docs
Writes and updates project documentation (README, project spec, ADRs, CHANGELOG, code comments) so it stays short, true and in sync with the code. Use when creating or changing docs, recording an architecture decision, preparing a release, describing what a project is, or when a change alters behavior that docs describe.
- License 许可
- GPL-3.0
- 最近更新
- 2026-11-12
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- docs
- description
- Writes and updates project documentation (README, project spec, ADRs, CHANGELOG, code comments) so it stays short, true and in sync with the code. Use when creating or changing docs, recording an architecture decision, preparing a release, describing what a project is, or when a change alters behavior that docs describe.
02 资源文件 5
- 资产文件assets/adr.md471 B
- 资产文件assets/changelog.md539 B
- 资产文件assets/readme.md521 B
- 资产文件assets/spec.md981 B
- 参考文档references/style.md3.4 KB
03 SKILL.md 正文
Docs
Goal: a reader (person or agent) understands the project from the docs alone, and every line is still true. Wrong docs are worse than none: agents trust them.
Rules for every document
- Write for the reader: what they need to use or change the project, in that order.
- One source of truth: each fact lives in one place; elsewhere, link to it.
- Examples must run: copy them from a real run or a test, never from memory.
- Docs change with the code, in the same pull request.
- Describe what and why. The how lives in the code.
Before writing, read references/style.md (how to write: words, sentences,
structure).
Where each thing lives
| Document | Says | Template |
|---|---|---|
README.md |
What it is (short), install, quick start, links | assets/readme.md |
docs/spec.md |
The whole project: purpose, concepts, behavior, constraints | assets/spec.md |
docs/adr/NNNN-<title>.md |
Why one decision was made | assets/adr.md |
CHANGELOG.md |
What changed for users, per release | assets/changelog.md |
| Code comments | Why the code is the way it is | (below) |
Per-feature documents come from other skills: docs/requirements/ from the
requirements skill, docs/plans/ from the implementation-plan skill.
Follow the project's own layout if it already has one.
README
Start with What it is: 2 to 4 sentences on what, for whom and which problem, then Non-goals. Then install, a quick start that works when copied, and links to the spec and other docs. Keep details out; link instead.
Spec
The full description of the project, precise enough that someone could rebuild a project that behaves the same without seeing the code.
- Describe behavior from the outside: commands or endpoints, inputs, outputs, errors. No function or file names: they go stale at every refactor.
- Name the constraints that must never break (security, trust, platforms).
- Link ADRs for the reasons; do not repeat them.
- When a change alters behavior, update the spec in the same pull request. The tests prove the behavior; the spec states the intent.
ADR
Write one when a decision is hard to reverse, has real alternatives, or someone will later ask "why is it like this?" (a dependency, a data format, an architecture boundary, a security trade-off). Number them in order. Never edit an accepted ADR's decision: write a new one that supersedes it, and mark the old one "Superseded by NNNN".
CHANGELOG
Follows Keep a Changelog. Add entries under Unreleased as changes land, in
words a user understands; build them from the feat: and fix: commits
(see the git-workflow skill), and skip refactor:, test: and chore:
unless users notice them. Mark breaking changes clearly.
Code comments
- Public items: a doc comment saying what it does, not how.
- Other comments explain why: a constraint, a workaround, a non-obvious choice. Never restate what the code says.
- Delete comments that are no longer true. No commented-out code.
Before finishing
- Check every command, path and example you wrote against the code.
- Reread what you wrote against
references/style.mdand cut what the reader does not need. - Search the docs for statements your change made false, and fix them.
- Reply in a few lines: files changed and anything left undocumented.
04 同仓库更多 Skills
{name=null}
Describe what {name} does and when the agent should use it
tdd
Develops with TDD driven by BDD scenarios (Given/When/Then), writing only the functional, regression and unit tests that protect real behavior. Use when implementing a feature, fixing a bug, or when asked for tests, TDD, BDD, regression tests or coverage.
security-audit
Audits code for exploitable security problems (injection, broken access control, leaked secrets, unsafe input handling, vulnerable dependencies) and reports only verified findings with severity and fix. Use when asked for a security review or audit, before a release, or when a change touches authentication, permissions, secrets, user input, file paths, commands or network calls.
requirements
Turns a request or idea into clear, testable requirements, with scope, user stories and Given/When/Then acceptance criteria. Use when starting a new feature or project, when a request is vague, or when asked for requirements, user stories, acceptance criteria or a feature spec.
refactoring
Restructures existing code without changing its behavior, in small steps with the tests green after each one. Use when asked to refactor, clean up, simplify, rename, extract, move or reorganize code, or to work on items recorded as "Refactor later".
implementation-plan
Turns requirements into a short implementation plan of small, verifiable steps, each with the files it touches and the test scenarios it covers. Use after requirements are clear and before coding, or when asked to plan, break down or estimate a change.