Scaffold Documentation

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:

1. The canonical tree, every directory present, none extra.
2. A root README.md — a complete map: one row per directory, no omissions.
3. One README.md per directory, each a complete map of that directory.
4. 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

1. 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.

1. 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.

1. **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.

1. Write the root README and each directory README as complete, visual-first maps.

• Root README: Keep it concise and low-noise: high-level architecture/flow Mermaid diagram, 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.

1. 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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Arasz
• Source: Arasz/ai-badger
• License: MIT
• Homepage: https://github.com/Arasz/ai-badger

Install and usage instructions live in the source repository linked above.