Skip to content
Skills Library
Programming · Writing

documentation-engineer

/documentation-engineer

Writes and updates accurate documentation from the code and decisions: README, how-to guides, API documentation, runbooks, ADRs and release notes, verified against the code. Use when behaviour changes or knowledge is undocumented.

Licence
MIT
Last repository change
02.11.2026

Assessment and security

100/ 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.
Content35 / 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 02.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

Writes and updates accurate documentation from the code and decisions: README, how-to guides, API documentation, runbooks, ADRs and release notes, verified against the code. Use when behaviour changes or knowledge is undocumented.

Original author description

Writes and updates accurate documentation from the code and decisions: README, how-to guides, API documentation, runbooks, ADRs and release notes, verified against the code. Use when behaviour changes or knowledge is undocumented.

How it works

  1. Purpose
  2. When to invoke
  3. Required input
  4. Execution instructions
  5. Expected output
  6. Validation checklist
  7. Example usage
  8. Sample prompts
  9. Common mistakes
  10. Related skills
Original SKILL.md headings · 96 lines, 458 words
SKILL.md preview
---
name: documentation-engineer
description: "Writes and updates accurate documentation from the code and decisions: README, how-to guides, API documentation, runbooks, ADRs and release notes, verified against the code. Use when behaviour changes or knowledge is undocumented."
license: MIT
metadata:
  activity: documentation
  difficulty: beginner
  frameworks: "any"
  version: "1.0"
---

# Documentation Engineer

## Purpose

Keep documentation correct and useful. Every statement is verified against the code, and every procedure was executed or marked unverified.

## When to invoke

- A change affects setup, behaviour, configuration or operations.
- A component has no README or runbook.
- A decision was made that future engineers must understand.

## Required input

- Code, configuration and scripts that the documentation describes.
- The audience: new contributor, operator, API consumer.
- Existing documentation and style guide.

If a required input is missing, ask for it. Do not guess.

## Execution instructions

1. Identify the audience and the task they must complete.
2. Read the code and run the commands you are about to document. Record what actually happens.
3. Write for the task: prerequisites, steps, expected results, troubleshooting.
4. Prefer examples that are executable or copied from tests.
5. Document decisions and trade-offs in an ADR, not in code comments.
6. Update or remove outdated sections that the change invalidates.
7. Mark anything you could not verify with `UNVERIFIED`.
8. Check links, commands and code samples.

## Expected output

- New or updated documents in the project's format.
- List of statements verified, and those marked unverified.
- Changelog or release note entry when relevant.

## Validation checklist

- [ ] Commands were run and outputs match.
- [ ] No invented behaviour, configuration keys or defaults.
- [ ] Audience and prerequisites are clear.
- [ ] Links and code samples work.
- [ ] Outdated content was removed or updated.

## Example usage

Input:

> Change adds env var `PAYMENT_TIMEOUT_MS` with default 3000.

Illustrative output (abridged, hand-written for this guide, not captured from a model run):

```text
README configuration table: `PAYMENT_TIMEOUT_MS`, default 3000 (verified in `config.py:14`), effect: maximum wait for the payment provider; timeout produces `PaymentUnavailable`.
Runbook: symptom "payments failing with PaymentUnavailable" -> check provider status then consider raising the timeout. UNVERIFIED: provider SLA.
```

## Sample prompts

```text
Act as the Documentation Engineer. Update the documentation for this change for [AUDIENCE]. Verify every statement against the code and mark anything unverifiable as UNVERIFIED. Include prerequisites, steps with expected output and troubleshooting. Diff: [DIFF]. Existing docs: [DOCS]
```

## Common mistakes

- Describing intended behaviour instead of actual behaviour.
- Copying AI-generated configuration keys that do not exist.
- Writing documentation that duplicates the code line by line.
- Leaving outdated pages in place.

## Related skills

- [PR Readiness Reviewer](../pr-readiness-reviewer/SKILL.md)
- [Architecture Reviewer](../architecture-reviewer/SKILL.md)
- [Repository Explorer](../repository-explorer/SKILL.md)

## Related resources

Handbook:

- [Chapter 2: Developer Ways of Working](../../../handbook/02_developer_ways_of_working/README.md)
- [Chapter 11: Engineering Delivery and Operations](../../../handbook/11_delivery_and_operations/README.md)

Prompts:

- [Documentation Update](../../../prompts/development/documentation-update.md)
- [Changelog and Release Notes](../../../prompts/delivery/changelog-and-release-notes.md)
- [Architecture Decision Record Drafting](../../../prompts/architecture/adr-drafting.md)

Workflows:

- [Prepare a production release](../../../workflows/10_production_release.md)
- [Introduce a new API](../../../workflows/04_new_api.md)

Versions

RepositoryScoreLicence
This page · arijeetganguli/ai-kaarkhana100MIT
tmcfarlane/team-avatar100MIT
agentic-swe/agentic-swe100MIT
arijeetganguli/ai-kaarkhana100MIT
zhaono1/agent-playbook100MIT
charlieviettq/awesome-agent-skill100MIT

Database snapshot: 13.11.2026 · package version 8d289666d110 (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

  • 90Technical Writing
    Use for writing technical documentation - architecture decision records, RFCs and design docs, READMEs, API references, tutorials and how-to guides, runbooks, changelogs and release notes, and developer documentation. Also covers information architecture, audience calibration,…
  • 100documentation-and-adrs
    Writes or updates engineering documentation and architecture decision records from repository facts, explicit assumptions, trade-offs, and verification links. Use for README changes, design docs, runbooks, ADRs, migration notes, and contributor documentation. Not for…
  • 100technical-writing
    Use when writing developer-facing documentation — READMEs, API references, architecture docs, ADRs, runbooks, and docstrings. Covers structure by document type, writing for the reader's task, and keeping docs accurate against the code.
  • 100code-documentation
    Analyze source code repositories and create, update, and validate accurate technical documentation. Use when developers request README generation, API documentation, architecture documentation, codebase explanation, or documentation maintenance.
  • 100documentation
    Use this skill when the user asks you to write, update, or fix project documentation — READMEs, API docs, user guides, ADRs, or other Markdown docs. Also use when code changes need user-facing docs updates. Only write Markdown files; do not use for implementation, planning or test work.
  • 90technical-documentation
    Use this skill when creating, maintaining, or auditing technical documentation — READMEs, ADRs, API docs, runbooks, onboarding guides, changelogs, knowledge bases, and AI agent context files (AGENTS.md/CLAUDE.md). Covers documentation- driven development, OpenAPI generation,…

Feedback and reports

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