Documentation Guide

Documentation skill

Operating manual for working in an Astro-based documentation-template project. The project's content + config live under the user's data/ and config/ folders and render through Astro layouts shipped inside the documentation-template/ framework folder. The framework's own bundled docs (the canonical user-guide for the framework itself) live at documentation-template/default-docs/data/user-guide/ — read those when this skill is unclear.

Two modes. Consumer mode (the default) — the framework is a subfolder of the user's project (<project>/documentation-template/) and the user's content lives at the project root (config/, data/, assets/, themes/ next to the framework folder). Dogfood mode — the framework repo is the project; content lives under default-docs/. The scripts derive the actual location from .env (CONFIG_DIR), so this skill describes paths relative to the user's content folders and the underlying scripts handle both modes. Where this skill says data/, the script resolves to <project>/data/ (consumer) or <framework>/default-docs/data/ (dogfood).

Triage — which reference file to read

Pick the reference file that matches the task. Read only the one(s) you need — they're independent and self-contained.

Cross-cutting tasks read multiple references. Example: "add a new docs section and write its first page" → read settings-layout.md (registering the section) and writing.md (writing the page).

Project orientation

Consumer mode (default) — the user's project root, with the framework as a subfolder:

<your-project>/                   ← user's project root
├── config/                       ← site.yaml, navbar.yaml, footer.yaml
├── data/                         ← all content (docs, blog, issues, custom)
│   ├── user-guide/               ← (your own user-guide, if any)
│   ├── blog/                     ← blog posts
│   ├── todo/                     ← issue tracker (folder-per-item)
│   └── README.md                 ← MAP of every top-level data folder (read first)
├── assets/                       ← static assets served at /assets/
├── themes/                       ← optional custom themes
├── layouts/                      ← optional custom layouts (with LAYOUT_EXT_DIR set)
└── documentation-template/       ← FRAMEWORK FOLDER — don't edit
    ├── start                     ← bash wrapper: `./start [dev|build|preview|<script>]`
    ├── .env                      ← CONFIG_DIR=../config (consumer) or ./default-docs/config (dogfood)
    ├── astro-doc-code/           ← framework code (src/, package.json, astro.config.mjs)
    │   └── src/layouts/          ← per-content-type layouts (docs, blog, issues, custom)
    ├── default-docs/             ← framework's bundled content (its own user-guide / dev-docs / themes / template)
    └── plugins/                  ← repo-local plugins (e.g. documentation-guide)

Dogfood mode — the framework repo is the project; the structure above collapses (no outer wrapper). Content lives under documentation-template/default-docs/ and CONFIG_DIR=./default-docs/config. Same code path either way; only CONFIG_DIR differs.

The most important rule: the framework's bundled user-guide at documentation-template/default-docs/data/user-guide/ is the canonical source of truth for everything this skill describes. When this skill is unclear, ambiguous, or stale, the user-guide wins. Each reference file points to its corresponding user-guide section.

Read data/README.md first

Every project should have a data/README.md that maps the data layout — what each top-level folder contains, its purpose, and how it's served. Read it at the start of any task to learn the project's content shape. The framework supports user-guide/, dev-docs/, blog/, todo/, pages/ out of the box, but a project may add custom ones (e.g. an internal-knowledge-base/, a separate meeting-notes/, etc.).

If data/README.md doesn't exist, create one before doing the requested task — the skill is far more useful when this map exists, and the cost is low. When you add or remove a top-level folder under data/, update the README in the same change so future agents (and humans) don't drift.

Universal conventions

These apply across all domains. Reference files don't repeat them — they assume you know.

• XX_ prefix — folders and files inside data/<docs-section>/ use a 2-digit numeric prefix (01_, 05_, 10_, …) for ordering. Issues and blog posts do not use this prefix.
• settings.json — every docs folder has one (sidebar label, position). Issue trackers have a root settings.json declaring vocabulary. Issues have a per-issue settings.json for metadata.
• Frontmatter title — required on every markdown file. Astro builds will fail without it.
• Theme variables only — when editing CSS in layouts, consume declared theme variables (see astro-doc-code/src/styles/theme.yaml → required_variables). Never hardcode colours, fonts, or invent variable names.
• Edit, don't rewrite — prefer Edit over Write for existing files. Surgical regex replaces preserve formatting and key order in JSON.
• ./start is the entrypoint — from the repo root, ./start (preflight: detect bun/npm → install if needed → sanity build → dev), or ./start dev | build | preview to skip preflight and forward to that script. Inside astro-doc-code/, bun run dev / bun run build / bun run preview still work directly. For helper scripts and any Node CLI tool, prefer bun if available, fall back to npm / node.

Helper scripts — 12 CLI wrappers on PATH

This plugin ships 12 CLI wrappers in its bin/ folder, which Claude Code adds to PATH automatically when the plugin is installed. Just type the command — no path needed.

Issue tracker (8):

Validators (3):

Content ops (1):

Each wrapper internally uses bun if available, falls back to node. Pass --help to any of them for the full flag list. Validators exit 0 on clean, 1 on errors found — useful in pre-commit / CI.

Searching the tracker — use docs-list --search, not the Grep tool. Any "find / locate / grep / search" verb against data/todo/ (or any tracker folder) should route to docs-list, which understands the schema (vocabulary, subtask states, frontmatter), composes structural filters with regex search in one call, and returns exact paths + line numbers. Grep only sees text. See references/issue-layout.md for the synonym list and examples.

Slash commands — bootstrap & section scaffolding

The plugin ships two slash commands for project-level scaffolding:

When the user says "set up a new docs project", "scaffold a new site", "add a new section / area / handbook", route to these commands rather than hand-authoring.

When to spawn a subagent

For bulk file reads (10+ files), spawn a Haiku subagent via the Task/Agent tool to summarise rather than loading every file into the main context. Pattern: give the subagent the file list + the question, ask for a tight report (under 200 words).

The reference files (especially issue-layout.md) document concrete subagent patterns for their domain.

When to update this skill

This skill mirrors the framework's bundled user-guide. If you discover the skill is wrong or out of date relative to the user-guide, update the skill rather than working around it — and tell the user. The skill catalogue page (@root/default-docs/data/user-guide/05_getting-started/05_claude-skills.md — i.e. inside the framework folder) is the user-facing index of installed skills; keep it in sync.

Source: sidhanthapoddar99/documentation-template — distributed by TomeVault.