Scaffold the documentation tree
Create the canonical documentation tree and its seed READMEs, so that every later document has a
legal home before anyone has to invent one. Reference: references/structure.md — the tree, the
filename grammar, and the freeze list; read it when the canonical tree is in question. The
docs root defaults to docs/; read it from
.ai-badger/config.json's docs.root if the project sets one.
What a finished scaffold IS — four parts, in this order:
- The canonical tree, every directory present, none extra.
- A root
README.md — a complete map: one row per directory, no omissions.
- One
README.md per directory, each a complete map of that directory.
- One ledger entry per seeded file, if the project keeps a ledger, so the next person's check is
green from the first commit.
Seeded READMEs are meant to be edited. They carry no generated-file header and no golden test.
Steps
- Inventory the current tree against the canonical one. Postcondition: you have a written
list of missing and extra paths. If the list is empty on both sides, the tree is already
canonical — say so and stop; you are not the right skill.
- Create every missing directory. Postcondition: each one exists and is a directory. A
path that collided with an existing file is resolved one path at a time — never by deleting or
re-running blind.
- Structure gate. Re-run the inventory from step 1 and do not proceed until it comes back
empty — no content is written before it does. Content written into a wrong tree has to be
moved, and moving it costs the file's history on every file.
- Write the root README and each directory README as complete, visual-first maps.
- Root README: Keep it concise and low-noise: a high-level architecture/flow diagram authored with
archify (fall back to Mermaid only when Node.js 18+ or the skill is unavailable, or the diagram must render inline), quick start snippet, capabilities matrix, and clear links to dedicated Diátaxis pages.
- Directory READMEs: One row per file, describing purpose directly without fluffy prose.
- Humanization: Apply
humanizer rules — active verbs, no em-dash filler, no empty copulas (serves as).
Postcondition: every file in each governed directory appears in its parent README, and every relative link in what you wrote resolves to a path that exists. Check both by hand; a missing entry is a document nobody will find.
- Record the seeded files in the project's documentation ledger, if it has one.
Postcondition: every seeded file has an entry, and the ledger's own consistency check is
green. An unrecorded seed makes the very next person's check fail.
Scripts versus judgement
A step whose output is checkable is a script call, where the project has a script. A step needing
judgement is prose followed by a check of its postcondition.
Never script: what a directory is for. A generated purpose line reads like a decision and is
not one, and nobody re-opens it.
Do not put a script inside this skill directory. Documentation tooling, if a project has any,
belongs in the project's scripts directory and is bound through .ai-badger/config.json's docs
map — see extensions/ledger/.
Where reference material lives
A skills directory registers exactly one nesting level, and a directory without a SKILL.md is
silently ignored rather than erroring. Verified across the agents ai-badger supports. So
when placing a skill's reference material, put it in a references/ subdirectory inside
that skill, which ships
with it — never in a sibling directory beside it, which would never be indexed and would never be
delivered. The same rule applies to the documentation tree you are creating: nothing is picked up
because it is nearby.
Gotchas
No environment-specific gotchas known.
Red flags — STOP
- Writing any document before the structure inventory comes back empty
- Adding a directory the canonical tree does not have, "because this repo needs it"
- A directory README that lists the interesting files instead of all of them
- Putting a script inside this skill directory
- Creating or touching content under a frozen build-input directory — read the freeze list in
references/structure.md when a build-input path is in question
- Reporting the scaffold done with seeded files the ledger does not know about
1---2name: scaffold-documentation-33description: >-4 Use when a repository has no documentation tree yet, or the canonical docs layout is missing,5 incomplete or was hand-created — "set up docs", "scaffold documentation", "create the docs6 structure", a fresh repo with only a README, a docs directory missing its directory READMEs, or a7 structure check that reports absent directories. Not for adding or editing a document (use8 update-documentation), and not for reorganising docs that already exist (use9 migrate-documentation).10version: 1.0.011author: ai-badger12license: MIT13platforms: [linux, macos, windows]14scope: default15metadata:16 source: https://skillmd.com/skills/arasz/scaffold-documentation-317 hermes:18 tags: [documentation, structure, diataxis, scaffolding]19 related_skills: [update-documentation, migrate-documentation]20---2122# Scaffold the documentation tree2324Create the canonical documentation tree and its seed READMEs, so that every later document has a25legal home before anyone has to invent one. Reference: `references/structure.md` — the tree, the26filename grammar, and the freeze list; read it **when the canonical tree is in question**. The27docs root defaults to `docs/`; read it from28`.ai-badger/config.json`'s `docs.root` if the project sets one.2930**What a finished scaffold IS** — four parts, in this order:31321. The canonical tree, every directory present, none extra.332. A root `README.md` — a **complete** map: one row per directory, no omissions.343. One `README.md` per directory, each a complete map of that directory.354. One ledger entry per seeded file, if the project keeps a ledger, so the next person's check is36 green from the first commit.3738Seeded READMEs are meant to be edited. They carry no generated-file header and no golden test.3940## Steps41421. **Inventory the current tree against the canonical one.** **Postcondition:** you have a written43 list of missing and extra paths. If the list is empty on both sides, the tree is already44 canonical — say so and stop; you are not the right skill.452. **Create every missing directory.** **Postcondition:** each one exists and is a directory. A46 path that collided with an existing *file* is resolved one path at a time — never by deleting or47 re-running blind.483. **Structure gate. Re-run the inventory from step 1 and do not proceed until it comes back49 empty** — no content is written before it does. Content written into a wrong tree has to be50 moved, and moving it costs the file's history on every file.514. **Write the root README and each directory README as complete, visual-first maps.**52 - **Root README:** Keep it concise and low-noise: a high-level architecture/flow diagram authored with `archify` (fall back to Mermaid only when Node.js 18+ or the skill is unavailable, or the diagram must render inline), quick start snippet, capabilities matrix, and clear links to dedicated Diátaxis pages.53 - **Directory READMEs:** One row per file, describing purpose directly without fluffy prose.54 - **Humanization:** Apply `humanizer` rules — active verbs, no em-dash filler, no empty copulas (`serves as`).55 **Postcondition:** every **file** in each governed directory appears in its parent README, and every relative link in what you wrote resolves to a path that exists. Check both by hand; a missing entry is a document nobody will find.565. **Record the seeded files** in the project's documentation ledger, if it has one.57 **Postcondition:** every seeded file has an entry, and the ledger's own consistency check is58 green. An unrecorded seed makes the very next person's check fail.5960## Scripts versus judgement6162A step whose output is checkable is a script call, where the project has a script. A step needing63judgement is prose followed by a check of its postcondition.6465**Never script:** what a directory is for. A generated purpose line reads like a decision and is66not one, and nobody re-opens it.6768Do not put a script inside this skill directory. Documentation tooling, if a project has any,69belongs in the project's scripts directory and is bound through `.ai-badger/config.json`'s `docs`70map — see `extensions/ledger/`.7172## Where reference material lives7374**A skills directory registers exactly one nesting level, and a directory without a `SKILL.md` is75silently ignored rather than erroring.** Verified across the agents ai-badger supports. So76**when placing a skill's reference material**, put it in a `references/` subdirectory *inside*77that skill, which ships78with it — never in a sibling directory beside it, which would never be indexed and would never be79delivered. The same rule applies to the documentation tree you are creating: nothing is picked up80because it is nearby.8182## Gotchas8384No environment-specific gotchas known.8586## Red flags — STOP8788- Writing any document before the structure inventory comes back empty89- Adding a directory the canonical tree does not have, "because this repo needs it"90- A directory README that lists the interesting files instead of all of them91- Putting a script inside this skill directory92- Creating or touching content under a frozen build-input directory — read the freeze list in93 `references/structure.md` when a build-input path is in question94- Reporting the scaffold done with seeded files the ledger does not know about