Docs

Docs

Keep ./docs/ honest. Scout the code, diff it against what the docs claim, write what's true. Small canonical set — easy to keep current, hard to let rot.

What this skill is — and isn't

| Skill | Question it answers | Output | |---|---|---| | vd:scout | "Where does X live in this repo?" | File map, no writes | | vd:journal | "What did I just learn / decide / break?" | Personal entry in the injected Journals path | | vd:docs | "Are the shared ./docs/ files true and current?" | Updated files in ./docs/ |

./docs/ is team-facing truth. Journals are personal. Plans/reports live under ./plans/. Changelog, roadmap, and PR-style narrative are intentionally not in this skill's scope — those rot fastest and vd:ship / vd:journal already cover them.

Subcommands

| Subcommand | Reference | When | |---|---|---| | init | references/init-workflow.md | Fresh repo — no ./docs/ yet, or only a stub README | | update | references/update-workflow.md | Code drifted from docs after a feature, refactor, or migration | | check | references/check-workflow.md | Validate-only: required files, size, freshness, broken refs. No writes. | | adr | references/adr-workflow.md | Record an architecture decision (the why behind an irreversible choice) under docs/decisions/ |

Parse $ARGUMENTS first word (in runtimes without $ARGUMENTS substitution, use the text following the skill name in the user's message):

• init / update / check / adr → load the matching reference
• empty / unclear → AskUserQuestion with the options (AskUserQuestion in Claude Code; plain-text question elsewhere). Don't auto-run init — it writes files.

Flags

| Flag | Effect | |---|---| | --inline | Skip docs-manager subagent — write from main context. Use when you want to drive the writing yourself or the subagent is unavailable. | | --dry-run | Print the plan (files to scan, files to write/touch) and stop. No subagent, no writes. Use before letting a subagent churn on a large repo. |

Canonical doc set

Intentionally short. Every file here earns its place — code-derivable, frequently consulted, and stable enough not to need weekly rewriting.

| File | Purpose | Required? | |---|---|---| | README.md | Project entry point, ≤ 300 lines — what is this, how to run it, where to read more | Yes | | docs/development-guidelines.md | Code style, naming conventions, file layout, local dev setup, contribution flow | Yes | | docs/system-architecture.md | Components, data flow, integrations, module boundaries | Yes | | docs/tech-stack.md | Languages, frameworks, runtimes, key libraries, infra services — what powers this | Yes | | docs/deployment.md | CI/CD pipelines, environments, deploy steps, env vars, rollback procedure | Yes |

Out of scope (by design):

• Changelog → vd:ship writes CHANGELOG.md directly
• Project roadmap → lives in plans (./plans/) or your issue tracker, not here
• Codebase summary → vd:scout produces this on demand; doesn't need a static file
• PRD / requirements → product artifact, not a code-derivable doc

If a project has good reasons to maintain those, add them outside vd:docs's automated touch — this skill won't read, write, or validate them.

docs/decisions/ (ADRs) is a special case — append-only decision history written by the adr subcommand, not current-state docs. It is exempt from freshness, size-budget, and citation validation: an old ADR is correct (it records what was decided then), and a superseded one stays in place with its status flipped. check must skip docs/decisions/.

Pre-flight: missing ./docs/

Before any subcommand except init:

1. If ./docs/ does not exist → ask the user: run init now, or abort?
2. If ./docs/ exists but is empty → same question.
3. If a single required file is missing → flag it in the plan; create it as part of the run.

Never create ./docs/ silently. The user owns this directory.

Writer strategy

| Condition | Writer | |---|---| | Default, docs-manager subagent available | Delegate via Agent tool — passes the scout digest + doc readings, returns when files are written | | --inline, or subagent unavailable | Write from main context using the reference workflow's checklist | | check | Always inline — no writes |

When delegating, pass: scout digest, current doc LOC table, the user's $ARGUMENTS, plan dir (if any). Do not pass full file contents — let the subagent re-read what it needs.

After init or update writes files, list every changed doc with an openable location: [deployment.md](/absolute/path/to/docs/deployment.md) and, when helpful, file:///absolute/path/to/docs/deployment.md. Repo-relative paths are fine as secondary context, but never hand off only a basename.

Token efficiency

• Scout in parallel, write once. Don't re-scout per doc file.
• Read docs in bulk when many. If ls docs/*.md | wc -l ≥ 4, spawn Explore subagents to read in parallel (read sequentially if subagents unavailable) — see references/update-workflow.md Phase 1.5.
• Don't dump full git diff into the subagent prompt — git log --oneline + git diff --stat is enough; the subagent pulls scoped diffs only for files it names.
• --dry-run costs almost nothing — run it first on unfamiliar repos.

Quality bar

• Every claim has a citation. Architecture docs name the file path. Tech-stack entries name the version (from lockfile / package.json / go.mod). No "the system uses XYZ" without src/...:N.
• No filler. If a section in a template has nothing concrete, delete it — don't pad with "TBD".
• Size budget. docs.maxLoc from session context (default 800). Over budget → split or trim, not "accept as-is".
• Validation runs after every write. references/update-workflow.md Phase 4 — non-blocking, but report what it finds.

Workflow position

Typically follows: vd:ship (after the PR lands, sync ./docs/ to the new reality), vd:cook (end of plan), major refactor or migration.

Typically precedes: Nothing — vd:docs is terminal. Next pipeline starts at vd:scout or vd:plan.

Do not run vd:docs mid-implementation — docs drift faster than code does. Wait until the code is stable.

Hard rules

1. Never write outside ./docs/ or ./README.md, unless the user explicitly names a project guidance file such as AGENTS.md or CLAUDE.md. Plans, journals, and reports have their own homes.
2. Never invent. If the scout digest doesn't support a claim, the docs don't make it.
3. Never run init on a populated ./docs/. update is the right verb — init is for empty trees.
4. --dry-run before any big sync. Especially on repos you don't own well.
5. One file write per doc. No append-mode, no patch-on-patch. Subagent rewrites the file in full or not at all.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: vanducng
• Source: vanducng/skills
• License: MIT
• Homepage: https://skills.vanducng.dev

Install and usage instructions live in the source repository linked above.