# Askit Build Docs > Creates and improves a plugin's documentation across modes (readme, quickstart, tutorial, how-to, reference, glossary, faq, troubleshooting, architecture, folder-readme, and an Astro Starlight docs site) to the Advanced Skill Library Standard. Use when authoring or refreshing docs, scaffolding a folder README, standing up a docs site, or aligning documentation with the component index. - Skill: `product-on-purpose/askit-build-docs` (Agent Skill, multi-file: 5 files) - Install (CLI): `npx skillmds@latest add product-on-purpose/askit-build-docs` - Raw SKILL.md: https://api.skillmd.com/api/skills/product-on-purpose/askit-build-docs/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: product-on-purpose (https://skillmd.com/u/product-on-purpose) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/product-on-purpose/askit-build-docs --- # askit-build-docs ## Purpose Author and improve a plugin's human-and-agent-facing documentation, following the builder pattern ([../../docs/reference/builder-pattern.md](../../docs/reference/builder-pattern.md)). `create` scaffolds a doc from the component index and the Standard; `improve` reads `askit-evaluate` findings and the docs and fixes gaps. Doc modes follow the Diataxis split: `readme`, `quickstart`, `tutorial` (learning), `how-to` (task), `reference`, `glossary`, `faq`, `troubleshooting` (information), and `architecture` (an overview that links to a detailed companion, the summary-plus-detailed convention). The `folder-readme` mode scaffolds or refreshes a meaningful folder's `README.md` so its inventory matches the folder's actual children (the `G8` anti-rot guard). The `site` mode stands up an Astro Starlight documentation site from the pinned recipe in [references/docs-site-recipe.md](references/docs-site-recipe.md). Mermaid is a validated convention, not a skill. ## When to use When authoring or refreshing a plugin's docs, standing up a docs site, or aligning documentation with the component index after a change. ## create mode 1. Read `library.json` + component frontmatter (the index) and the target doc type. 2. Scaffold the doc from the matching Diataxis shape (one purpose per page). README and architecture lead with a summary and link to detail. 3. Cross-link: every relative link must resolve (the U6 reference-link rule is the discipline to mirror). ## improve mode 1. Run `npx agent-skills-toolkit evaluate . --json` and read the docs for drift against the component index (a renamed or removed component leaves a dangling reference). 2. Fix each gap; keep prose tight (the ETH-Zurich finding: verbose context files lower agent task success). ## site mode 1. Follow [references/docs-site-recipe.md](references/docs-site-recipe.md): copy the pinned `../pm-skills` stack (Astro 6 + `@astrojs/starlight` ~0.39 + `astro-mermaid` ~2.0, ordered mermaid-before-starlight), the GitHub Pages `site` + `base`, and the **generated Pattern S** content collection (ADR 0024 D2): the stock `docsLoader()` over `src/content/docs/`, a `gen-docs-site.mjs` generator that emits the public `docs/**` tree there (gitignored, rebuilt via a `generate()` call at the top of `astro.config.mjs`, link-rewritten so the clause-14.11 guard stays green), and curated landing pages on top. Not an in-place glob over `./docs`. 2. Wire the deploy workflow (`.github/workflows/deploy-pages.yml`, triggered on `site/**` and `docs/**`) and verify `npm run build` plus the link/route/untracked guards are green before publishing (standing up a live site is a separate, build-verified slice; the recipe is the contract). ## folder-readme mode Scaffold or refresh a folder `README.md` whose inventory set-equals the folder's immediate children, so the `folder-readme` (`G8`) check stays green as the folder evolves. 1. List the folder's immediate children with `fs.readdirSync`, dropping `README.md`, gitignored/scratch/tool dirs (`node_modules`, `.git`, `dist`, `.astro`, `_local`, ...), lockfiles, and `.gitkeep`. 2. Emit a README with a frontmatter `title`, a one-to-two-sentence purpose, and an `## Inventory` section listing each remaining child as `- ``name`` - what it is` (a trailing slash marks a subdirectory). For a folder under `docs/`, also carry the full frontmatter taxonomy (`description`, `audience`, `level`) so it passes `G7`. 3. Refresh rather than overwrite: when a README exists, keep its purpose paragraph and existing per-child descriptions, and only add or remove inventory lines so the set matches the current children. The meaningful-folder allowlist (ADR 0024 D1) is the repo's source and component folders; the repo-root README (the project hero) and `templates/seed-plugin/` (a seed payload, not a folder guide) are excluded. ## Writing rules (all modes) Five rules, each from a defect found in this repository's own public docs on 2026-08-23 and 2026-08-24. The per-quadrant page anatomy, the measurable floor, and the worked exemplar are in [references/style-contract.md](references/style-contract.md); measure a page before and after any rewrite rather than judging your own prose. 1. **Every command must run from the reader's position.** A page written for a plugin author must not name `node scripts/*.mjs`: that path exists only in a clone, while the install docs send people to npm or the marketplace. Use the published bin (`npx agent-skills-toolkit [subcommand]`). Where a tool ships with the plugin but NOT the npm package, say which install route provides it rather than dropping the command. Seventy commands across 34 pages had this defect. 2. **No internal planning vocabulary.** Project phases, wave numbers and packet names mean nothing outside this repo, and they rot: one page told readers to wait for a phase that had shipped three months earlier. 3. **Define a coined word in the sentence that first uses it**, and link [the glossary](../../docs/explanation/glossary.md). Product terms (Bronze, Silver, Gold, tier) do not need this; invented ones (burndown, spine, emission, declared-tier ceiling) do. 4. **A reference ID always carries a handle and a route.** Never a bare `E14`; write what it is and link where it lives. A reader cannot look up a number they have no index for. 5. **Orientation before mechanism**, on every explanation and tutorial section. Say what the thing is, then what breaks without it, then the specification. A section opening with "X is an ES module with exactly two exports" has told a reader who already knew. A sweep aimed only at sentence length missed this entirely: the corpus measured plain at a 12-word median sentence and still read as hard. ## Scope Documentation is Universal (markdown is portable on both agents). The site is the v1 docs surface (ADR 0021/0023); README/CHANGELOG/RELEASE-NOTES discipline is gated by `askit-release` and the release-readiness gate (ADR 0022). Sample sets and eval coverage are authored by `askit-build-samples`, not here.