Documentation-first discipline for AI coding agents: declare your scope before editing, leave a trail after.
An Agent Skill that stops AI assistants from making undocumented changes. It enforces three rules on every task — state what you're about to touch, record what you actually changed, never backfill the record later — and ships a six-file project skeleton for teams adopting the workflow from scratch.
Distilled from AGENTS.md conventions that were battle-tested across two real projects.
Coding agents are fast, agreeable, and forgetful. Left alone, they rewrite files you never asked them to touch, summarize their work in chat but never write it down, and quietly overwrite yesterday's decision as if it had never been made. Three sessions later nobody — human or AI — can reconstruct why the code looks the way it does.
This skill treats documentation as part of the task, not as cleanup afterward.
Log every change, in the same turn. If the task touched any file — code, docs, assets — a CHANGELOG.md entry is mandatory before finishing. The one exception is a pure discussion turn with no file edits, and even then the agent must say so explicitly rather than trailing off. Deferred logging is not allowed: "I'll write it up once everything's done" is how records get lost to an interrupted session.
Unknowns get marked, not invented. Any placeholder the agent can't fill from the conversation becomes TBD (reason: …). It may not delete the section, and it may not make something up to fill the gap. A TBD is a signal that someone needs to go ask.
Superseded decisions stay on the record. When a later decision overturns an earlier one, the old entry isn't deleted or edited — it gets annotated with a pointer to what replaced it. History stays auditable; the log doesn't get quietly rewritten to look like no mistake was ever made.
The skill also ships a short table of the excuses agents reach for ("too small to log", "the user didn't ask for a changelog") paired with why each one doesn't hold.
| The user says | Mode |
|---|---|
| "Initialize a new project" / "set up an AGENTS.md skeleton" | Init |
| (routine code or doc changes, nothing special) | Task discipline — the default |
| "Tidy up the folders" / "are these files in the right place?" | Cleanup |
Creates the directory tree (docs/, src/, assets/{design,bug,reference}/, notes/, archive/) and writes six files from templates embedded in the skill: AGENTS.md, README.md, CHANGELOG.md, TODO.md, docs/decision-log.md, and docs/project-context.md. Placeholders get filled from the conversation — the agent is instructed to interview you rather than hand back a file still full of {{...}}.
Two paths are handled separately. For a greenfield project, the templates apply directly. For an existing project adopting the workflow, the decision log deliberately does not back-fill history into ADR format — that invites fabricated detail. Instead it opens with an index table pointing at wherever the real reasoning already lives (old design docs, the README), and starts ADR format from the adoption date forward.
Read the project's docs first, then declare scope up front: goal, files to read, files to modify, files that won't be touched, and risks. After the work, a structured report covers what changed, whether legacy code was removed, whether the build passed, blast radius, and known issues.
Two details that make this more than a checklist:
- Scope reconciliation. If something declared off-limits turned out not to need touching, or a planned step got dropped, that's stated explicitly. You can't silently drop half the plan and report success.
- Proposal menus. Out-of-scope improvements spotted mid-task don't get implemented on the sly, and don't get waved at with a vague "maybe later." They come back as an enumerated list, each with a priority and a reason it was deferred — a menu you choose from.
Incidental fixes made outside the requested scope must be listed on their own line, not folded into the main description.
Audits the tree against the project's own documented conventions, falling back to sensible defaults when AGENTS.md doesn't specify. It flags misfiled files, meaningless names (screenshot1.png), root-directory clutter, and orphan docs that no navigation table references.
Crucially, it produces a list and stops — no file gets moved until you approve it. Nothing is deleted, ever, as part of cleanup; an empty or unreferenced directory is not grounds for removal without your explicit say-so. Files being replaced go to archive/ with a date stamp rather than being overwritten, so the change stays reversible. Once approved, git mv is preferred over plain moves to preserve history.
The skill is a single file with no dependencies — by design, it forbids itself any companion folders or template files. Installing it is one curl.
Personal (available in every project):
mkdir -p ~/.claude/skills/docs-driven-workflow
curl -o ~/.claude/skills/docs-driven-workflow/SKILL.md \
https://raw.githubusercontent.com/<MNICKZ>/docs-driven-workflow/main/skills/docs-driven-workflow/SKILL.mdPer project, so it travels with the repo:
mkdir -p .claude/skills/docs-driven-workflow
curl -o .claude/skills/docs-driven-workflow/SKILL.md \
https://raw.githubusercontent.com/<MNICKZ>/docs-driven-workflow/main/skills/docs-driven-workflow/SKILL.mdRestart Claude Code after creating a new top-level skills directory, then confirm with /skills. You can also invoke it directly as /docs-driven-workflow.
Download SKILL.md, zip it with the file at the top level of the archive, and upload under Settings → Capabilities → Skills.
The file follows the open Agent Skills standard, so any host that reads SKILL.md can use it. Drop it in your agent's skills directory, or point your tool at this repo.
The instructions name no host-specific tools — file creation and directory setup are described by capability, not by tool name, and Init mode falls back to path-implied directories on hosts without shell access.
docs-driven-workflow/
├── skills/
│ └── docs-driven-workflow/
│ └── SKILL.md # the skill — the only file you install
├── README.md # English docs
├── README.zh-CN.md # 中文文档
├── CHANGELOG.md
└── LICENSE
The skill lives in a subdirectory so that cloning this repo never drops a README or LICENSE into your skills folder — the skill's own rules forbid companion files, and the repo layout respects that.
The skill body is written in Chinese, with an English description field carrying Chinese trigger keywords. Trigger matching works in both languages; the instructions the agent follows are Chinese.
The trigger targets projects that already follow this discipline, plus explicit requests to set it up. That keeps the agent from reaching for the skill in every unrelated repo — but it also means an existing project won't pick it up automatically until it has the skeleton. Ask for initialization once, and the default mode takes over from there.
Project-specific prohibitions deliberately live in each project's own AGENTS.md, never in this skill. The skill supplies the placeholder structure and asks; you supply the content.
Issues and pull requests welcome. For changes to the workflow itself, please include a short before/after example showing the difference in agent behaviour — this skill is derived from practice, and it should stay that way.
MIT — see LICENSE.