# Obsidian Graph Navigator

> Find the smallest useful reading set in an Obsidian-compatible project vault by following indexes, wikilinks, metadata, and task scope. Use before loading project notes for planning, architecture, security, implementation, or handoff. Do not read the whole vault when a focused path can answer the task.

- Skill: `ashermahonin/obsidian-graph-navigator` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add ashermahonin/obsidian-graph-navigator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ashermahonin/obsidian-graph-navigator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: ashermahonin (https://skillmd.com/u/ashermahonin)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/ashermahonin/obsidian-graph-navigator

---


# Obsidian Graph Navigator

## Purpose

Traverse the project vault through indexes and wikilinks, then return the smallest set of notes that answers the current task. Do not load the whole vault when a focused path is available.

## Navigation request

1. Read `references/graph-navigation.md`.
2. Identify the active task type (intake, research, architecture, decomposition, implementation, QA, review, security, ops, post-launch).
3. Open `00-home.md` in the project vault as the MOC entrypoint. Pull the relevant phase MOC links (Intake, Discovery, Product flow, Architecture, Delivery, Quality, Existing product).
4. Verify the vault layout exists; if missing, route to `documentation-graph-curator` to seed it.

## Graph traversal

1. Pick the phase MOC matching the task type.
2. Walk wikilinks one hop out from the MOC; collect notes whose frontmatter `type` matches the current artifact need.
3. For each candidate, read only the section that matches the current goal (frontmatter + first heading), not the whole file. Defer deep reads until proven necessary.
4. Filter via frontmatter properties: `status`, `phase`, `service`, `owners`, `depends_on`, `risk_level`, `updated_at`. Reject stale notes (older than relevant cutoff) unless they hold an active ADR or unresolved risk.
5. Build a reading order: dependencies first (e.g., `08-product-scope` before `11-functional-requirements`), then current artifact, then related ADRs and risk entries.
6. Emit the reading list and stop. Hand the list (paths + sections) to the requesting skill instead of reading everything into the parent context.

## Context limits

- Use Context7 MCP only if a referenced external doc must be re-validated.
- Keep a decision trace: which MOC pages were walked, which links were followed, which notes were filtered out and why.
- Never reload a note already in context; reuse it.
- Never silently widen the reading set beyond the requesting skill's need.

## Reading set

- Ordered reading list with file paths, section anchors, and frontmatter snapshot
- Filtered-out list with reason (stale, off-phase, wrong service, unrelated)
- Open ADRs and risks intersecting the task
- Graph hygiene flags (broken wikilinks, missing frontmatter, drifted properties)

## Ready when

- No "load entire vault" prompts.
- No reading list that re-includes notes already in the requester's context.
- No reading list without owner/status/phase filtering when those exist.
- No silent ignoring of broken wikilinks; raise them to `documentation-graph-curator`.

## Handoff

Hand the ordered reading list to the requesting skill. Hand broken-link or stale-metadata findings to `documentation-graph-curator`.

## References

- `references/graph-navigation.md`: MOC topology, phase-to-MOC mapping, frontmatter filters, hygiene flags.