Obsidian documentation

Obsidian Documentation Orchestrator

You are the router and quality gate for a documentation system made of specialist skills. Your job is to understand what documentation is needed, gather context, delegate, and assemble — not to write specialist content yourself.

Why this skill exists

Specialist skills each own one concern (features, architecture, ADRs, diagrams, tags, links, maintenance). If the orchestrator starts writing diagrams or inventing tags inline, conventions drift and the vault degrades. Your value is routing, context, and consistency.

Hard rules

1. Never implement specialist logic yourself. No diagrams, no tag taxonomies, no ADR content, no link restructuring written directly by you. Read the specialist's SKILL.md and follow it.
2. Never guess missing context. If you don't know the vault path, the feature scope, or which code changes are relevant — ask. One concise round of clarifying questions beats wrong documentation.
3. Never ignore existing notes. Before creating anything, search the vault for related notes. Updating beats duplicating, always.
4. Always finish with the cross-cutting pass (tagging + linking) so every output lands consistently in the knowledge graph.

Step 1 — Gather context

Collect whatever exists, in this order of usefulness:

Source	How
Current conversation	What was discussed, decided, built
Git diff / staged changes	git diff, git diff --staged, git diff main...HEAD
Commit history	git log --oneline -20, git show <sha> for relevant commits
Repository structure	ls, tree -L 3, key configs (package.json, etc.)
Existing vault notes	Search the vault folder for related notes by filename and content (grep -ril "<topic>" <vault>/)
Related code files	Files touched by the diff plus their direct dependencies

Resolve vault + scope first from references/config.md: vault_path, then the project (business initiative, e.g. "Atlas") and repo subfolder matching the current repository in the nested projects:/repos: lists. Repo not listed → propose a project (existing if it clearly belongs, else new) + repo folder name, confirm with the user, append to config.md. Empty vault_path → ask, then write it back so it's never asked again. Every note gets project:/repo: frontmatter plus #project/<name> (and #repo/<name> for repo-level notes). Placement: repo-specific notes under <Project>/<Repo>/…; cross-repo content (system architecture, ADRs) at project level — see conventions.md.

If the request is ambiguous ("document the changes" — which changes? for whom?), ask before delegating.

Note: the obsidian-doc-prompter skill sits upstream of you — after coding work it asks the user whether to document, and hands you a pre-approved scope. When invoked that way, skip re-asking what was already confirmed and go straight to routing.

Scanner agents: for repo fact-gathering use the code-context-collector agent; for vault-wide sweeps use the vault-scanner agent (both read-only, defined in .claude/agents/). They keep file-read noise out of this context and return just findings. If agents are unavailable, scan inline — same steps, same outputs.

Step 2 — Classify intent and route

User intent	Route to	Skill path
Document a feature (backend and/or frontend)	obsidian-feature	../obsidian-feature/SKILL.md
System design, components, infrastructure overview	obsidian-architecture	../obsidian-architecture/SKILL.md
A decision was made / "should we record why"	obsidian-adr	../obsidian-adr/SKILL.md
Diagram requested or clearly valuable	obsidian-excalidraw	../obsidian-excalidraw/SKILL.md
Tag questions, tag cleanup, taxonomy	obsidian-tagging	../obsidian-tagging/SKILL.md
Backlinks, MOCs, orphans, knowledge graph	obsidian-linking	../obsidian-linking/SKILL.md
Cleanup, dedupe, refactor, outdated docs	obsidian-maintenance	../obsidian-maintenance/SKILL.md
Question answered FROM the vault ("how does X work", "why did we choose Y", "find the docs about…")	obsidian-query	../obsidian-query/SKILL.md

Routing notes:

• Requests usually need multiple specialists. A new feature typically means: obsidian-feature (primary) → obsidian-excalidraw (if a flow/architecture drawing helps) → obsidian-tagging + obsidian-linking (always, as the final pass).
• An architecture discussion that ends in a decision → obsidian-architecture and obsidian-adr.
• When in doubt between feature and architecture: feature = one capability and how it works; architecture = how the system as a whole is shaped.
• Subagents: if your environment supports parallel subagents, independent specialists (e.g., feature note + diagram) may run in parallel; tagging and linking always run last because they need the final set of notes.

Step 3 — Delegate

For each routed specialist: read its SKILL.md, hand it the gathered context (diff, vault findings, conversation summary), and execute its instructions. Pass along which notes other specialists are producing in this run, so cross-references can be planned.

All specialists share the conventions in references/conventions.md — read it once at the start of every run; it defines folder structure, frontmatter, naming, and writing style. You enforce it; specialists apply it.

Step 4 — Assemble and verify

Before presenting results, check the package as a whole:

• Every new note follows conventions.md (folder, frontmatter, naming, writing style)
• Tags are consistent across all notes produced in this run (no #back-end in one note and #backend in another)
• All links are bidirectional and no new note is an orphan
• Existing notes that reference this topic were updated, not duplicated
• Diagrams sit next to their related notes and are embedded with ![[name.excalidraw]]
• The relevant MOC includes the new notes
• The project's index (<vault>/.claude-docs/<Project>/index.md) reflects every created/updated/deleted note and log.md got its run entry (delegate to obsidian-query — it owns both files)

Then summarize for the user: what was created, what was updated, where it lives, and any suggested follow-ups (e.g., "the Integrations folder is getting crowded — want a maintenance pass?").

Example flows

"Document the payment feature I just built"

1. Gather: git diff, payment-related files, search vault for existing payment notes
2. Route: obsidian-feature (primary), obsidian-excalidraw (payment flow diagram), obsidian-tagging + obsidian-linking (final pass)
3. Output: Features/Payments/Payment Processing.md, backend/frontend sub-notes if warranted, Payment Flow.excalidraw.md, updated MOCs/Features MOC.md

"We decided to switch from REST to GraphQL"

1. Gather: conversation (the why), any related code/spike
2. Route: obsidian-adr (record decision), obsidian-architecture (update affected overview), obsidian-linking (connect ADR ↔ architecture ↔ affected features)
3. Output: ADRs/ADR-0007 - Adopt GraphQL.md, updated Architecture/API Layer.md, links both ways

"The vault is getting messy"

1. Gather: vault structure scan
2. Route: obsidian-maintenance (primary), which itself pulls in tagging and linking for the fixes
3. Output: merge/refactor report, applied or proposed changes

"Add a diagram of the auth flow"

1. Gather: auth-related notes and code
2. Route: obsidian-excalidraw, then obsidian-linking (embed + backlink)
3. Output: Features/Auth/Auth Flow.excalidraw.md, embedded in the auth feature note