doc

name	doc
description	Generate and validate repo docs, READMEs, and OSS doc packs. Triggers: "doc", "generate and validate repo docs", "doc skill".
practices	["wiki-knowledge-surface","code-complete","pragmatic-programmer"]
hexagonal_role	supporting
consumes	["repo-context"]
produces	["documentation"]
context_rel	[]
skill_api_version	1
context	{"window":"fork","intent":{"mode":"task"},"sections":{"exclude":["HISTORY"]},"intel_scope":"topic"}
metadata	{"capabilities":["doc"],"effects":["write_documentation"],"canonical_status":"canonical","disposition":"keep_specialist","tier":"product","dependencies":[]}
output_contract	documentation files

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.

Constraints

• Ground every documentation claim in the current repository, because plausible but stale prose is a documentation defect.
• When the subject is AgentOps itself, generated product and docs copy starts from the canonical category (docs/contracts/ubiquitous-language.md: the operations layer for agentic engineering) and preserves the ownership boundary; never describe AgentOps as an execution orchestrator, factory, corpus, or loop.
• Research in bounded chunks against a coverage ledger, and hold finished docs to the conceptual-surprise floor (see Research and depth kernels).
• In OSS scaffold mode, create missing docs only by default; never update or overwrite an existing doc unless the user explicitly confirms, because these files may contain operator-owned policy and project history. Treat refresh as a separate opt-in path and confirm its target writes with the user before proceeding.
• Keep mode boundaries explicit and run the selected mode's validation, because default, README, and OSS outputs have different completion criteria.

Modes

--mode	Artifact	Read first
(default)	API docs, code-maps, doc coverage/validate	this file
readme	Gold-standard README (interview → generate → de-slop → deterministic checks)	references/readme-craft.md
oss	OSS doc pack (CONTRIBUTING/CHANGELOG/AGENTS.md, audit + scaffold)	references/oss-pack.md

Same skill, different shapes. Prefer modes and references over a pile of one-off doc skills. README generate/rewrite always runs the de-slopify docs-prose pass before checks.

Mode routing (absorbed skills):

You typed	Runs