A Claude Skill that atomizes a software-project spec into a PARA-style Obsidian vault — folders, Bases, templates, an AGENTS.md briefing for future AI sessions — in one command. Zero copy-paste.
Requires Claude Code, Claude Desktop, or any Claude environment that supports skills.
A 1500-line spec.md is a write-once, read-never artifact. The same content split into atomic notes with queryable frontmatter? Navigable, linkable, AI-friendly.
spec.md
└── 1,847 lines of headings,
code blocks, tables,
open questions buried
on line 1,432, risks on
line 1,609, and the
whole thing has been
untouched since you
wrote it 3 months ago.
vault/
├── 00_Index/
│ ├── HOME.md
│ ├── AGENTS.md
│ └── MOCs/Project MOC.md
├── 10_Projects/Project/
│ ├── Project Charter.md
│ ├── Architecture/ (3)
│ ├── Brief/ (4)
│ ├── Specs/ (9)
│ ├── Open Questions/ (6)
│ ├── Risks/ (5)
│ └── Plans/ (6)
└── _Bases/
├── Open Questions.base
├── Risks.base
└── Project Tracker.base
Give Claude (with this skill installed) a project spec — or just a one-liner about a project you're about to start.
The skill handles the full range of "I have something to start with" cases — from a formal spec down to a single sentence.
| Mode | Trigger | Output |
|---|---|---|
| spec-driven | Markdown / Word / PDF spec | ~50 atomized notes. Charter populated. |
| brief-driven | Slack post / transcript / multi-paragraph brief | ~20 atomized notes. Charter populated from brief. |
| one-liner | A sentence ("a self-hosted Vercel for Node services") | Scaffold only. Charter seeded with the description. |
| skeleton | Truly no description provided | Empty Charter shell. Rare. |
Two iterations of the skill across three test cases. Six gaps surfaced in iteration 1; every one fixed with a concrete change traceable to subagent feedback.
verify subcommand)| Test case | v1 baseline | v2 (current) |
|---|---|---|
| spec-driven 286-line technical spec |
46 notes, ad-hoc layout, Charter left blank | 55 notes, full PARA atomization, Charter populated from Executive Context |
| one-liner no spec, sentence-only |
Defaulted to skeleton mode, dropped the user's pitch | Charter seeded with the user's description via charter_seed |
| existing vault add 2nd project |
HOME.md / AGENTS.md edited manually with regex patches | Script auto-splices HOME, rewrites AGENTS as project-agnostic |
Same test (existing-vault add-second-project), independent subagent runs, v1 vs. v2:
"v1's only existing-vault behavior is skip files that exist. Every add-project-to-existing-vault use ends up requiring manual sed/python patches to splice the new project into Active Projects + MOC list + AGENTS. AGENTS is fundamentally single-project shaped."
"Script reported ~ HOME.md (Updated HOME.md with Tessellate). Inspection shows both wikilinks added under Active Projects and Maps of Content, with existing entries preserved verbatim. Script reported ~ AGENTS.md (rewritten as project-agnostic). All paths now read 10_Projects/<Project>/... instead of being hardcoded."
Full methodology, all six closed gaps, and per-run timing data: benchmarks/
Three ways to use it, depending on how you work.
Download obsidian-vault-scaffolder.skill from Releases and install with claude skill install. Then ask Claude to scaffold a vault for your next project.
Clone the repo, point your Claude config at the directory. Useful if you want to customize the templates or extend the atomization playbook.
The scaffolder works without Claude. python3 scripts/scaffold_vault.py --config config.json produces the folder layout, Bases, and templates. The atomization is the part you'd lose.
Five rules that make the vault queryable, navigable, and AI-friendly. Full docs in the repo.
00_Index, 10_Projects, 30_Resources) so they sort predictably.type: is non-negotiable on every note. Bases break without it.Risk — X.md, Open Question — X.md.AGENTS.md exists so future AI agents have a one-stop briefing on vault conventions.