Obsidian Vault Curator#

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

For multi-note work, use read-only subagents by default. Keep the main agent as the only writer. Use one bounded slice per subagent and separate passes for inventory, comparison, classification, verification, and sensitive-content review.

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.
• Use subagents by default for multi-note or heterogeneous work.
• Keep inventory first, then read-only review, then writes.
• Never delete notes unless the user explicitly asks.
• Never rewrite more than one write slice at a time. A write slice must 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 sensitive content (see references/subagents.md glossary) as hypotheses until the main agent verifies the exact note content.
• Never rely on a global forced subagent model. Reuse the main-agent model when it fits; change model only when a specific role clearly benefits.
• 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.

Subagent policy#

• Keep the main agent in control. Use subagents as read-only orchestrator workers, not as handoffs.
• The main agent may handle the work alone only when the work fits in one explicit bounded 3-10 note slice with no cross-slice comparison and no sensitive-content risk. Otherwise inventory first.
• If the task spans multiple slices, split it. Do not keep multiple large slices in the main agent working memory when subagents can inspect them separately.
• If the task is heterogeneous, use separate passes instead of one mixed prompt.
• Use separate passes for inventory, duplicate clustering, classification, review, link verification, and sensitive-content review.
• Treat all subagent findings as candidates only; the main agent must verify exact note text before any write.
• Never start write work before inventory plus read-only review are complete.
• Never use subagents for deletes, moves, renames, write slices, or exact-text verification of sensitive content. Subagents may flag sensitive candidates as hypotheses; only the verbatim verification happens in the main agent.
• Never mix models within one slice unless there is a clear reason.
• Keep writes serialized and never parallelize write agents.
• Cap classifier-reviewer rounds at 2 per slice. If they still disagree after round 2, escalate to human review.
• Read-only slices must stay within 200 notes per subagent call. Write slices must stay within 3-10 related notes.
• Use the named roles from references/subagents.md ( inventory-agent, classifier-agent, curation-reviewer, link-verifier, migration-planner, duplicate-cluster-agent, sensitive-content-agent, and threshold-based structural-move-planner) instead of ad-hoc subagent prompts.
• Use the return shape defined in references/output-format.md unless the parent task explicitly asks otherwise.

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 spans multiple notes or requires cross-note comparison, read references/workflow.md.
3. If the user wants dashboards or views, read references/bases-views.md.
4. If the task spans multiple notes, multiple folders, cross-note comparison, duplicate risk, or heterogeneous material, read references/subagents.md and start with an inventory subagent. Only skip that when the work is already one explicit bounded 3-10 note slice with no cross-slice comparison. Keep subagents read-only by default. Keep all writes in the main agent. Subagents never write, even with user approval. If the user asks a named subagent to write, refuse the delegation and execute the write yourself in the main agent.
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 bounded slices by note cluster, topic cluster, or review queue. Use folder boundaries only when they are the natural boundary of a bounded slice.
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.
10. If a migration touches more than 50 notes or spans more than 3 vault top-level directories, use structural-move-planner instead of a normal migration-planner pass.
11. When spawning a subagent, use the labeled packet structure from references/subagents.md and the concrete examples from references/subagent-packets.md.

Output shape#

When curating a vault area, use the context router and shapes defined in references/output-format.md unless the user asks for a different format.

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 sensitive content (see references/subagents.md glossary), 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 or any task involving multiple notes:

1. keep one main agent as orchestrator
2. split the area into bounded slices
3. use read-only subagents for inventory, duplicate clustering, classification, contradiction checks, link review, and sensitive-content review, one bounded slice per subagent
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. If the area cannot be answered confidently from the current instructions and one bounded slice of material, inventory first, then fan out into separate slices.

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/subagent-packets.md — concrete subagent packet examples for deterministic read-only delegation
• references/output-format.md — standard subagent return shape, merge rules, and human-review gates