Claude is strong at turning material that already exists (a spec, a ticket thread, a changelog) into a clean first draft, and at reading a page the way a confused user would. It is weak at facts it was not given: it cannot run your product, so it fills gaps with plausible behaviour. Work in three passes. First give it the source of truth and forbid anything outside it. Then ask for a draft with every assumption listed. Then switch roles and make it attack the draft for ambiguity. A person who can run the product still has to verify every step and every example.
Nesta página
- What does Claude need before it writes a word of documentation?
- How do you turn a spec into reference docs without invented behaviour?
- How do you turn tickets into release notes people read?
- How do you write a how-to from a messy support thread?
- How do you review a draft for ambiguity?
- Where does Claude fail at this?
- Which writing skill fits which job?
- How do you install a technical writing skill in Claude?
- Related guides
- Frequently asked questions
API Technical Writer AI Skill - Bodhi
Get API Technical Writer AI Skill - Bodhi →What does Claude need before it writes a word of documentation?
The most common failure is asking for "documentation for our export feature" and receiving a polished page about an export feature that does not exist. Give it a source of truth and a reader.
The source. An OpenAPI file, a Postman collection export, a code comment block, a pull request description, a design doc. Paste the material itself, not your summary of it. If you have no source, you are writing from memory, and Claude will mirror your gaps.
The reader and what they are doing. "A backend developer integrating payments on a deadline" writes a different page from "an admin configuring SSO for the first time". Name the task, not the persona.
The document type. Tutorial, how-to, reference and explanation serve different readers; the Diátaxis framework describes the four and is worth ten minutes before you brief anyone. Tell Claude which one you want. A page that tries to be all four is the usual reason docs are unreadable.
Your style rules. Paste your house style, or name a published one you follow. Without it you get Claude's defaults: friendly, a little padded, with "simply" and "just" in places a stressed reader will resent.
What you do not know. List open questions. It is much better to have the draft carry [TO CONFIRM] markers than a confident guess.
How do you turn a spec into reference docs without invented behaviour?
A spec describes shape, not behaviour. Claude can render shape very well and will quietly invent behaviour. The prompt below separates the two.
The last line matters: restating a field name as its own description is the commonest low-quality docs habit, and models do it by default. Section 5 is the real deliverable. It turns "docs" into a short list of questions for the engineer, which is where the genuine value comes from.
Example output (illustration only, invented endpoint):
How do you turn tickets into release notes people read?
Release notes written from ticket titles read like an internal to-do list. Users want "what changed for me and do I need to do anything".
The "Unclear" bucket keeps the draft honest and gives you the list of questions to send to engineering. Run it once and expect to cut at least a third; the grouping is useful, but marketing adjectives creep in and should be stripped.
How do you write a how-to from a messy support thread?
Support threads contain the real task, the real wrong turns and the real fix. They are the best source for a how-to page, and the worst format.
UI labels are where Claude embarrasses writers: it names a button that was renamed two releases ago or never existed. The [CHECK UI LABEL] marker makes those visible. Someone must then run through the steps on a real account, and nothing in this workflow replaces that.
Another job, another skill
Whitepaper and Technical Marketing Writer, Amadora — $19. For the document a sceptical technical buyer reads to the end: one defensible differentiator, a claims register and sign-off flags on every number. Hands endpoint-and-parameter content back to the docs side.
How do you review a draft for ambiguity?
This is where Claude earns its place regardless of who wrote the page. It will read what is on the page, not what you meant.
Point 6 (one word for two things) is the sort of defect that a human editor catches after weeks on a doc set and Claude catches in seconds. Follow it with a search of your glossary and fix the term once everywhere, not just on this page.
Whitepaper & Technical Marketing Writer AI Skill - Amadora
Get Whitepaper & Technical Marketing Writer AI Skill - Amadora →Where does Claude fail at this?
It documents the product it imagines. Anything not in your source gets filled with a plausible default: rate limits, retry behaviour, permissions. The [TO CONFIRM] convention and a "Not in the spec" list are the controls.
It cannot run your software. Steps, screenshots, UI labels and error text must be verified by a person on a real account. Code samples must be executed, not admired.
Spec and reality disagree, and it trusts the spec. If an endpoint returns something the OpenAPI file does not describe, Claude will document the file. Pair it with real response payloads and your support tickets.
It smooths over your terminology. It will rotate synonyms for "workspace", "project" and "account" because variation reads nicely, which is exactly wrong for documentation. Give it a glossary and say terms are not to be varied.
It adds friendly padding. Openers like "In this guide we will explore" and reassurance between steps lengthen pages and slow scanning. Specify a word limit per step and no introductory paragraph.
It cannot decide what to document. Which pages matter, in what order, and what is deliberately left out are product and audience decisions. It can propose a structure; the call is yours.
Which writing skill fits which job?
| Skill | Best for | Price |
|---|---|---|
| API Technical Writer, Bodhi | Reference pages from OpenAPI/GraphQL, auth, errors, webhooks, spec-vs-docs audits | $19 |
| Whitepaper and Technical Marketing Writer, Amadora | Whitepapers, technical briefs, benchmark papers for a technical buyer | $19 |
How do you install a technical writing skill in Claude?
With an All-in-one subscription there is nothing to download. Open Customize → Connectors, click +, then Add custom connector, and paste https://mcp.kissmyskills.com/mcp. Sign in with your email, then ask for the skill by name, for example "load Bodhi". Signing in is free, and your first skill call starts a 7-day free trial with every skill. The same connector works in ChatGPT, Claude Code, Codex and Cursor; steps are on the connector page.
Bought the single file? It is a .skill file, a ZIP with SKILL.md inside. In Claude, turn on code execution under Settings → Capabilities, then open Customize → Skills, click +, choose Upload a skill and toggle it on. In ChatGPT or Gemini, open the ZIP and paste the contents of SKILL.md into custom instructions.
Need more than one specialist?
Buying API Technical Writer AI Skill - Bodhi gets you one file. The All-in-one subscription loads every skill in the catalog through one connector, in Claude, ChatGPT Business, Enterprise or Edu, Claude Code, Codex or Cursor, and keeps each skill updated when we improve it. $12 a month or $69 a year, with 7 days free and every skill included.
Start the free trial → Why a subscription beats buying filesRelated guides
- AI API Documentation Generator: Write Developer Docs Without Hating It
- How to Use Claude as a Report Writer
- How to Use Claude as a UX Writer
- How to Use Claude as a Backend Developer
Frequently asked questions
Is there a Claude skill for technical writing?
Yes. Bodhi, the API Technical Writer AI Skill ($19), writes reference documentation from OpenAPI or GraphQL specs, including auth, error codes and webhooks. For whitepapers and technical briefs aimed at technical buyers, Amadora ($19) builds the argument and a claims register.
Can Claude write API documentation from an OpenAPI spec?
Yes, for the shape of the API: endpoints, parameters, schemas and examples. It cannot know behaviour the spec leaves out, so ask it to mark gaps with [TO CONFIRM] and list unanswered questions such as rate limits, idempotency and pagination, then get answers from an engineer.
Can Claude write release notes from tickets?
Yes. Paste the ticket titles or changelog lines, name the reader, and ask for entries that say what changed for the user and what action is needed. Have it list vague items separately instead of inventing a benefit, and strip any marketing adjectives that appear.
How do I use Claude to review documentation for clarity?
Ask it to act as a literal-minded new reader and list ambiguous sentences, unclear pronouns, assumed knowledge, unitless numbers and words used for two things, quoting each. Tell it not to rewrite or praise the page, so you get findings rather than reassurance.
What is Claude bad at when writing technical documentation?
It documents behaviour it was not given, cannot run your software to verify steps or UI labels, trusts the spec over real responses, varies terminology that should stay fixed, and pads pages with friendly filler. A person who can run the product must check every step and example.
API Technical Writer AI Skill - Bodhi
Or get it with every other skill in All-in-one: $12/month, 7 days free, every skill.