Skip to content
Skills Library
Documents & office · Writing

documentation

/documentation

Write and maintain documentation that stays true — present-tense description of the system as it is, every claim traceable to code, updated in the same change as the behaviour it describes, written for one named audience. Use when changing behaviour that is documented, writing a README or guide, or maintaining agent-facing or product-facing knowledge files.

Licence
MIT
Last repository change
11.11.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 11.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Write and maintain documentation that stays true — present-tense description of the system as it is, every claim traceable to code, updated in the same change as the behaviour it describes, written for one named audience. Use when changing behaviour that is documented, writing a README or guide, or maintaining agent-facing or product-facing knowledge files.

Original author description

Write and maintain documentation that stays true — present-tense description of the system as it is, every claim traceable to code, updated in the same change as the behaviour it describes, written for one named audience. Use when changing behaviour that is documented, writing a README or guide, or maintaining agent-facing or product-facing knowledge files.

How it works

  1. The core rule
  2. Write for one audience
  3. Where things belong
  4. Do not generate documentation nobody asked for
  5. Product-facing knowledge is part of the product
  6. Keeping it honest
  7. Reviewing documentation you did not write
  8. Commit and handoff prose
  9. Forbidden
Original SKILL.md headings · 78 lines, 881 words
SKILL.md preview
---
name: documentation
description: Write and maintain documentation that stays true — present-tense description of the system as it is, every claim traceable to code, updated in the same change as the behaviour it describes, written for one named audience. Use when changing behaviour that is documented, writing a README or guide, or maintaining agent-facing or product-facing knowledge files.
---

# Documentation

Documentation has exactly one job: let someone act correctly without reading the source. It fails silently — when it goes stale nothing breaks, nothing turns red, and the reader confidently does the wrong thing. That is worse than having no documentation at all, and it is the failure this skill exists to prevent.

## The core rule

**Documentation describes the system as it is, in the present tense.**

- No roadmap items, no "coming soon", no aspirational features.
- No migration history, phase numbers, or "formerly known as".
- No changelog narrative inside reference documentation. History belongs in version control and in the plan archive.
- Every claim must be traceable to something in the repository — code, schema, configuration, infrastructure. If you cannot point at it, do not write it.

If you change behaviour, update the affected documentation **in the same change**. Not afterwards, not in a follow-up. A rename of a page, a field, a command or a concept is enough to require it.

## Write for one audience

Decide who the reader is before the first sentence, and never mix two audiences in one document:

- **Engineers** — may see file paths, table names, code, infrastructure, real environment names.
- **Operators / admins** — need exact procedures, commands, preconditions and failure recovery; not internals.
- **End users** — need the interface's own vocabulary: pages, buttons, settings. No table names, no column names, no code, no file paths, no infrastructure.
- **Agents** — need procedures and constraints, not prose. See `engineering-workflow` and the project's agent instructions file.

A sentence only comprehensible to someone who has read the source does not belong in user-facing or product-facing documentation, even when it is accurate.

## Where things belong

- **Reference** — what the system is, and how its parts relate. Explanatory, stable.
- **Guides** — how to do a thing, start to finish, in order, with the exact commands.
- **Operations** — deployment, infrastructure, environments, incident procedures.
- **Agent instructions** — conventions and constraints for automated contributors.
- **Plan archive** — the dated, immutable record of what was decided. The deliberate exception to the present-tense rule: plans are history and must never be edited (`change-planning`).

Prefer editing the document that already covers the area over adding a new one. Fragmentation is the main way documentation dies.

## Do not generate documentation nobody asked for

Do not create summary files, migration notes, status reports, "what I changed" documents or implementation notes as artifacts. Put that in your handoff message and in the commit message, where it belongs. The exception is a persistent project-knowledge file the project actually maintains.

## Product-facing knowledge is part of the product

When a system reads documentation at runtime — an in-app assistant, a help surface, an onboarding tour, a support bot — those files are product code, not documentation. Treat them accordingly:

- Nobody reads them directly, so staleness is invisible until it misleads a real user. Update them in the same change as the behaviour, always.
- Write in the interface's vocabulary, naming only things the reader can actually see and click.
- Every answer must land somewhere actionable. Abstract explanation with no control to act on fails the bar even when it is true.
- Never name another customer, tenant or brand in content that ships to all of them.
- If the project has an automated consistency check for this corpus, run it. When it reports drift, fix the content — never weaken the check.

## Keeping it honest

- **Generated files are generated.** If a file is produced by a script, never hand-edit it; run the generator. Say so at the top of the file.
- **Exact commands, copy-pasteable, in the shell the reader actually uses.** Shell syntax is not portable — a `bash` heredoc does not parse in PowerShell. Either match the project's documented shell or give both forms.
- **Preconditions before steps.** What access, credentials, network position or state the reader needs first.
- **Say what failure looks like.** The error they will see, and what to do about it.
- **Link rather than duplicate**, unless duplication is deliberate because the audiences differ — and then say that it is deliberate.

## Reviewing documentation you did not write

When you touch an area, check whether its documentation is still true. If it is not, fix it or report it — "that's not my document" is not available. Do not, however, rewrite a document's structure as a side effect of a small change.

## Commit and handoff prose

The diff shows *what* changed. Your commit body must carry *why* — the problem, the cause, the decision. State what was verified and anything deliberately left unverified. Write it for the person who finds this commit in six months while bisecting.

## Forbidden

- Documenting intent, plans or future work as if it exists.
- A claim you cannot trace to code, schema or configuration.
- Changing behaviour without updating the documentation in the same change.
- Hand-editing a generated file.
- Mixing audiences — internals in user-facing content, or interface vocabulary in engineering reference.
- Naming a real customer or tenant in content that ships to all of them.
- Creating unrequested summary, status or migration documents.
- Editing an archived plan.

Versions

RepositoryScoreLicence
This page · iWiiCK/iwiick-ai-agent-plugin90MIT
software-combined/SC_AI100Apache-2.0
DaveSkender/Stock.Indicators100Apache-2.0
mcouthon/agents100MIT
YLfjuk/deltafold100MIT
comet-ml/opik100Apache-2.0
runwield/runwield100MIT
anthropics/knowledge-work-plugins100Apache-2.0
luocfprime/labtasker100Apache-2.0

Database snapshot: 13.11.2026 · package version 7c63de8457b4 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100technical-writing
    Write or revise evidence-backed technical documentation for its intended audience. Use when creating, updating, restructuring, or editing a README, runbook, architecture guide, API guide, spec, or agent-facing instructions.
  • 100s4h-writing-technical
    Writes and audits technical documentation, API docs, user guides, and specifications for completeness, sequence, precision, and audience calibration. Use when documentation is confusing, assumes too much knowledge, or leaves gaps a user can't bridge. Triggers: 'technical…
  • 90tc-docs-write
    Use when writing or updating the TcKit documentation site or the README — anything under docs/content/ or README.md. Triggers on requests like "update the docs", "document this in the docs", "write a docs page for X", "the README needs Y", "add a capability page", "fix the home…
  • 100technical-writing
    Write or repair documentation that stays true to the system it describes — README, setup guide, how-to, API reference, architecture explanation, release notes, runbook — by fixing the reader and the task first, then grounding every factual claim in code you actually read. Use…
  • 85write-the-docs
    Write or edit project documentation. Use when writing a README, design doc, or module doc.
  • 100technical-documentation
    Audit, write, and improve developer documentation using Google''s Developer Documentation Style Guide and Technical Writing courses. Use this skill for any documentation work, even when the user names no style guide: "audit our docs", "review this README", "write a README",…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.