| name | docs-style |
| description | Style gate for human-facing prose (README, docs/, guides, release notes). Use when writing or reviewing any human-facing documentation to strip LLM-writing tells and keep the voice plain, warm, and factual. Not needed for API reference generated from docstrings. |
Docs Style: human prose without the LLM tells
Agents write most of this repo's docs, so human-facing prose must be actively swept for the patterns readers now recognise as machine output. This skill is the curated shortlist (sources: Wikipedia's "Signs of AI writing" field guide, 2025-2026 detection roundups) plus the sweep procedure.
Knowledge
Voice for this repo
Warm, plain, confident. Short sentences over clever ones. State facts directly ("strand is a CLI" — never "serves as a CLI"). Concrete examples over abstract claims. It is fine to be enthusiastic about a genuinely good bit; it is not fine to inflate an ordinary bit.
Tell catalogue
Word tells — greppable, replace with a plain synonym or delete:
- delve, tapestry, landscape (abstract), interplay, intricate/intricacies
- pivotal, crucial, vital, testament, underscore(s/ing), boasts, showcase
- seamless(ly), robust, powerful, comprehensive, cutting-edge, game-changer
- leverage (as verb for "use"), empower, elevate, streamline, supercharge
- meticulous(ly), vibrant, enduring, fostering, garner, bolster
- "Additionally," / "Moreover," / "Furthermore," as sentence openers
Copula avoidance — "is/has" dressed up:
- "serves as", "stands as", "acts as", "represents" → "is"
- "boasts", "features", "offers", "maintains" → "has"
Structure tells:
- Contrast reframe: "It's not X, it's Y" / "not just X, but Y" / "It isn't about X; it's about Y"
- Rule-of-three padding: "fast, flexible, and powerful" triples where one precise word would do
- Em-dash overuse: more than one
— per paragraph is a flag; prefer a period or comma
- False-payoff hooks: "Here's the kicker", "The best part?", "But here's the thing"
- Unsolicited validation: "You're not alone", "You're not imagining it"
- Hedged authority: "Industry experts say", "Some argue", "Observers have noted"
- The "Challenges/Future Outlook" closing formula: "Despite its strengths, X faces challenges…"
Formatting tells:
- Bold-term-colon bullet walls (
- **Thing:** description) as the default paragraph substitute
- Bolding every key term on every occurrence
- Emoji as section markers or list bullets
- Title Case In Every Heading (this repo uses sentence case)
- Summary sections that restate the page ("In conclusion", "To sum up")
Content tells:
- Empty superlatives about significance ("a pivotal moment", "rich ecosystem")
- LLM-safe truths that say nothing ("good documentation is important")
- Neutral flatness where the text should take a stance, or hype where it should be neutral
- Generic claims replacing the specific, checkable fact that belongs there
Detection heuristic
No single tell proves anything — one em dash is fine. Flag prose when tells cluster: three or more distinct tell types in one section is a rewrite signal, not an edit signal.
Line length and prose that lives in code
The rule is two-sided. Markdown prose is not hard-wrapped: each paragraph or bullet is one source line, and the reader's IDE wraps it — that is what markdown editors are set up for. Older files in this repo are hard-wrapped; do not rewrap one in a drive-by edit, but write new markdown full-length and let a diff that already owns a file convert it.
Prose inside Clojure source is the opposite: hard-wrapped in the file so it reads without soft-wrap — 96 columns in skein.api.* modules (SPEC-003.C19a), matching the namespace elsewhere, and never past column 180 anywhere.
Prose that ships as data inside Clojure source (op payloads, about surfaces, rule descriptions) is still human-facing and gets this skill's sweep, but its authoring format is the |-margin block reflowed through skein.api.format.alpha — never one long string literal or (str ...) fragments. See docs/spools/writing-shared-spools.md for the block contract.
Procedures
- Grep the changed docs for the word tells and structure tells above (case-insensitive;
--/— count, "not just", "serves as", "isn't just").
- For each hit, rewrite in the repo voice: plain verb, concrete fact, shorter sentence. Delete the sentence if nothing factual remains.
- Read each section aloud-in-your-head for cadence: uniform sentence lengths and triple rhythms are rewrite signals even with zero grep hits.
- Check every remaining bold, bullet list, and heading earns its formatting: would prose read better?
- Confirm every factual claim survived the rewrite unchanged — style sweeps must never alter meaning.
Constraints
- Never trade accuracy for style: if a rewrite changes what the sentence claims, revert and rewrite again.
- Never mechanically strip a tell into worse prose; the goal is writing a human would produce, not zero grep hits.
- Do not apply this to generated API reference (
spools/*.api.md, docs/api/*.api.md — anything make api-docs writes); those mirror docstrings.
Validation
