secondary-text-audit
Skill904 starsChanged 5 days agoMITView on GitHub
Audit the subordinate copy in a UI — section descriptions, field helper text, hints, card subtitles, empty-state body copy, tooltip bodies — against the secondary-text ruleset, and emit a per-string keep/rewrite/delete verdict table a coding agent can apply. Use this skill whenever the user asks to review, tighten, trim, or clean up UI copy, microcopy, descriptions, helper text, subtitles, hints, or empty states; asks "is this copy necessary?", "does this description earn its place?", "why is our UI so wordy?"; wants a settings page or dialog decluttered; or is writing new secondary text and wants it checked before it ships — even if they don't say "audit". For view-level UX behavior (labels, missing states, redundancy, one-primary-action), use ux-semantics-audit; for palette and tokens, use color-audit. This skill owns everything about whether a piece of subordinate copy should exist at all and how it should read.
In this repository18 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- docs/CLAUDE.mdCLAUDE.md
- ios/CLAUDE.mdCLAUDE.md
- rome_apps/CLAUDE.mdCLAUDE.md
- add-oauth-integrationSkill
- babysit-prSkill
- color-auditSkill
- dddSkill
- file-issueSkill
- imports-ofSkill
- loop-northstarSkill
- loop-reconcileSkill
- move-codeSkill
- release-rome-imageSkill
- respond-to-reviewSkill
- todos-to-github-projectSkill
- ux-semantics-auditSkill
- validate-oauth-integrationSkill
The file
We split this skill into the rules it gives an agent
12 rules. About 0 are common, 4 are distinctive, and 8 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
8
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 25
Uncertainty resolves to
delete, with one exception: When a string sits between delete and rewrite, choose delete — the primary label … - Very specific: line 44
Write the sentence that ships, in the register docs/ui/VOICE.md fixes.
- Very specific: line 97
Read docs/ui/VOICE.md first — it fixes the register, the person, and what a description must carry, and every rewrite row is written in it.
- Very specific: line 123
Ask the four questions of every string, in order, stopping at the first failure.
- Distinctive: line 129
Before emitting, re-examine the table:
- Very specific: line 131
Every keep — name its kind of fact out loud.
- Very specific: line 133
Every rewrite — read the replacement alone, without the original.
- Very specific: line 135
Every delete — confirm the information is not lost: either it was restatement, or the surviving payload moved into another row's …
- Distinctive: line 138
Every row — is the label quoted the one that actually renders?
- Distinctive: line 142
Use exactly this structure:
- Distinctive: line 180
When the user asks for the changes and not just the table:
- Very specific: line 190
Verify with pnpm typecheck, then look at the surface in the running dashboard.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Secondary-Text Audit
Extract every piece of subordinate copy in a surface and put each one on trial. The ruleset's premise is that secondary text defaults to absent: it exists only to carry information the user needs before acting that the label, the control's shape, and the surrounding context do not already give them. Most shipped secondary text describes what something is, which the label already did. That text goes.
The output is a verdict table, not prose commentary. Every row resolves to
keep, rewrite, or delete, and every rewrite carries its replacement
string.
Design philosophy (read this — it shapes every judgment call)
- Delete is the expected majority outcome. This is the inversion that makes
the skill useful. An audit that keeps most of what it finds has not applied
the ruleset; it has admired the copy. If your table is mostly
keep, re-run the fact test on everykeeprow and mean it. Uncertainty resolves to
delete, with one exception. When a string sits betweendeleteandrewrite, choosedelete— the primary label almost always suffices. This is the opposite of the precision-over-recall bias inux-semantics-audit, and deliberately so: a wrongkeepis permanent noise on the screen.The exception is a string carrying a cost, a scope, or a cause. Deleting one of those does not cost a line of copy, it costs the reader the fact that made the screen actionable. When the string tells the user what an action breaks, where a setting stops applying, or why a surface is in a state they did not choose, uncertainty resolves to
rewrite. Trim it to the fact and keep it.- Judge the rendered pair, never the key name. A verdict needs the label
the user actually sees next to the text. A key called
*.descriptionmay render as a card subtitle, a tooltip body, a dialog description, or nothing at all. - Fact before verdict. Name which kind of fact the text carries before
deciding anything. A string carrying none is
delete— that is the rule, not a shortcut. - A rewrite must be a real string. "Tighten this" is not a replacement.
Write the sentence that ships, in the register
docs/ui/VOICE.mdfixes. If you cannot write one that passes the rules, the verdict wasdelete. - A shorter string is not automatically a better one. Trimming is the means,
not the goal. A replacement that reads as a system log has failed even when
every word left is load-bearing — check it against
VOICE.mdbefore it ships.
Workflow
Step 1 — Scope the audit
The unit of analysis is the surface: a page, tab, dialog, drawer, or self-contained section. Secondary text is judged against what renders beside it, so the scope must be something the user sees at once.
- Whole package → audit surface by surface; do not emit one 120-row table.
- A named page ("the settings page", "the app detail page") → that page and the dialogs it opens.
- New copy the user just wrote → that string plus its label and siblings.
Step 2 — Extract the candidates
node .claude/skills/secondary-text-audit/scripts/extract-secondary-text.mjs --scope settingsThe script collects both carriers Rome uses — i18n locale keys under
packages/web/src/i18n/locales/<locale>/ and literal strings in *Description
components and description= / subtitle= / hint= / helperText= props —
pairs each with its label, resolves it back to the component that renders it,
and prescreens it. --scope <substr> filters by key or location; --json emits
the rows for programmatic use; --root points at another package.
Its flags are advisory triage, not verdicts:
forbidden:*andgeneric-verbare near-certaindelete, but confirm the match is real before writing it down.no-signalfires on most rows. It means "re-examine", nothing more — real cost text often has no number.sr-onlyrows are out of scope entirely. Never delete them.UNRENDEREDmeans no call site was found. Confirm with a grep for the bare key before calling copy dead, then verdict itdelete.dynamic-keyandkey-refare the weakest resolutions and can over-match: a computed key likeconnections.headings.${role}matches every sibling under that prefix, including ones the union type never produces. Open the cited line and check the key can really reach this row before trusting it — a row that only resolves this way is adeletecandidate hiding behind a wildcard.label-inferredmeans the label shown is a guess from the key path. Read the component before judging that row.
Step 3 — Read the ruleset and the voice
Read docs/ui/VOICE.md first — it fixes the
register, the person, and what a description must carry, and every rewrite
row is written in it. Then read
docs/ui/secondary-text.md in full. It
carries the scope, the five kinds of fact, the four-question test, and the
repo rules. Do not
audit from memory of the kind names.
Step 4 — Establish the rendered context
For each surface, read the component and write down, before judging anything:
- the label rendered above/beside each string, verbatim;
- the siblings rendered on the same screen (this decides every difference verdict);
- whether the string is conditional — empty-state only, error-only, first-run only (this decides first-step text and pulls error copy out of scope);
- what the control's shape already says — a toggle, a file input, and a destructive-variant button each carry information the copy need not repeat.
This step is what separates a verdict from a guess. Skipping it produces plausible-sounding tables that are wrong about half the rows.
Step 5 — Run the test per string
Ask the four questions of every string, in order, stopping at the first
failure. Then, for rewrite rows, check that the replacement passes the four questions on its own and
obeys VOICE.md.
Step 6 — Verdict-hardening pass
Before emitting, re-examine the table:
- Every
keep— name its kind of fact out loud. If naming it takes a paragraph of justification, it isrewriteordelete. - Every
rewrite— read the replacement alone, without the original. Does it pass the four questions as a new string? Does it lead with the fact? - Every
delete— confirm the information is not lost: either it was restatement, or the surviving payload moved into another row's replacement. Say which. - Every row — is the label quoted the one that actually renders?
Step 7 — Emit the report
Use exactly this structure:
# Secondary-Text Audit: <surface>
## Summary
<2-4 sentences: how many strings, the keep/rewrite/delete split, and the single
pattern driving most deletions on this surface.>
## Verdicts
| Location | Label | Secondary text | Fact | Verdict | Replacement |
|---|---|---|---|---|---|
## Notes
<Only rows needing a reason a reader would otherwise dispute: a `keep` that
looks like description, a `delete` whose payload moved elsewhere, a `rewrite`
that changes placement. One line each, referencing the location.>
## Out of scope
<Strings the extractor surfaced that the ruleset excludes — sr-only
descriptions, error messages, placeholders, dev-gallery copy — with the
exclusion that applies. Keeps the next reader from re-litigating them.>Column rules:
- Location —
file:lineof the render site, plus the i18n key when there is one. The applying agent needs both: the key to edit, the line to check. - Fact — one of the five kinds, or
none. - Verdict —
keep,rewrite, ordelete. - Replacement — required for
rewrite, empty fordeleteandkeep.
Order rows by render order on the surface, not by verdict. The applying agent walks the file top to bottom, and a reader checking your work walks the screen.
Step 8 — Applying the verdicts
When the user asks for the changes and not just the table:
- A
deleteon an i18n key removes it from every locale underpackages/web/src/i18n/locales/—enandzh-CNtoday. A key deleted fromenalone leaves the other locale still rendering the string. - A
rewriteupdatesenand marks the other locales for retranslation; do not hand-translate unless the user asks. - Deleting the last child of a key object removes the empty parent too.
- Removing a rendered string usually leaves a dead wrapper element — delete the
<p>or thedescription={...}prop, not just the key. - Verify with
pnpm typecheck, then look at the surface in the running dashboard. Copy changes are exactly the class of change a type check cannot catch: a deleted key that is still rendered fails at runtime as a raw key string, not at build time.
Division of labor
| Question | Skill |
| Should this description exist, and how should it read? | secondary-text-audit |
| Does this view have the right labels, states, and emphasis? | ux-semantics-audit |
| Is the palette itself sound? | color-audit |
The seam with ux-semantics-audit is its consistent-terminology and
label-outcome-clarity rules: those judge the label, this skill judges what
hangs beneath it. When a description only exists because the label is wrong, say
so in Notes and name the ux-semantics-audit follow-up rather than writing a
replacement that props up a bad label.
What this skill does NOT do
- Judge labels, button text, or headings — that is the primary layer.
- Own tone or brand voice —
docs/ui/VOICE.mddoes. This skill decides whether a string exists and what it must carry; every replacement it writes must obey that file. - Rewrite error messages or validation text — different rules, out of scope.
- Translate. It flags locales that need retranslation; it does not write them.
- Apply its own verdicts unless asked. The table is the deliverable.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

