docs

name

docs

description

Use whenever the user asks to create a spec, archive or rename a doc, list docs, regenerate INDEX.md, stamp a metadata block onto a file already written, reassign a doc's project, or check a docs tree (a directory with a .docs.toml file at its root), or to adopt a foreign Markdown directory into the convention (e.g. "adopt this directory", "migrate this folder", "bring this into docs convention", "import existing markdown specs"). Always run the docs CLI verb (docs new / index / archive / mv / list / touch / stamp / check / migrate / project rename / project set / install-skill) — never hand-edit INDEX.md, metadata blocks, or files into archive/. Not for ordinary Markdown outside a .docs.toml-marked tree.

docs — run the verb, never hand-edit

docs is a CLI for managing trees of structured Markdown documents — specs, runbooks, references, design notes — where each file is self-describing (a metadata block under its H1) and INDEX.md is a generated view of the docs, not a hand-maintained list. Run a docs verb for every metadata, index, archive, or lifecycle action; never hand-edit those parts. A hand edit silently drifts the tree out of sync.

When this skill applies

A docs-managed tree is a directory with .docs.toml at its root. Use this skill when:

• The directory has .docs.toml and the user's request maps to a verb below.
• The user wants to start managing a directory as docs — bootstrap with touch .docs.toml at the intended root, then use docs new and docs index.
• The user wants to adopt an existing tree of foreign Markdown into the convention — run docs migrate <dir> (dry-run first).
• The user is about to hand-edit INDEX.md, a metadata block, or move a file into archive/.
• The user needs to create or maintain quality artifacts such as contract-to-test matrices, quality logs, or generated coverage/mutation/ benchmark report summaries in a docs-managed tree.

Do not apply when:

• Editing ordinary Markdown in a non-docs project (e.g. a README.md in a code repo).
• A prose-only edit that does not touch metadata, INDEX.md, archiving, or lifecycle — make the edit normally.

If no .docs.toml exists up-tree, docs silently falls back to the current directory as the implicit root. That cwd-fallback is convenient but easy to misuse — confirm with the user before any verb that writes.

Where to put .docs.toml. A project is metadata (the Project: slug), not a directory — one root can hold many projects, and a single project needs no subdirectory. Put .docs.toml at the directory that will hold the docs so the root is the project: docs sit flat and the root-relative Related: paths stay clean. Don't create a parent root and nest a lone project one level down — every sibling reference then carries a redundant <subdir>/ prefix. Group genuinely separate bodies of work by Project: metadata, not by folder. See references/convention.md "Where to put".

The verbs

Task	Verb	Key flags / behaviour
Create a doc	docs new <role> <slug>	--project, --title, --body-from; scaffolds metadata
Stamp a metadata block onto a file you already wrote	docs stamp <file>...	--role (default notes), --project, --title; write-then-stamp, idempotent re-stamp refreshes Updated:
Regenerate the index	docs index	idempotent; rewrites only the marker block
Archive a finished doc	docs archive <file>	--reason, --date, --cascade
Rename or move a doc	docs mv <old> <new>	rewrites Related: tree-wide
List or query docs	docs list	--lifecycle, --role, --project, --stale, --json
Bump a doc's Updated:	docs touch <file> [--check [--stale N]]	reindexes; --check folds in docs check (touch-then-validate in one invocation; --stale N is the check's stale window)
Validate the tree	docs check	exit 0 clean / 1 warnings / 2 errors
Adopt a foreign tree	docs migrate <dir>	dry-run by default; --apply to write
Rename the project	docs project rename <new-name>	rewrites .docs.toml + every Project: line; --dry-run
Reassign one or more docs' project	docs project set <doc>... <new-project>	rewrites only the named docs' Project: line; --new-project to create a new group; --dry-run
Install this skill on a host	docs install-skill	--dest, --copy (default), --symlink, --force

docs walks up from the current directory to find .docs.toml. Use docs <verb> --root DIR to point at a specific tree explicitly. For full flag and exit-code detail, read references/cli.md or run docs <verb> --help.

Per-tree stale window (.docs.toml [check] stale_days = N). Set a [check] stale_days = N key in the tree's .docs.toml to give docs check and docs touch --check a default stale window — bare docs check then flags Lifecycle: active docs untouched for more than N days, instead of hard-coding --stale N at every call site. An explicit CLI --stale overrides it; the key is check-scoped (it does not affect docs list --stale).

Adopting an existing Markdown directory? Read references/adoption-playbook.md first — it walks the dry-run → triage → exclude → iterate → apply → verify loop end-to-end and points at the starter references/docs-toml-template.toml.

Quality artifacts

For test matrices, quality logs, and generated reports, use Markdown companion docs for the indexed summary and keep tool output in generated files. Prefer docs new spec <milestone>-test-matrix for contract-to-test matrices and docs new log quality/<milestone>-quality-log for ongoing quality results, then docs touch, docs index, and docs check as usual.

Generated reports such as coverage.xml, mutation.json, and benchmark.json remain canonical tool output. Link them from the companion doc with Related: when the local convention accepts non-Markdown artifact targets; otherwise link their paths in the body.

Read references/quality-artifacts.md before creating a quality log or report companion.

Important: docs check proves the docs tree is mechanically clean. It does not prove behavior is correct, visible tests are adequate, hidden/ generalization coverage exists, or risk gates passed.

Update notices

docs checks PyPI at most once a day and, when a newer docs-cli release is available, prints one advisory line to stderr — docs: update available <current> -> <latest> — run: pip install -U docs-cli. It never touches stdout and never changes the exit code, so it is safe to leave on in scripts. To silence it: --quiet or --json suppress the line, and setting CI, DOCS_CLI_NO_UPDATE_CHECK, or DO_NOT_TRACK (any value) disables the check entirely. See references/cli.md "Update check".

Three things never to hand-edit

• INDEX.md — generated between <!-- docs:generated --> markers. Run docs index to regenerate.
• A file's location relative to archive/ — never mv/git mv a file into or out of archive/<date>/, and never hand-flip Lifecycle: to or from archived. Run docs archive so lifecycle and location move together.
• A metadata block — Lifecycle: / Role: / Project: / Updated: / Related:. Use docs new to scaffold a new block; docs touch to bump the date. Never hand-write or hand-edit.

Reference

The on-disk format and vocabulary (Lifecycle: / Role: values, metadata-block grammar, archive layout): references/convention.md.

The full flag and exit-code reference of every verb: references/cli.md.

Quality artifacts, test matrices, generated reports, and the limits of docs check: references/quality-artifacts.md.

When a task needs a convention or flag detail this skill does not give, open the reference rather than guessing.