| name | project-doc-bootstrap |
| description | Bootstrap a reusable repository documentation hierarchy for AI agents. Use when starting a new project, initializing repo docs, setting up CLAUDE.md and AGENTS.md, defining L1/L2/L3 documentation layers, creating AGENTS.md symlinks, or designing a fractal documentation system that helps AI quickly understand and safely update the codebase. |
Project Doc Bootstrap
Use this skill to set up a repository so future AI sessions can reach useful context in a few reads instead of re-deriving structure from source every time.
Default convention:
CLAUDE.md is the source of truth.AGENTS.md is a sibling symlink to CLAUDE.md.- Every directory that has a
CLAUDE.md must also have an AGENTS.md symlink as a sibling. This is a hard invariant — never create one without the other.
- Docs follow a fractal hierarchy: L1 root guide, L2 directory guides, L3 file-header notes only where needed.
If the user explicitly wants different filenames or a different source-of-truth file, adapt the convention. Otherwise default to CLAUDE.md + AGENTS.md.
When to Use
Use this skill when the user wants to:
- initialize a new project's AI-facing docs
- set up
CLAUDE.md / AGENTS.md
- design a directory-level documentation hierarchy
- make a repo easier for AI to understand and maintain
- standardize how docs are updated when files move or modules grow
- install a pre-commit hook that enforces doc-sync at commit time
Quick Start Workflow
- Read
references/blueprint.md to choose the documentation model.
- Read
references/workflow.md to bootstrap the repo in the right order.
- Read
references/templates.md for ready-to-copy templates: CLAUDE.md skeletons, symlink commands, and pre-commit hook scripts.
Core Outcomes
By the end of the task, the repo should have:
- one root
CLAUDE.md that explains architecture, rules, and the doc system
- one root
AGENTS.md -> CLAUDE.md symlink
- L2 docs for top-level and core module directories
- L2 docs for subdirectories that cross the documentation threshold
- explicit rules for when new L2 docs should be created later
- a pre-commit hook (
.git/hooks/pre-commit) that warns when staged source files are in a documented directory whose CLAUDE.md was not also staged (hook is local-only, not committed)
- a verification pass confirming symlink integrity, hook installation, and obvious gaps
Operating Rules
- Prefer small, stable documentation rules over exhaustive directory-by-directory prose.
- Keep each
SKILL.md and each L2 doc concise; move detail into references when it grows.
- Prefer symmetry for repeated trees such as locales, themes, provider categories, or parallel route groups.
- Do not create L2 docs for every leaf by default; stop when parent docs keep the tree understandable.
- Treat doc maintenance as part of code maintenance: if a directory changes shape, update its
CLAUDE.md in the same task.
Decision Rules
Create an L2 doc when a directory meets any of these:
- it is a top-level or core module directory
- it has 4 or more direct child items or source files
- it is a clear module boundary or high-frequency entrypoint
- its parent doc can no longer explain it within 3 reads
Do not create an L2 doc when all of these are true:
- the directory has only 1-3 files
- it is a leaf route or narrow implementation detail
- its parent doc already provides enough context
Delivery Checklist
Final Verification
Before closing the task, run these checks in order and do not skip any:
- List every
CLAUDE.md in the repo.
- For each
CLAUDE.md, verify a sibling AGENTS.md symlink exists and points to that CLAUDE.md.
- Verify
.git/hooks/pre-commit exists and is executable.
- Spot-check 2-3 representative L2 docs for format consistency.
- Report what was intentionally left undocumented and why.
Use the audit commands in references/templates.md to automate steps 1-2.
