Skill v1.0.0
currentAutomated scan73/100version: "1.0.0" name: writing-style description: >- Revise prose so it reads as though a person wrote it, without the tells that give an AI draft away. Use it whenever prose is about to leave your hands, not only when someone asks for it: PR descriptions and PR review comments, issue bodies, commit message bodies, README and documentation sections, design-doc prose, and the summary or explanation you are about to write back to the user. Also use it when someone asks to improve, humanize, clean up, tighten, or revise a draft, or says something sounds robotic or AI-written. Apply it proactively — the drafts that need it most are the ones nobody thought to ask about, and a repo can declare its own terms of art that generic advice would strip out. It is about how the prose reads, not what it says: it does not decide a document's content or supply what the document is missing. allowed-tools: Bash(${CLAUDE_PLUGIN_ROOT}/scripts/skill-preflight.sh *), Bash(true)
!${CLAUDE_PLUGIN_ROOT}/scripts/skill-preflight.sh writing-style 2>&1 || true
When invoked directly with a draft: identify patterns below, revise, return the revised text. When producing prose: apply these patterns from the start rather than producing and then revising.
The rules live in rules.yaml
skills/writing-style/rules.yaml is the single authoritative source. Read it for the banned words, phrases, and frequency thresholds. It carries the terms and the reason for each, grouped by category.
A repository can declare terms of art the rules must not fire on, through a ## Prose Vocabulary: header in its CLAUDE.md. Honor a repository's declaration when you draft in it: shirabe declares tier, journey, and underscore because those are its own vocabulary, not tells.
What no matcher reaches
The judgment_only section of the rule source holds what no matcher decides, and it is where the value is:
- Low information density. Well-formed sentences that say nothing. A
fluent, entirely vacuous document produced ten alerts under three off-the-shelf style packages and not one concerned the vacuity.
- Empty conclusions. A closing paragraph that adds no content.
- Demonstratives with no antecedent. "This" and "that" pointing at
nothing nameable.
- Attribution without a citation. "Studies show" with no study.
- Synonym cycling. Repeat the word instead.
- Forced rule of three. Use the actual count.
- `from X to Y` on no real scale. Measured zero true positives across 46
corpus hits; every one was a genuine state transition.
- `landscape` used figuratively. "Competitive landscape" is a term of
art; "the landscape of modern tooling" is the tell.
Structural patterns
| Pattern | Fix | |
|---|---|---|
| "serves as", "stands as", "boasts" | Use "is/are/has" | |
| "It's not just X, it's Y" | Just say Y | |
| Stacked qualifiers ("could potentially possibly") | One qualifier | |
| Hollow gerunds: "highlighting/underscoring/emphasizing" | Cut or make main clause |
Formatting tells
| Tell | Fix | |
|---|---|---|
| Em dash overuse | Comma, parentheses, or colon. The validator measures the rate per document; a threshold breach means the whole draft, not one sentence. | |
| No contractions | Use "don't", "it's", "we've" | |
| Title Case Headings | Sentence case | |
| Boldface overuse | Bold genuine emphasis only | |
| Uniform paragraph length | Vary naturally |
Over-formality substitutions
| Avoid | Use | |
|---|---|---|
| "In order to" | "To" | |
| "Due to the fact that" | "Because" | |
| "At this point in time" | "Now" | |
| "Prior to" / "Subsequent to" | "Before" / "After" | |
| "With respect to" | "About" or "For" | |
| "Has the ability to" | "Can" |
What human writing has
- Burstiness: dramatic variation, a 3-word sentence next to a 25-word sentence is the target, not mild variation
- "And", "But", "Or" as sentence starters are fine
- Specifics over abstractions: name the file, cite the number
- Opinions: take a position; acknowledge complexity or mixed feelings