# Agents and skills for technical documentation

> READMEs, API docs, ADRs, diagrams and changelogs that do not go stale

- Source: https://doutorai.pt/en/for/technical-documentation
- Site: Doutor AI (https://doutorai.pt/en) - AI tools for small businesses

Technical documentation is usually the first thing to fall behind. The code changes every week, the README still describes last year's installation and the API spec lives in a document nobody has opened since the last migration. The cost shows up late: every new person loses days working out what had already been decided, and nobody remembers why.

The components on this page treat documentation as the output of a process rather than a manual task that keeps getting postponed. They generate API references from the code, write Architecture Decision Records (ADR) with context and alternatives, draw diagrams in Mermaid or with the C4 model, build the changelog from the commit history and check whether the existing files still match what is implemented.

Start with what hurts most in your project. If nobody can get the local environment running, the README and the onboarding guide are worth more than any diagram. If the frontend team keeps asking about the response format, start with the API documentation. Agents are for open-ended, ongoing work, commands for a concrete, repeated task, and skills for fixing formats and writing rules.

21 hand-picked components, from 4 different angles.

## Project documentation: README, guides and maintenance

The starting point for any repository: explaining what the project does, how to get it running and how to contribute. It also includes the less visible work of keeping those files alive as the code changes.

- **documentation-expert** (Agents): For when there is too much code and too little text: it creates and improves the project documentation from the code itself, applying consistent technical writing standards. [page](https://doutorai.pt/en/components/agents__documentation-expert)
- **documentation-generation-docs-architect** (Agents): Designed for inherited codebases. It analyzes the existing architecture and implementation patterns and produces long technical manuals, instead of loose pages. [page](https://doutorai.pt/en/components/agents__wshobson-agents__agents-docs-architect)
- **update-docs** (Commands): A single command for the sync pass, which updates the implementation status, the API changes and any content that has drifted after a round of development. [page](https://doutorai.pt/en/components/commands__update-docs)
- **docs-maintenance** (Commands): Useful when the documentation is already too big to reread by hand, because it sets up validation and automatic updates to catch pages that no longer match. [page](https://doutorai.pt/en/components/commands__docs-maintenance)
- **crafting-effective-readmes** (Skills): Not every README serves the same audience. This skill provides templates based on the type of project and who will read it, from an internal library to an open source project. [page](https://doutorai.pt/en/components/skills__crafting-effective-readmes)
- **documentation-templates** (Skills): For teams that want to stop arguing about structure. It brings together templates for READMEs, API documentation and code comments, including formats designed to be read by AI. [page](https://doutorai.pt/en/components/skills__documentation-templates)

## APIs, contracts and references

Documentation that other people read to integrate with your system. It covers OpenAPI specs, complete parameter listings and the handoff of context between backend and frontend.

- **api-documenter** (Agents): Covers the full lifecycle of an API exposed to third parties: writing the OpenAPI spec, interactive documentation portals and ready-to-use code samples for integrators. [page](https://doutorai.pt/en/components/agents__api-documenter)
- **generate-api-documentation** (Commands): When the API is already stable and all that is missing is the reference, it generates the documentation in several output formats and handles automatic publishing. [page](https://doutorai.pt/en/components/commands__generate-api-documentation)
- **openapi-spec-generation** (Skills): A good fit for anyone working design-first or who needs to generate SDKs, because it creates and maintains OpenAPI 3.1 specs and checks contract compliance. [page](https://doutorai.pt/en/components/skills__wshobson-agents__openapi-spec-generation)
- **backend-to-frontend-handoff-docs** (Skills): Solves the moment when the backend is done and the frontend is left waiting to find out what exists, producing a handoff document focused on whoever consumes the endpoints. [page](https://doutorai.pt/en/components/skills__backend-to-frontend-handoff-docs)
- **reference-builder** (Agents): For the cases where the complete listings are missing. It produces exhaustive parameter references and configuration guides, instead of a handful of illustrative examples. [page](https://doutorai.pt/en/components/agents__wshobson-agents__agents-reference-builder)

## Architecture, decisions and diagrams

Documentation for the newcomer who asks why the system is built this way. It brings together the overall design, the decisions recorded in writing and the visual representations.

- **create-architecture-documentation** (Commands): A complete kickoff when nothing has been written about the system's design, since it produces the diagrams, the ADRs and a browsable visualization in one go. [page](https://doutorai.pt/en/components/commands__create-architecture-documentation)
- **adr-generator** (Agents): For pinning down decisions before they get lost in chat history. It writes structured Architecture Decision Records, with the context and the alternatives considered. [page](https://doutorai.pt/en/components/agents__adr-generator)
- **c4-architecture** (Skills): Follows the C4 model and generates the context, container and component levels in Mermaid, which helps when you need to explain the same system to audiences who need different levels of detail. [page](https://doutorai.pt/en/components/skills__c4-architecture)
- **diagram-architect** (Agents): When the diagram has to fit a specific format, it produces ASCII, Mermaid, PlantUML or Draw.io, including ERDs, state machines and dependency graphs. [page](https://doutorai.pt/en/components/agents__diagram-architect)
- **mermaid-diagrams** (Skills): A syntax reference for anyone who writes diagrams by hand inside Markdown, covering class diagrams, sequence diagrams and domain modeling. [page](https://doutorai.pt/en/components/skills__mermaid-diagrams)

## Change history and onboarding new people

What has changed since the last version and what someone needs to know on day one. They are two problems with the same root: context that only exists in the heads of the people who are already there.

- **changelog-generator** (Agents): Works from the git history to produce changelogs and release notes, and keeps the version documentation aligned from one release to the next. [page](https://doutorai.pt/en/components/agents__changelog-generator)
- **add-changelog** (Commands): For anyone who just wants the CHANGELOG.md file in order. It generates and maintains entries in the Keep a Changelog format, without inventing a new structure for each version. [page](https://doutorai.pt/en/components/commands__add-changelog)
- **Release Note Generator** (Commands): Separates two audiences that usually get mixed up: from the recent commits it produces a customer-facing note and a separate technical note for the team. [page](https://doutorai.pt/en/components/commands__centminmod-cc-setup__commands-create-release-note)
- **create-onboarding-guide** (Commands): Generates the onboarding guide with environment setup, workflows and tutorials, which saves you repeating the same explanations to every new person. [page](https://doutorai.pt/en/components/commands__create-onboarding-guide)
- **documentation-generation-tutorial-engineer** (Agents): Turns existing code into step-by-step tutorials with practical examples, useful when the reference is already written but nobody knows where to start. [page](https://doutorai.pt/en/components/agents__wshobson-agents__agents-tutorial-engineer)

## How to install these components in your project

Every item in the Doutor AI technical library is a text file. Agents go in .claude/agents/, commands in .claude/commands/ and skills in .claude/skills/, inside the repository where you want to use them. If you would rather have them available in every project, put them in the equivalent folder inside ~/.claude/. After saving the file, restart the Claude Code session so the new component is read. Agents are chosen by their description, so you just ask for the task in plain words; commands are called by name, preceded by a slash; skills load when the request matches what their description says. Install two or three at a time, not twenty.

## Combining the components into a workflow

These components do more when chained than when used alone. A sequence that works well on a project already underway: first an agent that reads the codebase and produces the overall design, then the ADRs to record the decisions that only exist in the team's memory and, at the end, the README and the onboarding guide, which build on that foundation. API documentation follows a different rhythm, tied to the development cycle: generate the OpenAPI spec from the code and regenerate it whenever an endpoint changes. The changelog closes the loop, because it comes from the commits and serves as a record of what was delivered in each version.

## What these components do not solve

None of these components knows what is not written down anywhere. An agent reads the code, the commits and the existing files; it does not know why the team rejected the obvious alternative two years ago, or that a given service is going to be switched off next quarter. That context has to come from you. There is also a known risk: documentation generated in large volumes gives a sense of work done and starts being accepted without being read. Review the output before saving it, especially the ADRs and the API documentation, where one wrong detail leads someone else to build on a false premise.

## Keep reading

- [Documentation Writer Agent](https://doutorai.pt/en/how-to/subagents--documentation-writer)
- [API Documentation Generator](https://doutorai.pt/en/how-to/slash-commands--generate-api-docs)
- [Documentation Refactor](https://doutorai.pt/en/how-to/slash-commands--doc-refactor)

## Frequently asked questions

### Is it worth generating documentation automatically, or does it always come out generic?

It depends on what you ask for. Reference documentation, meaning lists of endpoints, parameters and configuration options, comes out well because the information is already in the code. Text that explains intent and tradeoffs needs context only the team has. In practice, generate the mechanical part and write by hand the three or four pages that explain decisions.

### How do I choose between an agent, a command and a skill?

A command is for a closed task that repeats many times, such as adding an entry to the changelog. An agent is for open-ended work, where it has to read several files and decide the structure of what will be written. A skill does not run anything on its own: it defines formats, templates and writing rules that Claude Code applies when the subject comes up.

### How do I stop the documentation from going out of date again?

Tie updates to the rhythm of the code, instead of treating them as a separate project. A sync command run at the end of each block of work, plus a maintenance component that periodically validates the existing pages, catches most of the drift. The rest is deciding which files become mandatory in a code review.

### Do I really need ADRs on a small project?

If you are the only person working on the project and do not plan to leave it, probably not. The value of an ADR shows up when someone new joins, or when you come back to the code a year later and no longer remember why you ruled out the simplest solution. A short file per relevant decision is usually enough.

### Do these components work with any language or stack?

Most are language-independent, because they work on text files, git history and folder structure. The exceptions are the ones that assume a specific format: OpenAPI specs assume an HTTP API, and Mermaid diagrams need a destination that can render them, for example GitHub or a documentation site.

---
Content by Doutor AI (https://doutorai.pt/en). When quoting, please cite the source: https://doutorai.pt/en/for/technical-documentation