Guide · Agent skill
How to use the better-writing agent skill for interface copy
Updated · written with AI from the project's own documentation and checked against our catalogue data
The better-writing skill is an agent skill that writes and reviews the words inside a product's interface, such as button labels, error messages, empty states and confirmation dialogs. This guide explains what an agent skill is, how to install better-writing, how to ask for it in plain language and what to check before you rely on its output. After reading, you will be able to add the skill to Claude and use it on your own interface text.
Better Writingjakubkrehel/skills · MIT Download the skill Quick start
- 1Download the ZIP. Get the better-writing ZIP from the skill's page on this directory.
- 2Unzip into a skills folder. Unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder for one project.
- 3Or upload in the Claude apps. In the Claude apps, go to Settings → Capabilities → Skills and upload the skill.
- 4Ask in plain language. Describe the copy task, name the screen or element and share the strings or files involved.
- 5Check the findings. Review each flagged item, apply the fixes that match your product's voice and note any hand-offs to typography, accessibility or layout skills.
What the better-writing skill makes the agent do
Once installed, the agent checks and writes interface copy. Before it writes anything, it looks for the existing copy and terminology in your product, so new text matches the product's voice. For example, if the menu says 'Archive', a new toast should not say 'Move to storage'.
It also flags wording that misleads people or leaves them without a clear next step. It follows set rules, such as starting buttons with a verb, writing errors that say how to fix the problem and building translatable sentences instead of joining fragments together.
- Writes and reviews labels, errors, empty states and confirmations
- Checks new copy against the terms already used in your locale files, CMS or API
- Flags misleading copy and missing next steps
- Does not cover rendering, typography or accessibility markup, which the skill hands off to other skills
Install the better-writing skill
You can install the skill in one of two ways. Download the ZIP from the skill's page on this directory and unzip it into ~/.claude/skills/ to make it available for your user account, or into a project's .claude/skills/ folder to make it available only to that project.
If you use the Claude apps instead, upload the skill under Settings → Capabilities → Skills.
- Personal install: unzip into ~/.claude/skills/
- Project install: unzip into the project's .claude/skills/ folder
- Claude apps: Settings → Capabilities → Skills, then upload
~/.claude/skills/Know what the skill package contains
The package has three files: SKILL.md, which holds the main instructions; patterns.md, which holds templates for destructive flows and status copy and recipes for plurals and locale formatting; and agents/openai.yaml. The skill's instructions point to patterns.md when it needs a template, so keep all files together when you unzip or upload.
- SKILL.md: main instructions and rules
- patterns.md: destructive-flow and status-copy templates, plural and placeholder recipes
- agents/openai.yaml: agent configuration file included in the package
Trigger the skill with natural requests
You do not need a special command. Describe the copy task in plain language and name the element or the screen. Give the agent the files or strings in question, since the skill starts by searching for the existing copy around your change.
Useful requests name the kind of text and the goal, for example reviewing a set of error messages before release, or writing an empty state for a new screen. You can also ask for a check of translation risk in a set of strings.
- 'Review the error messages in this form for anything that doesn't say how to fix the problem.'
- 'Write an empty state for the projects page that offers one next action.'
- 'Check these button labels. Are they verb-first and consistent with our existing terms?'
- 'Look at this confirmation dialog for deleting a workspace and suggest the title, body and buttons.'
Review what the skill reports and what it leaves to others
The skill treats a deliberate brand voice as intentional. It raises a departure from plain language only when that departure causes inconsistency, ambiguity, translation risk, or a tone the stakes do not support. Rewording that only reflects personal taste is not reported as a finding.
Keep the division of work in mind. Text rendering, including text-transform, truncation and smart punctuation, belongs to better-typography. Error markup, announcements and accessible names belong to better-accessibility. Room for translated strings belongs to better-layout. Marketing and long-form content are outside the skill's scope.
- Expect findings tied to consistency, clarity, next steps and translation risk
- Expect hand-offs for rendering, accessibility markup and spacing
- Check the output against your own style guide before shipping
Apply the rules to your copy
The skill applies a fixed set of rules. Buttons start with a verb, such as 'Save draft' or 'Delete project'. Errors say what to fix, such as 'Enter a date as DD/MM/YYYY' rather than 'Invalid date'. Toggles are labelled for the ON state, such as 'Send read receipts'. Link text names its destination, such as 'Read the billing docs' rather than 'Click here'.
Strings are built whole, with placeholders and plural rules, rather than concatenated. The source gives this example of what to avoid: "You have " + n + " new messages".
- Verb-first buttons
- Errors that name the fix, with no 'Oops' or exclamation marks
- Toggles described by their ON state
- Destination-based link text
- Whole sentences with placeholders, not fragments
<!-- Bad: a shrug -->
<p>No results.</p>
<!-- Good: orientation plus a next step -->
<p class="font-medium">No projects yet</p>
<p class="text-sm text-zinc-500">Projects keep your tasks and files together.</p>
<button class="mt-4">Create a project</button>What people use it for
- Reviewing error messages in a form before a release, so each one says how to fix the problem
- Writing an empty state for a new page with one clear next action
- Checking that labels, toasts and error messages use the same terms for the same objects
- Reviewing confirmation dialogs for destructive actions, with a title that names the object and buttons that name the action
Frequently asked questions
How do I install the better-writing agent skill?
Download the ZIP from the skill's page on this directory and unzip it into ~/.claude/skills/ for your user account, or into a project's .claude/skills/ folder. In the Claude apps, you can instead upload it under Settings → Capabilities → Skills.
Is the better-writing skill free?
The skill is published under the MIT licence, as stated on its page. The source does not list any price, so check the licence text in the package for the terms that apply to your use.
What do I need to run better-writing?
The source lists no requirements. The skill does not run scripts and does not use the network, according to its listing. It works on the interface text you give it.
Does better-writing check accessibility or typography?
No. Rendering, text-transform, truncation and smart punctuation belong to better-typography. Error markup, announcements and accessible names belong to better-accessibility. Room for translated strings belongs to better-layout.
Why isn't the skill giving me a result after I upload it?
The source does not include troubleshooting steps. Check that the skill folder is in the right location, either ~/.claude/skills/ or the project's .claude/skills/, and that SKILL.md and patterns.md are together in the same folder.
Can I use better-writing for marketing copy or blog posts?
No. The skill is scoped to interface copy only, so it is not built for marketing or long-form content. Use it for labels, errors, empty states and confirmations.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use better-writing if you are a product designer, front-end developer or writer who needs interface text checked for consistency, clear next steps and translation risk before release. Pick something else if you need help with marketing copy, long-form content, or the rendering and accessibility work that this skill hands off to other skills.
Download the skill