doc

Doc Skill

YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.

Generate and validate documentation for any project. --mode selects the artifact family — the default mode handles code/API docs and code-maps; --mode=readme generates a gold-standard README; --mode=oss scaffolds and audits the open-source doc pack.

Modes

Mode routing (absorbed skills):

When invoked with --mode=readme or --mode=oss, read the corresponding reference above and follow its workflow verbatim. The default-mode steps below apply only when no mode (or the implied code-docs mode) is selected.

Execution Steps (default mode — code/API docs)

Default mode is deliberately thin — a frontier model runs it correctly with no payload. Given /doc [command] [target]:

1. Detect project type — ls package.json pyproject.toml go.mod Cargo.toml + existing docs/; classify CODING / INFORMATIONAL / OPS.
2. Run the command — discover (grep undocumented funcs), coverage (documented vs total), gen [feature] (read code → stamp function/class markdown), all, or validate.
3. Write the report to .agents/doc/YYYY-MM-DD-<target>.md (coverage %, generated, gaps, validation issues), then report coverage + gaps to the user.

Full step-by-step detail — grep recipes, function/class + code-map templates, the report skeleton, key rules, worked examples, and the troubleshooting table — lives in references/default-mode.md (moved there in the generic-craft trim). Read it when you need the exact shapes; otherwise just do the three steps.

Reference Documents

• references/default-mode.md — default mode (code/API docs): the full Steps 1-7 detail — grep recipes, function/class + code-map templates, report skeleton, worked examples, troubleshooting (moved out of SKILL.md in the generic-craft trim)

• references/doc.feature — Executable spec: detect project type, generate type-appropriate docs from the repo, validate existing docs against source (soc-qk4b)

• references/readme.feature — Executable spec (--mode=readme): mode detection, problem-first lead, trust block near install, collapse-don't-delete depth, the council gate, anti-pattern detection (soc-qk4b)

• references/oss-docs.feature — Executable spec (--mode=oss): audit existing/missing OSS docs, scaffold missing without overwrite, project-type-tailored (soc-qk4b)

• references/readme-craft.md — --mode=readme: the 8 gold-standard README patterns, interview, generation structure, council validation, anti-pattern table

• references/oss-pack.md — --mode=oss: audit + scaffold the OSS doc pack (CONTRIBUTING/CHANGELOG/AGENTS.md), project-type templates

• references/oss-documentation-tiers.md — OSS doc tier definitions (core/standard/enhanced)

• references/oss-project-types.md — Per-type OSS scaffolding templates (cli/operator/service/library/helm)

• references/oss-beads-patterns.md — AGENTS.md beads-tracker patterns for OSS projects

• references/generation-templates.md

• references/prose-and-report-workmanship.md

• references/project-types.md

• references/validation-rules.md

• references/de-slopify.md — Remove AI writing artifacts from docs

• references/architecture-report.md — Generate technical architecture documents

Examples

/doc                    # default: docs for the changed surface (references/default-mode.md)
/doc --mode=readme      # gold-standard README, council-validated
/doc --mode=oss         # full OSS doc pack

Troubleshooting