Skills
skills/synapsync/synapse_registry/obsidian-md-standard

obsidian-md-standard

SKILL.md

Obsidian Markdown Standard

Purpose

Define a shared specification for all markdown documents generated by SynapSync skills, ensuring every .md output is Obsidian-native — with rich YAML frontmatter, wiki-links, bidirectional references, living document patterns, trackable IDs, and metric tables. When multiple skills produce documents for the same project, the result is an interconnected knowledge graph in Obsidian, not a collection of isolated files.

This skill is a specification — it is not invoked directly by users. Other skills reference it and embed the relevant compact profile into their output instructions.

When to Use This Skill

  • Skill authors: When creating or updating a SynapSync skill that writes .md files to {output_base}
  • Reference: When validating that generated documents follow the Obsidian-native standard
  • Not for direct invocation: Users do not call this skill — it is consumed by other skills

Specification

1. Universal Frontmatter Schema

Every generated .md document MUST include YAML frontmatter with these fields:

Required Fields

---
title: "Document Title"
date: "YYYY-MM-DD"           # Creation date
updated: "YYYY-MM-DD"        # Last modification date
project: "{project-name}"     # Kebab-case project identifier
type: "{document-type}"       # From the Document Type Taxonomy (section 2)
status: "draft"               # draft | active | completed | superseded | archived
version: "1.0"                # Document version (semver-ish)
tags:
  - "{project-name}"
  - "{type}"
  - "{additional-tags}"
changelog:
  - version: "1.0"
    date: "YYYY-MM-DD"
    changes: ["Initial creation"]
related:
  - "[[related-document-1]]"
  - "[[related-document-2]]"
---

Extended Fields (by document type)

Field Used By Description
sprint sprint-plan, progress Sprint number (integer)
phase sprint-plan, execution-plan Phase identifier (e.g., "1.1")
progress sprint-plan, progress Completion percentage (0-100)
previous_doc sprint-plan, retrospective "[[SPRINT-1-name]]"
next_doc sprint-plan "[[SPRINT-3-name]]"
parent_doc any child document "[[PROGRESS]]" or "[[README]]"
vision_ref sprint-plan, progress "[[growth-vision]]"
retro_refs sprint-plan, progress ["[[RETRO-1-name]]"]
metrics sprint-plan, retrospective, progress Inline metric summary object
approved_by any gated document Approver name
approved_date any gated document "YYYY-MM-DD"
severity bug-fix analysis critical / high / medium / low
scope_modules refactor analysis List of affected modules

2. Document Type Taxonomy

Type Description Typical Skills
analysis General analysis document universal-planner, project-planner
conventions Project patterns and conventions universal-planner, project-planner
requirements Functional/non-functional requirements universal-planner (NEW_PROJECT), sdlc-planner
architecture Architecture decisions and design universal-planner, sdlc-planner
plan Strategic planning document universal-planner, project-planner
execution-plan Concrete task breakdown universal-planner, project-planner
sprint-plan Sprint-level task plan universal-planner, project-planner
progress Master progress dashboard universal-planner, universal-planner-executor
technical-report Code/module analysis report code-analyzer
refactor-plan Refactoring recommendations code-analyzer (v3)
retrospective Sprint/project retrospective universal-planner, universal-planner-executor
decision-log Architecture/engineering decisions universal-planner-executor
data-model Entity relationships and storage sdlc-planner
flow-diagram Core flows and sequences sdlc-planner

3. Wiki-Link Convention

Inter-document references MUST use wiki-links. Markdown links are reserved for external URLs only.

Pattern Usage Example
[[filename]] Reference another document [[CONVENTIONS]]
[[filename#Section]] Reference a specific section [[ANALYSIS#Success Criteria]]
[[filename]] (v1.2) Reference a specific version [[SPRINT-1-foundation]] (v1.0)
[[filename|display text]] Aliased reference [[functional-requirements|FR Spec]]
[text](https://...) External URL only [Obsidian docs](https://obsidian.md)

Rules:

  • All inter-document references use [[wiki-links]], never [text](relative-path.md)
  • Filenames in wiki-links omit the .md extension
  • Wiki-links are case-insensitive in Obsidian but use the actual filename casing for clarity

4. References Section

Every generated document MUST end with a ## Referencias section. This section provides structured navigation between related documents.

## Referencias

**Parent:** [[PROGRESS]] | [[README]]
**Siblings:** [[SPRINT-1-foundation]], [[SPRINT-3-testing]]
**Children:** [[RETRO-2-core-implementation]]
**Input Documents:** [[CONVENTIONS]], [[ANALYSIS]]
**External:** [Relevant external link](https://...)

Categories (include only those that apply):

  • Parent: The document this one belongs to (e.g., PROGRESS for a sprint)
  • Siblings: Documents at the same level (e.g., other sprints)
  • Children: Documents spawned from this one (e.g., retro from sprint)
  • Input Documents: Documents this one was derived from
  • External References: External URLs relevant to this document

5. Living Document Pattern

Documents that evolve over time (sprint plans, progress dashboards, visions) follow the living document pattern:

Versioning: Track in frontmatter version field + changelog array.

Status transitions:

draft → active → completed → superseded → archived
Status Meaning
draft Initial creation, not yet reviewed
active Currently in use, may be updated
completed Work described is finished
superseded Replaced by a newer version (link to successor in related)
archived Historical record, no longer active

Update protocol: When modifying a living document:

  1. Bump the version field
  2. Update the updated date
  3. Add an entry to changelog
  4. Update status if the transition applies

6. ID System

Trackable IDs provide stable anchors for cross-referencing within and across documents.

Prefix Domain Example
FR- Functional Requirement FR-001, FR-002
NFR- Non-Functional Requirement NFR-001
ADR- / DEC- Architecture/Engineering Decision ADR-1, DEC-3
T- Task T-1.1.1, T-2.3.1
K- Retrospective: Keep K1, K2, K3
P- Retrospective: Problem P1, P2
L- Retrospective: Learning L1, L2
A- Retrospective: Action A1, A2
D- Technical Debt item D-001, D-002
M- Metric M-001, M-002

Rules:

  • IDs are scoped to the document they appear in (not globally unique)
  • Reference from another document: [[document-name#FR-001]]
  • Sequential numbering within each document
  • Once assigned, an ID is never reused in that document (even if the item is removed)

7. Bidirectional References

If document A references document B, then document B MUST reference document A.

Implementation:

  1. related array in frontmatter of both documents
  2. ## Referencias section at the end of both documents
  3. When generating multiple documents, ensure bidirectionality before finishing

Verification: After generating a batch of documents, check that for every [[X]] in document Y, document X contains [[Y]] in its related field or ## Referencias section.

8. Metric Tables

When reporting quantitative data, use the standard metric table format:

| Metric | Before | After | Delta | Status |
|--------|--------|-------|-------|--------|
| Test coverage | 72% | 89% | +17% | IMPROVED |
| Build time | 45s | 32s | -13s | IMPROVED |
| Bundle size | 2.4MB | 1.8MB | -0.6MB | IMPROVED |
| Open bugs | 12 | 8 | -4 | IN_PROGRESS |

Status values: NOT_STARTED | IN_PROGRESS | IMPROVED | DEGRADED | COMPLETED | AT_RISK

Use this format in: sprint plans (planned vs actual), retrospectives (before/after), progress dashboards (target vs current), technical reports (metrics section).

9. Graduation Gates

Sprint plans and phase-gated documents use checkbox-based graduation criteria:

## Graduation Gate

Sprint {N} is approved for completion when ALL criteria are met:

- [x] All tasks marked complete with passing verification
- [x] No open P0/P1 blockers
- [ ] Test coverage >= 85% for new code
- [ ] Build passes in CI
- [ ] Code reviewed and approved
- [ ] PROGRESS.md updated with final metrics

Rules:

  • Gates use - [ ] / - [x] checkbox syntax
  • Criteria must be verifiable (not subjective)
  • A document with unmet gates cannot transition to completed status
  • Gates are checked by the executor skill (universal-planner-executor) or manually

10. Sequential Numbering

Documents within the same directory that have a reading order MUST use numeric prefixes:

requirement-analysis/
├── 01-problem-definition.md
├── 02-goals-and-success-metrics.md
├── 03-stakeholders-and-personas.md
├── 04-functional-requirements.md
├── 05-non-functional-requirements.md
├── 06-assumptions-and-constraints.md
└── 07-out-of-scope.md

Rules:

  • Use two-digit zero-padded prefixes: 01-, 02-, ..., 99-
  • Sequential numbering indicates reading order, not priority
  • Sprints use their sprint number: SPRINT-1-name.md, SPRINT-2-name.md
  • Retrospectives pair with sprints: RETRO-1-name.md

11. Carried Forward Rules

When a document is part of a sequence (e.g., Sprint 2 follows Sprint 1), include a section for items carried from the previous document:

## Carried Forward from [[SPRINT-1-foundation]]

The following items were not completed in Sprint 1 and are carried into this sprint:

- [ ] T-1.2.3 — Implement caching layer (blocked by ADR-3 in Sprint 1)
- [ ] T-1.3.1 — Add integration tests for auth module

**Decisions inherited:**
- DEC-2: Use Redis for session storage ([[SPRINT-1-foundation#DEC-2]])

Rules:

  • Only Sprint 2+ and sequential documents include this section
  • Reference the source document with wiki-links
  • Include specific task IDs and decision IDs
  • Place this section after the sprint header but before the first phase

12. Retrospective Template

When a skill generates a retrospective document (optional feature in universal-planner and universal-planner-executor):

---
title: "Retrospective: Sprint {N} — {Sprint Name}"
date: "YYYY-MM-DD"
updated: "YYYY-MM-DD"
project: "{project-name}"
type: "retrospective"
status: "active"
version: "1.0"
sprint: {N}
previous_doc: "[[SPRINT-{N}-name]]"
tags:
  - "{project-name}"
  - "retrospective"
  - "sprint-{N}"
changelog:
  - version: "1.0"
    date: "YYYY-MM-DD"
    changes: ["Initial retrospective"]
related:
  - "[[SPRINT-{N}-name]]"
  - "[[SPRINT-{N+1}-name]]"
  - "[[PROGRESS]]"
---

# Retrospective: Sprint {N} — {Sprint Name}

## Context
{Brief description of what the sprint aimed to accomplish and its outcome}

## Keep (What Went Well)
- **K1**: {What to continue doing}
- **K2**: {What to continue doing}

## Problems (What Went Wrong)
- **P1**: {Issue encountered}
- **P2**: {Issue encountered}

## Learnings (What We Learned)
- **L1**: {Insight gained}
- **L2**: {Insight gained}

## Actions (What to Do Differently)
- **A1**: {Concrete action for next sprint} → Assigned to: {who}
- **A2**: {Concrete action for next sprint} → Assigned to: {who}

## Metrics

| Metric | Planned | Actual | Delta | Status |
|--------|---------|--------|-------|--------|
| Tasks completed | {N} | {N} | {+/-N} | {status} |
| {Custom metric} | {target} | {actual} | {delta} | {status} |

## Signals to Watch
- {Early warning indicator for next sprint}
- {Trend to monitor}

## Verdict
{One paragraph: was the sprint successful? Key takeaway for the team.}

## Referencias

**Parent:** [[PROGRESS]]
**Input Documents:** [[SPRINT-{N}-name]]
**Siblings:** [[RETRO-{N-1}-name]], [[RETRO-{N+1}-name]]

Domain Profiles

Each SynapSync skill that produces .md output embeds a compact profile from this standard into its ## Obsidian Output Standard section. Profiles are domain-specific subsets of the full specification, providing just the rules and templates relevant to that skill's output.

Planning Profile

For: project-planner, universal-planner

### Obsidian Output Rules (Planning)

All documents generated by this skill MUST follow the obsidian-md-standard:

1. **Frontmatter**: Every `.md` file includes the universal frontmatter schema (title, date, updated, project, type, status, version, tags, changelog, related)
2. **Types**: Use `conventions`, `analysis`, `plan`, `execution-plan`, `sprint-plan`, `progress`, `requirements`, `architecture` as appropriate
3. **Wiki-links**: All inter-document references use `[[filename]]` syntax — never `[text](relative-path.md)`
4. **Referencias**: Every document ends with `## Referencias` listing Parent, Siblings, Children, and Input Documents
5. **Living documents**: PROGRESS.md and sprint plans are living documents — bump `version`, update `changelog`, transition `status` on modification
6. **IDs**: Use FR-/NFR- for requirements, ADR- for architecture decisions, T- for tasks
7. **Bidirectional**: If document A references B, document B must reference A in `related` and `## Referencias`
8. **Metrics**: Use `| Metric | Before | After | Delta | Status |` format for all quantitative data
9. **Gates**: Sprint plans include `## Graduation Gate` with verifiable checkbox criteria
10. **Carried Forward**: Sprint 2+ includes `## Carried Forward from [[previous-sprint]]` for incomplete items
11. **Sequential numbering**: Use `01-`, `02-` prefixes where reading order matters

**Frontmatter template for sprint plans:**
```yaml
---
title: "Sprint {N}: {Name}"
date: "YYYY-MM-DD"
updated: "YYYY-MM-DD"
project: "{project-name}"
type: "sprint-plan"
status: "draft"
version: "1.0"
sprint: {N}
phase: "{active-phases}"
progress: 0
previous_doc: "[[SPRINT-{N-1}-name]]"
next_doc: "[[SPRINT-{N+1}-name]]"
parent_doc: "[[PROGRESS]]"
tags: ["{project-name}", "sprint-{N}", "sprint-plan"]
changelog:
  - version: "1.0"
    date: "YYYY-MM-DD"
    changes: ["Initial sprint plan"]
related:
  - "[[PROGRESS]]"
  - "[[EXECUTION]]"
  - "[[SPRINT-{N-1}-name]]"
  - "[[SPRINT-{N+1}-name]]"
---


### Technical Report Profile

**For:** `code-analyzer`

```markdown
### Obsidian Output Rules (Technical Reports)

All documents generated by this skill MUST follow the obsidian-md-standard:

1. **Frontmatter**: Every `.md` file includes the universal frontmatter schema (title, date, updated, project, type, status, version, tags, changelog, related)
2. **Types**: Use `technical-report` for REPORT.md, `refactor-plan` for REFACTOR.md
3. **Wiki-links**: When both REPORT.md and REFACTOR.md exist, cross-reference with `[[REPORT]]` / `[[REFACTOR]]`
4. **Referencias**: Every document ends with `## Referencias` listing related analysis documents
5. **Metrics**: Use `| Metric | Before | After | Delta | Status |` format for code quality metrics, complexity scores, and coverage data
6. **IDs**: Use D- for debt items in refactor plans
7. **Bidirectional**: If REFACTOR.md references REPORT.md, REPORT.md must reference REFACTOR.md

**Frontmatter template for REPORT.md:**
```yaml
---
title: "Module Analysis: {module-name}"
date: "YYYY-MM-DD"
updated: "YYYY-MM-DD"
project: "{project-name}"
type: "technical-report"
status: "active"
version: "1.0"
tags: ["{project-name}", "technical-report", "module-analysis", "{module-name}"]
changelog:
  - version: "1.0"
    date: "YYYY-MM-DD"
    changes: ["Initial analysis"]
related:
  - "[[REFACTOR]]"
---


### SDLC Profile

**For:** `sdlc-planner`

```markdown
### Obsidian Output Rules (SDLC)

All documents generated by this skill MUST follow the obsidian-md-standard:

1. **Frontmatter**: Every `.md` file includes the universal frontmatter schema (title, date, updated, project, type, status, version, tags, changelog, related)
2. **Types**: Use `requirements` for Phase 1 files, `architecture` for Phase 2 files, `plan` for future-phases
3. **Wiki-links**: All inter-document references use `[[filename]]` — README links to all children via wiki-links
4. **Referencias**: Every document ends with `## Referencias` with bidirectional links to sibling and parent documents
5. **Sequential numbering**: Maintain `01-`, `02-` prefixes for reading order
6. **IDs**: Use FR-/NFR- for requirements, ADR- for architecture decisions
7. **Bidirectional**: All 17 documents must have reciprocal references — README↔children, siblings↔siblings
8. **Parent document**: README.md serves as the parent; all other documents include `parent_doc: "[[README]]"` in frontmatter

**Frontmatter template for requirement files:**
```yaml
---
title: "{Document Title}"
date: "YYYY-MM-DD"
updated: "YYYY-MM-DD"
project: "{project-name}"
type: "requirements"
status: "active"
version: "1.0"
parent_doc: "[[README]]"
tags: ["{project-name}", "requirements", "sdlc", "{specific-tag}"]
changelog:
  - version: "1.0"
    date: "YYYY-MM-DD"
    changes: ["Initial generation"]
related:
  - "[[README]]"
  - "[[{sibling-documents}]]"
---


### Sprint Execution Profile

**For:** `universal-planner-executor`

```markdown
### Obsidian Output Rules (Sprint Execution)

When modifying sprint documents and PROGRESS.md, follow the obsidian-md-standard:

1. **Frontmatter maintenance**: When updating a sprint file, bump `version`, update `updated` date, add `changelog` entry, update `status` and `progress`
2. **Status transitions**: Move status through `draft → active → completed` as work progresses
3. **Decision Log**: Decisions logged with DEC- IDs include wiki-links to the sprint and task that triggered the decision
4. **Metrics**: Use `| Metric | Before | After | Delta | Status |` format when recording actual vs planned metrics
5. **Gates**: Verify all `## Graduation Gate` criteria before marking a sprint `completed`
6. **Bidirectional**: When adding decision references or notes that mention other documents, ensure reciprocal links
7. **Wiki-links**: All document references in notes, decision logs, and completion summaries use `[[filename]]` syntax

**When completing a sprint, update frontmatter:**
```yaml
status: "completed"
progress: 100
version: "{bumped}"
updated: "YYYY-MM-DD"
changelog:
  - version: "{new}"
    date: "YYYY-MM-DD"
    changes: ["Sprint completed — all tasks done, gates passed"]


### Retrospective Profile

**For:** `universal-planner` (optional), `universal-planner-executor` (optional)

```markdown
### Obsidian Output Rules (Retrospective)

When generating a retrospective document:

1. **Frontmatter**: Include full universal schema plus `sprint`, `previous_doc` (the completed sprint)
2. **Type**: `retrospective`
3. **IDs**: Use K1-Kn (Keep), P1-Pn (Problems), L1-Ln (Learnings), A1-An (Actions)
4. **Metrics**: Use `| Metric | Planned | Actual | Delta | Status |` comparing sprint targets to outcomes
5. **Wiki-links**: Reference the completed sprint, next sprint, and PROGRESS with wiki-links
6. **Bidirectional**: The completed sprint's `related` and the PROGRESS `retro_refs` must link back to this retrospective
7. **Referencias**: Include Parent (PROGRESS), Input (completed sprint), Siblings (other retros)

See the full retrospective template in the obsidian-md-standard specification (Section 12).

Sync Profile

For: obsidian-sync

### Obsidian Output Rules (Sync)

When syncing documents to Obsidian:

1. **Frontmatter enrichment**: If a document has minimal frontmatter (only title/date/project/type/tags), enrich it with the full universal schema (add updated, status, version, changelog, related)
2. **Frontmatter preservation**: If a document already has rich frontmatter, preserve all existing fields — only add missing ones
3. **Frontmatter generation**: If a document has no frontmatter, generate the complete universal schema
4. **Wiki-link preservation**: Never convert `[[wiki-links]]` to `[markdown](links)` — preserve them exactly
5. **Type inference**: Map document content to the 14-type taxonomy defined in the standard
6. **Cross-reference validation**: After syncing a batch of files, verify that `related` fields and `## Referencias` sections are bidirectional — if A references B, B should reference A
7. **Status**: New documents get `status: "active"`, documents with existing status are preserved

Compliance Checklist

When validating that a skill's output follows this standard:

  • Every .md file has YAML frontmatter with all required fields
  • type field uses a value from the Document Type Taxonomy
  • All inter-document references use [[wiki-links]] (no relative markdown links)
  • Every document ends with ## Referencias
  • Living documents have version and changelog maintained
  • IDs follow the prefix convention (FR-, ADR-, T-, K-, P-, L-, A-, D-, M-)
  • Bidirectional references are reciprocal
  • Metric tables use the standard format
  • Graduation gates use verifiable checkbox criteria
  • Sequential documents use 01-, 02- prefixes
  • Sprint 2+ documents include ## Carried Forward
  • No [text](relative-path.md) patterns for inter-document links

Version History

Version Date Changes
1.0 2026-02-11 Initial release with full Obsidian-native markdown specification
Weekly Installs
2
Repository
synapsync/synap…registry
GitHub Stars
4
First Seen
Feb 11, 2026
Security Audits
Gen Agent Trust HubPass
SocketPass
SnykPass
Installed on
amp2
opencode2
kimi-cli2
codex2
github-copilot2
claude-code2