AI Documentation: Agents, Add-ons, Prompts

For documentation, use AI to draft from sources you control (code, comments, tickets, release notes), to keep pages in one consistent shape and to propose updates inside the same pull request as the change. A person who knows the product checks every claim and runs every example. Model cost per page is cents; review time is the real cost. Checked 31 October 2026.

The job in one table

What the job is

Good documentation tells a reader how to do a thing and what to expect, and it stays true when the product changes. Most teams fail at the second half. Pages are written once and drift. People stop trusting them, and support gets the questions the docs should have answered.

AI helps with the grind: producing a first draft in the right shape, listing every option from the code and noticing which pages mention a function that just changed. It hurts when it is trusted to know the product. A model that has not run your software will describe an option that sounds right and does not exist. The fix is the same as in every other job on this site: ground the draft in sources, and have a person who knows the product sign it off.

Which agent fits

If the docs sit in a public repository, check the project's contribution rules on AI-assisted changes before you open pull requests. Policies differ by project, and we do not summarise them here.

Add-ons and kit items that help

The starter files are at CLAUDE.md starter and AGENTS.md starter. Prompts for documentation sit in the prompt library. Claude Code's docs say a skill's body loads only when it is used, so a long style guide in a skill costs almost nothing until needed, while the same text in CLAUDE.md costs tokens every session. See context window.

A safe workflow, step by step

1. Write the style sheet once. Voice, terms, how to show commands, how to name things.
2. Pick the source for each page. Code, an existing doc, a ticket or a recorded demo. No source, no page.
3. Draft from the source. Tell the agent: describe only what appears in the source; mark anything you could not confirm.
4. Run every example. Commands and code blocks must run on a clean environment.
5. Review for claims. A person who knows the product reads for accuracy, not for style.
6. Keep the draft with its sources. A comment or a front-matter list of files and commits it was based on.
7. Update in the same pull request as the change. A rule that a code change touching public behaviour must include a doc diff.
8. Check links and examples in CI.
9. Set an owner and a review date on each page.

Step 6 is the one that makes later updates cheap. When a source file changes, you know which pages to look at, and an agent can propose the edit.

A page template that keeps drafts honest

Give the agent a fixed shape so reviewers know where to look.

The sources row is easy to skip and costly to omit. Without it, the next person has no way to know which parts of the page a code change makes false.

Release notes from merged changes

Release notes are the easiest first win, because the input is structured: a list of merged pull requests with titles and labels. A good routine asks the agent to group changes under fixed headings, write one plain sentence for each, drop internal detail such as ticket numbers and branch names, and flag any change it cannot describe from the title alone. A person then removes anything that should not be public, checks that every behaviour claim is right and adds the one-line summary. Our release notes skill packages this. If you publish on several surfaces, such as a changelog page, a readme and a release post, generate them from one reviewed list so they cannot disagree.

Answering questions from the docs

A question-answering assistant over your docs is a different job from writing them, and it is a strong test of them. Retrieve the relevant pages, send only those to the model and require it to quote the page and link to it. When it cannot answer, it should say so and log the question. A weekly list of unanswered questions is the best backlog a docs team can have. Keep this assistant read-only, and fix the page rather than patching the answer.

Common mistakes

• Drafting from memory. Always point the agent at the source.
• Publishing without running the examples. A broken command costs more trust than a missing page.
• Writing pages nobody owns. Each page needs a name and a review date.
• Letting the model pad. Short, exact pages are easier to keep true.
• Documenting everything. Start with the pages support asks about most.
• Skipping the reader. Say who the page is for, and write for that person.

What it costs

Model. From Anthropic's pricing page, checked 31 October 2026: Sonnet 5.5 is $2 per million input tokens and $10 per million output; Haiku 5.5 is $0.10 and $0.50.

Worked example (the token counts are our assumptions). Documenting one module with 10,000 input tokens (code and notes) and a 2,500-token page:

An agent that reads a whole repository, runs commands to check examples and revises will use more. See Claude API pricing.

Seats. A terminal or editor agent plan, if you do not use the API: Claude Code Pro $20 ($17 annual), Codex Plus $20, Copilot Pro $10, Cursor Plus $8, from our pricing pages. See AI coding agent pricing compared.

People. A reviewer reading a 2,000-word page for accuracy takes perhaps fifteen to thirty minutes. That is a good trade against writing it from scratch, and it is the number to track.

Risks and how to review them

For public docs, treat anything the model says about a third-party tool as unverified until you have read that tool's own documentation. Library examples are a common failure; Context7 reduces it by giving the agent current docs, and you still run the code.

Measure it

A falling count of "how do I" support tickets for a documented topic is the best sign the page works. See AI customer support.

Keeping a docs folder healthy over time

A short monthly routine prevents most rot. Have the agent list pages whose source files changed since the page was last edited. Have it run every code block and report failures. Have it check links. Then a person reads the list, fixes the pages that matter and retires the ones nobody needs. Put the routine in a skill so it runs the same way each month, and keep a count of stale pages on a dashboard everyone can see.

Who should do what

Related tasks: AI code review so docs and code are reviewed together, AI testing agent so examples are tested, and AI tools for business for choosing across jobs. If your docs are for plugins or a product with its own hub, keep the source in the repository and publish from there.

Our take

AI is a strong drafting and upkeep tool for documentation, and a weak authority on your product. Draft from sources, run every example, review for facts and tie each page to the files it came from so changes can be found. The cost per page is cents; keeping a human owner for each page is the real commitment. We built this page from vendor documentation, our kit items and published specs, and have not run a documentation programme with these tools.