Skip to main content
skill CX Codex

writing-user-docs — Claude Code skill for user documentation style

writing-user-docs — a skill that sets voice, scope, and structure for user-facing docs. Use it when an agent writes or reviews anything a person reads to learn a tool.

MIT 1,500 installs ★ 1,715 updated 2026-10-08

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add callstackincubator/agent-skills --skill writing-user-docs -a claude-code
Open on GitHub

What writing-user-docs does

This skill tells the agent to write for the person using the tool, not for the one who built it. A user can be an end user of an app or a developer installing a library. Either way, the reader is not implementing the thing.

The rules cover everyday English, second person, active voice. Cut words like "just", "simply", and "easy" — they add nothing when things work and read as mockery when they don't. Marketing adjectives are out. One term per concept, matching the UI exactly: a button called Workspace never becomes "project" in the text.

Structure follows user goals, not features. Headings say what people want to do, not module names. Prerequisites and limits go up front, before step one. Pick one recommended path and give alternatives a short note at the end, or nothing.

The skill pushes hard on the unhappy path: write down what the error says, what causes it, and what to do next. Say what a feature doesn't do when users predictably assume it does. Put warnings before destructive steps, never after. Before publishing, the draft gets one pass for filler, implementation leaks, sentences you wouldn't say aloud, and unanswered failure cases.

It's not for internal engineering docs, architecture notes, RFCs, or code comments.

What it helps with

  • keep one voice across help center, tutorials, and release notes
  • strip implementation details that confuse readers
  • organize a page around the reader's task, not the screens
  • cover error cases and what to do after them
  • review a draft before publishing

Example prompts for the agent

  • Write docs for this feature following the writing-user-docs skill.
  • Rewrite this README: keep only what a developer installing the library needs.
  • Review this help article for tone, filler, and implementation leaks.

How to install writing-user-docs

1Skills CLI (Vercel)

npx skills add callstackincubator/agent-skills --skill writing-user-docs -a claude-code

2Manually: put the files in place

~/.claude/skills/writing-user-docs/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/writing-user-docs/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about writing-user-docs

How do I install writing-user-docs in Claude Code?

Run npx skills add callstackincubator/agent-skills --skill writing-user-docs -a claude-code. The skill lands at ~/.claude/skills/writing-user-docs/SKILL.md.

What does writing-user-docs do?

It defines house style for user-facing documentation: voice, scope, structure, and what to leave out. The agent applies it when writing, editing, or reviewing docs for users.

When should I not use this skill?

Skip it for internal engineering docs, architecture write-ups, RFCs, and code comments. The skill is only for text a user reads to learn how to use a tool.

Source text

SKILL.md · MIT
---
name: writing-user-docs
description: House style for user-facing documentation — voice, scope, structure, and what to leave out. Use this skill whenever writing, editing, or reviewing anything a user reads to learn how to use a tool — help center articles, getting-started guides, tutorials, feature docs, README usage sections, in-app help, release notes, or FAQ entries. Trigger it even when the request is phrased plainly — "document this feature", "write docs for X", "explain this to users", "write a README for this library", "turn these notes into a guide" — and even when no style guidelines are mentioned. Also use it to review existing docs for tone, bloat, or leaked implementation detail. Do not use it for internal engineering docs, architecture write-ups, RFCs, or code comments.
---

# User-facing documentation

Write for the person using the tool, not the person who built it.

"User" means whoever uses the thing. For an app, that's an end user. For a library, it's the developer who installs it. Either way they are *not* implementing it, and the docs should reflect that.

## Voice

Everyday English — the way you'd explain it to a colleague sitting next to you. Formality doesn't add authority, it just adds distance and words.

- **Second person, active, present tense.** "You tap Save," not "the Save button should be tapped" or "the user will then be able to save."
- **Cut "just," "simply," "easy," "obviously."** They add nothing when things work, and read as mockery when they don't.
- **No marketing adjectives.** "Powerful," "seamless," "robust," "intuitive" — that's the author admiring the product. The reader is mid-task and doesn't care.
- **One term per concept, matching the UI exactly.** If the button says *Workspace*, the docs never say "project" or "team space." Varying your vocabulary is good prose and bad documentation — every synonym reads as a new concept.

## Scope: what goes in

Include only what the reader needs to use the tool. The default is to leave things out.

**Implementation details stay out.** Not the database, the queue, the framework, the algorithm's name, the internal service, the refactor it took to ship. The test isn't "is this technical?" — it's **"will the reader be surprised, or make a wrong decision, without it?"**

Observable behavior passes that test even when it sounds technical, and belongs in the docs: rate limits, offline behavior, what syncs and when, where files are stored, what happens on a conflict, what survives a reinstall. The machinery producing that behavior doesn't.

**Concise means no filler, not short.** Every sentence earns its place. A thorough troubleshooting section is still concise if none of it is padding — and a two-line page is bloated if one line is a welcome message. Cut preambles, restatements of the heading, and "in this article you will learn."

## Structure

- **Organize by user goal, not by feature or screen.** Headings are things people want to do — "Share a report with someone outside your team" — not nouns like "Sharing module."
- **Lead with the outcome, then the steps.** People need to know they're on the right page before investing in step 1.
- **Prerequisites and limits go up front.** Required plan, permission, platform, file size cap. Discovering the blocker at step 6 is the worst possible moment.
- **One page answers one question, and stands alone.** Most readers arrive from search or a deep link, never from page 1. Assume no one read the previous page; link instead of assuming.
- **Pick one path.** Where three ways exist, document the recommended one. Alternatives get a short note at the end, or nothing.

## Cover the unhappy path

This is the most-skipped section and the one people actually search for.

- **Document the failure cases**: what the error says, what causes it, what to do next.
- **Say what the feature doesn't do** when users predictably assume it does. Cheaper than a support ticket.
- **Warn before destructive actions, never after.** The warning goes above the step it applies to.

## Keep it from rotting

- **Real examples with real-looking data.** No `foo`, no `test123`, no lorem ipsum. Examples should be copy-pasteable and produce the result shown.
- **No time-relative language.** "New," "recently," "currently," "coming soon" — all rot silently. So do roadmap promises.
- **Walk every procedure literally.** If someone following it word-for-word can't finish, the doc is wrong — not the reader.

## Before publishing

Read the draft once looking only for these:

1. Anything the reader doesn't need to finish the task → cut it.
2. Anything about how it works internally → cut it, unless behavior depends on it.
3. Any sentence you wouldn't say out loud → rewrite it.
4. What happens when this goes wrong → is that answered?

© callstackincubator · MIT · callstackincubator/agent-skills

Similar skills

All skills for Writing and docs →

From the same set10

The whole set →
upgrading-react-native upgrading-react-native upgrades React Native apps to newer versions by applying rn-diff-purge template diffs, migrating iOS and Android native config, and resolving CocoaPods and Gradle conflicts. CX Codex +1 14,100installs github-actions Reusable GitHub Actions patterns to build React Native apps for iOS simulators and Android emulators in the cloud and download artifacts. Simplifies CI pipeline setup and scripted retrieval via gh CLI or REST API. CX Codex +1 12,400installs validate-skills validate-skills is a Claude Code skill that checks skills in skills/ against agentskills.io and Claude Code practices during skill collection authoring and review. CX Codex +1 7,800installs react-navigation react-navigation is a Claude Code skill for building navigation interfaces with React Navigation. It covers stacks, tabs, drawers, headers, sheets, and safe-area handling. CX Codex +1 6,200installs react-native-brownfield-migration react-native-brownfield-migration guides incremental React Native or Expo adoption in native iOS and Android apps using @callstack/react-native-brownfield. CX Codex +1 5,700installs create-react-native-library create-react-native-library scaffolds a React Native library or a local native module inside an app, then points the agent at the right implementation doc. CX Codex +1 5,600installs react-native-tv-best-practices react-native-tv-best-practices is a Claude Code skill for reviewing React Native TV apps. It applies to work on remote navigation, playback, TV layouts, accessibility, and device performance. CX Codex +1 2,800installs assess-react-native-migration assess-react-native-migration audits product repositories and decides whether a mobile app should move to React Native, before anyone writes migration code. CX Codex +1 2,700installs

Project sponsors

Companies that keep this analytics open