Skill: Technical Writer

The Technical Writer skill gives Claude a consistent documentation voice. Instead of ad-hoc explanations that change tone every time, you get structured docs that follow the same sections, the same formatting, and the same rules about what to include and what to cut.

What This Skill Does

The skill enforces a style guide every time you ask Claude to write or update docs. It applies four rules:

Voice — active, concise, professional but friendly. "The function returns a list" instead of "A list is returned by the function."
Formatting — headers for structure, code blocks for anything you'd type, lists for steps. No wall-of-text paragraphs.
Structure — every doc follows the same skeleton: Overview → Installation → Usage → API. Readers always know where to look.
Forbidden patterns — no first person ("we", "I"), no marketing fluff, no paragraphs longer than four sentences.

The result is documentation that reads like it came from one person, even when five different engineers contributed code.

How to Install

Create the skills directory:

mkdir -p .claude/skills/technical-writer

Save the template below as .claude/skills/technical-writer/SKILL.md.
Trigger it with a prompt like: "Write documentation for src/utils/format.ts using the technical-writer skill."

SKILL.md Template

# Technical Writer Skill

## Triggers
- "Write docs"
- "Create README"
- "Explain this"

## Style Guide
1.  **Voice:** Active, concise, professional but friendly.
2.  **Formatting:** Use headers (##), code blocks, and lists.
3.  **Structure:** 
    - Overview (What is it?)
    - Installation (How to get it?)
    - Usage (How to use it?)
    - API (Technical details)

## Forbidden
- Do not use "we" or "I". Use "the system" or "you".
- Do not use wall-of-text paragraphs. Break it up.

Real-World Usage Example

Prompt:

Write documentation for this function using the technical-writer skill.

export function formatCurrency(cents: number, currency = 'USD'): string {
  return new Intl.NumberFormat('en', { style: 'currency', currency }).format(cents / 100);
}

Expected output:

formatCurrency

Converts an integer amount in cents into a localized currency string.

Usage
import { formatCurrency } from './utils/format';

formatCurrency(1999);        // "$19.99"
formatCurrency(1999, 'EUR'); // "€19.99"
formatCurrency(0);           // "$0.00"
API

Parameter Type Default Description
cents number — Amount in minor units (e.g., cents).
currency string 'USD' ISO 4217 currency code.

Returns: string — the formatted currency value.

The function divides by 100 before formatting. Pass amounts in their smallest unit (cents, pence) to avoid floating-point rounding errors.

Parameter	Type	Default	Description
`cents`	`number`	—	Amount in minor units (e.g., cents).
`currency`	`string`	`'USD'`	ISO 4217 currency code.

Customization Tips

Add a doc-type preset. If you write a lot of API references, add a rule: "For API docs, always include a parameter table and a return type." Claude will generate the table automatically.
Enforce a tone for user-facing docs. Add "For user-facing docs, use second person ('you') and keep sentences under 20 words." This keeps onboarding guides scannable.
Pin a code-block language. If your project is single-language, add "Always specify the language in fenced code blocks (ts, bash)." This prevents unstyled blocks in your rendered docs.
Add a "no assumptions" rule. Append "Do not invent parameters or return values. If unsure, write 'TODO: verify'." This stops Claude from hallucinating API signatures.

Combining With Other Skills

code-reviewer — After reviewing a function, pass it to technical-writer to generate or update its docs. The reviewer already knows the edge cases, so the docs end up covering them.
data-analyst — When the analyst produces a notebook, use technical-writer to turn the findings into a readable report with proper structure.
ux-designer — Use technical-writer to document component props and usage examples right after ux-designer generates the component.

Common Mistakes to Avoid

Asking for docs without showing the code. Claude can't document what it can't see. Always paste the source or point it at the file path.
Skipping the structure rule. If you let Claude pick its own headings, you'll get a different layout every time. The fixed Overview → Installation → Usage → API skeleton is what makes the skill useful.
Not editing the forbidden list. The defaults ban "we" and "I", but your team might also want to ban phrases like "simply", "just", or "obviously". Add them and Claude will strip them out.
Generating docs once and forgetting them. Docs drift. Re-run the skill when the API changes — the fixed structure makes diffs easy to review.
Documenting implementation details instead of behavior. Good docs tell the reader what the function does and what to pass it, not how the internals work. If Claude starts explaining the algorithm, cut it — that belongs in a comment, not user-facing docs.

Share this article