Obsidian Vault Curator

Bring structure to a messy Obsidian vault without flattening its history. Start with read-only analysis. Then propose one small, reviewable write slice.

Runtime requirement

This skill declares python3 on PATH as a host requirement.

• The requirement is surfaced in metadata as requires.bins: ["python3"].
• On macOS, the metadata includes a Homebrew install hint.
• On Linux, install Python 3 with your distro package manager, for example sudo apt install python3, then verify python3 --version.
• On Windows, install Python from the official Python Install Manager or with winget install Python.Python.3.14, then open a new terminal and verify that python3 --version works. If only python works, add a python3 alias or shim on PATH before using this skill.
• The bundled helper scripts in scripts/ use only the Python standard library.
• No extra Python packages are required.
• No exact minor version is currently pinned. The helpers were validated with Python 3.11+ and tested locally on macOS against Python 3.14.4.
• Windows support is documented, but the full workflow has not yet been live-validated on Windows.

Core rules

• Default to read-only.
• Never delete notes unless the user explicitly asks.
• Never rewrite more than one write slice at a time. A write slice should stay within 3-10 related notes. Multiple-slice content rewrites in one pass count as mass-rewrite and require explicit user approval.
• Never run parallel write agents.
• Treat findings of possible secrets, credentials, tokens, or live identifiers as hypotheses until the main agent verifies the exact note content.
• Prefer superseded_by over overwrite.
• Preserve historical context.
• Treat doc_kind and status as separate concerns.
• Prefer controlled YAML frontmatter over ad-hoc tags for lifecycle state.
• Verify links and metadata after each write slice.

Workflow

1. Always read references/status-schema.md and references/classification-rubric.md before classifying any note, including a single-note task.
2. If the task touches more than a few notes or spans more than one folder, read references/workflow.md.
3. If the user wants dashboards or views, read references/bases-views.md.
4. If the target area is too large for one context-bounded pass, read references/subagents.md. Keep subagents read-only by default. Keep writes in the main agent unless the user has explicitly approved writes from one specific named subagent for this task.
5. If findings need to be merged across slices or reviewed by a human, read references/output-format.md.
6. For larger areas, split the work into context-bounded slices by folder, topic cluster, or review queue instead of loading the whole vault at once.
7. Inventory the target area before proposing edits. Use scripts/inventory_slice.py when repeated folder scans would otherwise waste context.
8. Suggest canonical pages, status changes, supersession links, and the smallest safe write slice. Use scripts/generate_migration_plan.py with the JSON output of scripts/inventory_slice.py when the user wants a structured migration slice proposal.
9. Before structural writes and after every write slice, verify metadata with scripts/validate_frontmatter.py, verify links with scripts/check_links.py, and reassess whether the chosen canonical pages still make sense.

Output shape

When curating a vault area, return these sections unless the user asks for a different format:

Use this shape for a single-pass curation reply. Use the subagent shape from references/output-format.md when running as a subagent. Use the final main-agent summary shape from references/output-format.md only when merging results from multiple subagent slices.

1. Current state — what exists now, including ambiguity or conflicts.
2. Classification recommendations — suggested status, doc_kind, and canonical candidates.
3. Risks and contradictions — what could be damaged, misclassified, contradictory, or is still unverified.
4. Next write slice — the smallest safe set of edits.
5. Verification — what to check after changes.

Decision rules

• If a note is still useful but no longer leading, mark it historical and point to a successor.
• If a note describes a desired future state, mark status: concept and choose doc_kind separately.
• If validity is unclear, mark it needs-review first instead of guessing.
• If an old note may become useful again, prefer reactivatable over burying it.
• If multiple notes cover the same topic, nominate one canonical page and propose the rest as supporting or historical pages.
• If the vault already has a schema, adapt to it instead of forcing a new one.
• If a subagent flags possible secrets, credentials, tokens, or live identifiers, verify the exact text in the main agent before escalating or editing.

Safe operating mode

Use small, reviewable steps:

• classify before moving or merging
• move before rewriting when structure is the real problem
• create indexes and canonical pages before cleanup
• keep historical pages reachable
• ask before touching attachments, .obsidian/, or folder restructures that touch more than one folder or more than 10 notes

Built-in helpers (require installed python3)

If python3 is unavailable, the bundled helper scripts cannot run. Continue with the manual workflow and do not pretend a helper script ran.

• scripts/inventory_slice.py — scan one vault slice and summarize note counts, missing metadata, status/doc_kind coverage, title duplicates, exact-content duplicate clusters, and high-signal sensitive candidates that still require main-agent verification.
• scripts/validate_frontmatter.py — verify the controlled frontmatter shape on one slice before or after edits.
• scripts/generate_migration_plan.py — turn the JSON output of scripts/inventory_slice.py into a small, reviewable migration plan.
• scripts/check_links.py — inspect wikilinks in one slice and flag unresolved targets before or after moves. Treat results as slice-local unless the checked slice includes every possible target note.

Large-section strategy

When the user wants work on a broader vault area:

1. keep one main agent as orchestrator
2. split the area into bounded slices
3. use read-only subagents for inventory, classification, contradiction checks, and link review
4. merge findings in the main agent
5. execute one write slice at a time in the main agent

Prefer this over giving one agent the whole vault context at once.

References

• references/status-schema.md — controlled fields, values, and examples
• references/classification-rubric.md — note-by-note classification heuristics
• references/workflow.md — end-to-end curation and migration flow
• references/bases-views.md — suggested Bases views and review queues
• references/subagents.md — safe delegation model for larger vault jobs
• references/output-format.md — standard subagent return shape, merge rules, and human-review gates