These 13 documentation prompts help ChatGPT, Claude, Claude Code and Codex write docs people actually use: READMEs, quickstarts, API reference, architecture decision records, changelogs, release notes, code comments and onboarding guides. Each one asks the model to document only what the code does and to flag what it can't confirm.
A general "write a README section for this code" prompt is in the coding prompts collection. The prompts here cover each kind of doc separately.
How do you use these prompts?
Copy a prompt and fill in the blanks in double braces, or keep the default after the colon. {{style:JSDoc}} means JSDoc unless you change it.
Three habits keep AI-written docs accurate:
- Give it the source of truth. Code, config, routes, commit history. A model that can't see the code invents plausible options that don't exist.
- Name the reader. A new contributor, an API consumer and an end user need different docs.
- Check what it wrote. Run every command and example. The Claude Code common workflows page suggests specifying the documentation style you want, asking for examples, and checking the result against your project standards.
In an agent, these prompts work best when you name the folder and let it read the files. The Claude Code best practices guide recommends referencing specific files and pointing to existing patterns in your codebase instead of describing where code lives.
Keep docs next to the code they describe and update them in the same pull request, so reviewers catch drift. A doc that changes with the code stays true far longer than one in a separate wiki.
How do you write a README that works?
1. Audit and rewrite a README
Most READMEs drift out of date. This prompt checks it against the repo before rewriting.
Here is our README and the project's key files:
{{files:package.json, the main entry point, config files}}
README:
{{readme}}
First, list every statement in the README that the files contradict or
don't support: commands, options, versions, file paths. Then rewrite it
with these sections: what it is in two sentences, who it's for,
quickstart, configuration, common problems, and how to contribute. Keep
anything still accurate. Mark what you couldn't confirm with "Check:".
2. Write a quickstart that runs
A quickstart is only useful if every step works on a clean machine.
Write a quickstart for {{project:this project}} that takes a new developer
from a fresh clone to {{goal:the app running locally}}.
Project files:
{{files}}
Number every step. Use only commands that exist in our scripts or
Makefile, and say which file each one comes from. List prerequisites
with versions only if a file states them. End with how to tell it
worked. Note anything a new machine needs that isn't in the repo.
How do you write API documentation?
3. Add reference docs to a module
For a module other people import. Document the public surface, not every helper.
Write {{style:JSDoc}} comments for the public functions and types in this
{{language:TypeScript}} module.
For each: one-line summary, parameters with types and meaning, return
value, errors thrown, and a short example. Skip private helpers. Don't
restate what the type signature already says; explain meaning, units
and constraints instead. Mark any behavior you inferred rather than
saw with "Check:".
{{code}}
4. Document HTTP endpoints from the code
For an API with routes but no reference. The code is the source of truth, not memory.
Write API reference docs for these HTTP endpoints from the route and
handler code below.
{{code}}
For each endpoint: method and path, what it does, auth required, path
and query parameters, request body with an example, success response
with an example, and every error status the code can return with when
it happens. Use Markdown with one section per endpoint. Don't document
anything the code doesn't implement.
5. Write usage examples
Readers copy examples first and read prose second, so examples carry most of the weight.
Write usage examples for {{function:the createClient function}} for
{{audience:developers using our SDK for the first time}}.
Code:
{{code}}
Give four examples, from simplest to most advanced: basic use, a common
option, error handling, and one real-world combination. Each example
must be complete enough to run, with imports. Add one sentence before
each saying when you'd use it.
How do you record decisions?
6. Write an architecture decision record
ADRs capture why a decision was made, which is what future readers need most. Michael Nygard's original ADR post proposes five parts: title, context, decision, status and consequences.
Write an architecture decision record from the discussion below.
Discussion or notes:
{{notes}}
Use these sections: Title (short, names the decision), Status
({{status:Accepted}}), Context (the forces at play, stated neutrally),
Decision (in active voice, "We will..."), and Consequences (good, bad
and neutral). Include the alternatives that were considered and why
they lost. Keep it under one page.
7. Draft a design doc
Use it before building something large, so reviewers can push back on paper.
Draft a design doc for {{feature}}.
Problem and goals: {{goals}}
Constraints: {{constraints}}
Rough idea so far: {{idea}}
Sections: summary, background, goals and non-goals, proposed design,
alternatives considered, risks and open questions, rollout plan, and
how we'll know it worked. Keep the proposed design concrete: data
shapes, interfaces, and the main flow. List open questions I need to
answer before review.
How do you write changelogs and release notes?
8. Turn commits into a changelog entry
Keep a Changelog groups changes as Added, Changed, Deprecated, Removed, Fixed and Security, and recommends keeping an Unreleased section at the top.
Write a changelog entry for version {{version:Unreleased}} from these
commits or pull request titles:
{{commits}}
Follow Keep a Changelog: group entries under Added, Changed, Deprecated,
Removed, Fixed and Security, and leave out empty groups. Write for
people who use the project, not for the team: skip refactors, CI changes
and dependency bumps unless they affect users. Flag anything that looks
like a breaking change.
9. Write release notes for users
A changelog is for developers. Release notes explain what changed for the people using the product.
Turn this changelog into release notes for
{{audience:non-technical customers}}.
{{changelog}}
Lead with the two or three changes users will notice most. Describe
each in terms of what they can now do, not how it was built. Put fixes
in one short list. If anything requires action from users, put it at
the top under "What you need to do". No hype words.
How do you write code comments that help?
10. Comment the why, remove the noise
Good comments explain decisions the code can't show. Bad ones repeat the code.
Review the comments in this code.
1. Remove comments that only restate what the code does.
2. Add short comments where a reader would ask "why?": workarounds,
business rules, non-obvious performance choices, ordering that
matters.
3. Fix comments that no longer match the code.
Don't change any code. Show the result, then list each comment you
removed, added or changed.
{{code}}
11. Document a workaround
Workarounds outlive the bug they work around unless someone writes down when to remove them.
Write a comment for this workaround.
Code:
{{code}}
The problem it works around: {{problem}}
Link to the issue or discussion: {{link:none}}
The comment must say what would go wrong without the workaround, why
this approach was chosen, and the exact condition under which it can be
removed. Keep it to four lines or fewer.
How do you write onboarding docs?
12. Write an onboarding guide
For the doc a new developer reads on day one. In an agent, let it read the repo first.
Write an onboarding guide for a developer joining
{{project:this project}}.
Repo structure and key files:
{{structure}}
Sections: what the system does and who uses it, the main parts and how
they talk to each other, how to run it locally, how to run the tests,
how code gets reviewed and deployed, where to find logs and errors, a
glossary of project terms, and three good first tasks. Mark anything
you inferred from file names alone with "Check:".
13. Write a runbook for a routine task
For tasks done rarely enough that nobody remembers the steps, like rotating a secret or restoring a backup.
Write a runbook for {{task:rotating the database password}}.
How it's done today (notes, commands, chat history):
{{notes}}
Format: when to use this runbook, prerequisites and access needed, then
numbered steps with the exact command for each and what output to
expect, how to verify it worked, and how to roll back if a step fails.
Mark any step that causes downtime. Put secrets as placeholders, never
real values.
Which documentation prompts should you turn into skills?
The changelog and comment review prompts are good candidates for a skill, since they run on every release or pull request. Paste one into the free SKILL.md generator to get a valid SKILL.md. Project instructions for agents are a kind of documentation too: see the guides to AGENTS.md and CLAUDE.md. If the docs reveal confusing code, the refactoring prompts help clean it up.
Kipt keeps prompts like these as Markdown in a private GitHub repo you own. Blanks such as {{style:JSDoc}} stay as fill-in fields, tags and Cmd+K search find the right prompt fast, and skills saved there install into Claude Code or Codex with one command.