How to use the Technical Writing Expert agent skill

What the Technical Writing Expert skill makes the agent do

The skill gives the agent a working method for developer documentation. It tells the agent to sort material into four modes: tutorials for learning, how-to guides for solving a specific problem, reference for looking up facts, and explanations for understanding why something works the way it does.

It also sets formats for common documents. READMEs follow a set order of sections, API reference entries list parameters with types and defaults, return values and error conditions, architecture decision records (ADRs) have title, status, context, decision and consequences sections, and changelogs group entries under Added, Changed, Deprecated, Removed, Fixed and Security headings. The agent is told to write in second person for instructions, use present tense for descriptions, and suggest Mermaid or PlantUML diagrams for architecture, sequence flows and state machines.

• READMEs: name and one-line description, badges, installation, quick start, API overview, contributing and license
• API reference: signature, typed parameters with defaults, return value, errors, working example
• ADRs: title, status, context, decision, consequences
• Changelogs: Keep a Changelog grouping

Download and install the skill

Download the technical-writer ZIP from our page. The skill's package contains a single file, SKILL.md, so you can check the contents after unzipping. Then choose one of the two install locations below.

For a personal install that works across your projects, unzip the file into ~/.claude/skills/. For a single project, unzip it into that project's .claude/skills/ folder so the skill travels with the repository.

If you use the Claude apps instead of files on disk, open Settings, go to Capabilities, then Skills, and upload the skill there.

• Personal: ~/.claude/skills/
• Project only: .claude/skills/ inside your project
• Claude apps: Settings → Capabilities → Skills, then upload

Ask for documentation so the skill is used

The source does not list exact trigger phrases, so the simplest approach is to name the kind of document you want in plain words. The skill's description covers API docs, READMEs, ADRs and developer documentation, so requests that mention those topics are the best fit.

Give the agent the facts it needs: the project name, what it does, the function or endpoint names, the parameters and the decision you are recording. The more specific your input, the less the agent has to guess.

• Write a README for this CLI tool. It is a file-backup utility with three commands: init, run and verify.
• Draft an API reference entry for the POST /orders endpoint, including parameters, errors and one working example.
• Write an ADR recording why we chose PostgreSQL over DynamoDB. Status is proposed.
• Turn these commits into a changelog entry using Keep a Changelog headings.
• Explain how our job queue works, as an explanation rather than a tutorial.

Review and check the output

The skill tells the agent to write complete, runnable code examples, but it does not run or check them. Treat every code sample as a draft. Copy it into a clean environment and run it yourself before publishing.

Check facts the agent could not know, such as version numbers, default values in your real code and endpoint paths. The skill does not verify your codebase, so compare the reference entries with the actual source.

• Run every code example yourself
• Compare parameter names, types and defaults with the real code
• Confirm the ADR status and the decision wording match what the team agreed

Safety notes: scripts, network and requirements

The source lists no requirements, says the skill does not run scripts, and says it does not use the network. The package contains only SKILL.md, which is a text file of instructions.

Because the skill only shapes how the agent writes, the main risk is inaccurate output rather than system access. Review drafts before you commit them or publish them.

• Requires: nothing listed in the source
• Runs scripts: no
• Uses network: no
• Files: SKILL.md only

Tips for better documentation output

Ask for one document type at a time. The skill separates tutorials from reference material, so a combined request can produce a muddled result. If you want a tutorial, name it as a tutorial and say who the reader is.

Keep documentation close to the code it describes. The skill's guidance is that colocated docs are updated more often than docs kept in separate repositories, so place generated files in the repository they document.

• Name the document type and the reader
• Give exact names of functions, endpoints and options
• Ask for diagrams when you need architecture or sequence views
• Ask for alternatives or the decision context for ADRs