humanizer-narrative-nonfiction
dsolares/humanizer-narrative-nonfiction
Claude Code skill: final-pass AI-pattern cleanup for long-form narrative nonfiction (popular science, essays, memoir, history, biography). 29-pattern catalog tuned to the genre — incl. semicolon density, the "rather than" reflex, and the temperament/uniformity tells. Three-tier system (hard/strong/light) prevents over-correction.
Instalação
npx convez-ai dsolares/humanizer-narrative-nonfiction1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
humanizer-narrative-nonfiction
A Claude Code skill that removes AI-pattern tells from long-form narrative nonfiction without flattening the register the genre is written in.
Designed for writers of popular science, literary essays, memoir, history, biography, and book-length argument who use AI as a drafting tool and want the output to read like a human wrote it — without forcing the prose into blog-voice register that doesn't fit book-length or scholarly work.
What it does
A multi-pass cleanup tool for AI-generated or AI-assisted drafts. Catches the 29 patterns that mark text as machine-written — negative parallelisms, em-dash overuse (and the opposite em-dash-sterile floor), semicolon-density overuse, the "rather than" comparative-reflex substitute, textual self-reference, the temperament tells (uniformity), copula avoidance, weasel attributions, participle padding, hedge openers, closing bows, importance inflation, tourism-board reflex, condensed expressions, causal-claim hedging, and more — while preserving the features of good long-form nonfiction prose: long argument-carrying sentences, qualified scientific claims, technical vocabulary, author-year citations, and em-dashes used at human frequency.
Why this exists
Most AI-humanizer tools were built for short-form blog or marketing copy. Applied to book prose or scholarly writing, they damage the register: stripping qualifiers (evidence suggests), enforcing first-person voice, banning em-dashes outright, breaking long argument-carrying sentences, and inserting blog-voice tics ("welcome small imperfections," "have opinions," "use fragments"). The result reads worse than the AI default.
This skill was designed from the ground up for long-form narrative nonfiction. It treats AI patterns as a tiered checklist:
- Hard rules fire always (negative parallelisms, chat-mode warmth, knowledge-cutoff disclaimers, "Bolded term:" bullets, engagement bait, decorative emojis, title-case headers, curly quotes).
- Strong tendencies fire with judgment (em-dash frequency cap, negation-density audit, copula avoidance, participle padding, importance inflation, hedge openers, closing bows, tourism-board reflex, frequency-capped transitions).
- Light preferences flag for the writer to decide (banned vocabulary —
intricate,nuanced,pivotal— which may be load-bearing in context).
This three-tier system is the safety valve. Naive AI-pattern removal scrubbed at full strength produces prose that's stiff and over-corrected, which is its own AI tell.
What's different from upstream humanizer tools
- Em-dashes are capped, not banned. Target ~4–6 per 1,000 words — the working range of skilled long-form science-narrative nonfiction. The AI tell is clustering (three-or-more to a paragraph), not the glyph itself.
- Negative parallelism rule is precise. Fires on two-sentence rhetorical inversion (
It's not X. It's Y.). Does NOT fire onNot only X, but also Yas a within-sentence coordinator — that is standard scholarly construction in long-form nonfiction, not an AI tell. - Rule-of-three fires on abstractions only. Concrete three-item lists (named entities, places, times, molecules) are protected. Skilled writers routinely use
X, Y, and Zfor concrete enumerations. - "From X to Y" fires only on empty rhetorical ranges. Literal geographic, temporal, numerical, and bounded-endpoint ranges are protected.
- Banned vocabulary is flagged, not silently replaced.
Intricatedescribing receptor binding,nuanceddescribing contested ethics — these often do real work. The skill surfaces them for the writer to judge. - A do-not-flag vocabulary list explicitly protects words that skilled long-form writers use comfortably and that naive humanizers strip:
remarkable,profound,fascinating,compelling,paradigm,vivid,sophisticated. These trigger on clustering (Pattern 17, Pattern 20), not on the individual word. Furthermore/Additionally/Moreoverare frequency-capped, not deleted. Long-form academic argument occasionally requires connectors. The cap (~1–2 per 1,000 words) catches the AI reflex while allowing load-bearing instances.- Author-year citations are protected. Anything inside parens containing a four-digit year is preserved verbatim, so the skill doesn't corrupt
(Smith 2020)or(Smith et al. 2024, 145)style references. - Negation density is audited beyond explicit shapes. Pattern 1 catches the rhetorical sentence-pair; Pattern 1b caps overall standalone-
notdensity at <3/1k for general prose and <5/1k for safety/contraindication writing. LLM-drafted prose typically lands at 3–4× the rate of skilled long-form science writers on first pass. - Semicolon density is audited and capped. Pattern 27 caps body-prose semicolons at ≤4/1k, converting independent-clause joiners (
The curve is real; it is not the experience.) to periods while leaving citation clusters and disambiguating series untouched. LLM-drafted prose routinely lands at 6–11/1k — the single largest stylistic anomaly that survives the other checks. - The "rather than" comparative reflex is caught. Pattern 28 catches the move where the contrastive X-not-Y reflex routes itself into "X rather than Y" to evade the negative-parallelism rule. The fix is the affirmative claim standing alone, not a cosmetic
X, not Ysubstitution. - Both directions of the em-dash miscalibration are caught. Beyond the overuse cap, the skill flags the floor breach — an em-dash-sterile chapter (below ~0.3/1k) reads stiff because a pruning-only pass never adds the glyph back. Re-introduction is flagged for an upstream pass, not done by subtraction.
- The temperament tells are surfaced. Pattern 29 targets the residual uniformity that survives lexical cleanup: the reused reconciliation template, the honesty-broker clause, and the on-schedule hedging symmetry are thinned here; scene-then-gloss, authorial absence, and one-temperature paragraph rhythm are flagged for an upstream revision pass.
- 15% paragraph-touch escalation. If the skill is rewriting more than ~15% of paragraphs in a draft, it halts and reports upstream voice drift rather than silently mass-rewriting. Cleanup at that volume signals the draft needs revision, not surface polish.
Calibration
The thresholds are tuned to the register of skilled long-form science-narrative nonfiction — the writing tradition exemplified by authors like Mike Jay, Carl Zimmer, Robert Sapolsky, and Lisa Feldman Barrett. Reading widely in the genre and noticing what skilled writers actually do is the calibration method. The principle: where a typical AI humanizer over-corrects against blog-voice norms, this skill calibrates to the register actually used in long-form scientific narrative — long argument-carrying sentences, em-dashes used liberally where they earn their pause, concrete enumerations as a default, qualified scientific claims, and Latin or domain vocabulary preserved.
See SKILL.md for the threshold table.
See docs/design-rationale.md for the full methodology critique, including which rules from upstream AI-pattern checklists were kept, softened, dropped, or extended, and why.
The 29-pattern catalog
| # | Pattern | Tier |
|---|---|---|
| 1 | Negative parallelisms (the highest-leverage AI tell) | Hard |
| 1b | Overall negation-density audit | Strong |
| 2 | Em-dash frequency cap | Strong |
| 3 | "Bolded term: description" bullet structure | Hard |
| 4 | Chat-mode warmth | Hard |
| 5 | Knowledge-cutoff disclaimers | Hard |
| 6 | Title case in headers | Hard |
| 7 | Curly quotes (draft pre-typesetting) | Hard |
| 8 | Decorative emojis | Hard |
| 9 | Copula avoidance (serves as → is) | Strong |
| 10 | Participle padding (-ing tails) | Strong |
| 11 | Weasel attributions (it has been described as) | Strong |
| 12 | Importance inflation (pivotal moment) | Strong |
| 13 | Hedge openers (In today's…) | Strong |
| 14 | Closing bows | Strong |
| 15 | Empty rhetorical ranges | Strong |
| 16 | Forced synonyms | Strong |
| 17 | Rule-of-three reflex | Strong |
| 18 | Meta-commentary | Strong |
| 19 | Metronome cadence | Strong |
| 20 | Tourism-board reflex | Strong |
| 21 | False balance | Strong |
| 22 | Condensed expressions (where/via/yield/beyond/linked to) | Strong |
| 23 | Causal-claim hedging (leads to/drives/impacts) | Strong |
| 24 | Generic positive conclusions | Strong |
| 25 | Excessive hedging (distinguished from appropriate qualification) | Strong |
| 26 | Classical-term restoration (clinical/scientific prose) | Light |
| 27 | Semicolon density (independent-clause joiners → periods) | Strong |
| 28 | "Rather than" as X-not-Y substitute | Strong |
| 29 | The temperament tells (uniformity, reconciliation template, honesty-broker clause) | Strong + escalation |
Full catalog with before/after examples: references/patterns-full.md. Two further audits live as Pass 2 sub-checks rather than numbered patterns: the em-dash floor breach (the sterile-prose counterpart to the Pattern 2 overuse cap) and the textual self-reference recast (prose narrating its own structure — the chapter argues…).
Example
Before:
The compound — first isolated in 1958 — was tested in cats, then dogs — and finally, after a decade, in human volunteers — most of whom were inpatients. It's not just about the pharmacology; it's about the cultural container in which the molecule moves. The study, marking a pivotal moment in the field, served as a turning point that highlighted the molecule's importance and underscored its therapeutic potential.
After:
The compound, first isolated in 1958, was tested in cats and then dogs. After a decade it reached human volunteers — most of them inpatients. The cultural container in which the molecule moves matters as much as the pharmacology. Within five years of the trial, three independent labs had replicated the result.
Changes: one em-dash kept where it does work (was five); negative parallelism deleted (It's not just X; it's Y); participle padding cut (marking a pivotal moment, highlighted its importance, underscored its therapeutic potential); copula restored (served as a turning point → recast as a specific claim about replication).
Install
git clone https://github.com/dsolares/humanizer-narrative-nonfiction.git ~/.claude/skills/humanizer-narrative-nonfiction
Restart your Claude Code session. Full install instructions in docs/installation.md.
Use
Once installed, invoke it implicitly by describing what you want:
- "Humanize this chapter draft and remove the AI tells."
- "Final-pass AI-pattern cleanup on
~/Drafts/chapter-04.md." - "Run the humanizer on the passage below."
Claude Code will load the skill and run the cleanup workflow.
Architecture
humanizer-narrative-nonfiction/
├── README.md ← this file
├── LICENSE ← MIT
├── CHANGELOG.md ← version history
├── SKILL.md ← the skill itself (loaded by Claude Code)
├── references/
│ └── patterns-full.md ← the 29-pattern catalog with before/after examples
└── docs/
├── design-rationale.md ← methodology critique and tier-system reasoning
└── installation.md ← install, update, uninstall
The skill uses Claude Code's progressive disclosure pattern: SKILL.md (loaded at activation, ~210 lines) describes the workflow at a high level and points at the reference files; patterns-full.md (loaded on demand) holds the full catalog with examples.
Extending it for your project
Some projects layer additional rules on top — strict citation formats, controlled vocabularies, in-house style sheets, chapter-class calibration (e.g., clinical-cluster vs narrative-cluster chapters in a long book series). The recommended pattern: wrap humanizer-narrative-nonfiction in an orchestrator skill that invokes it via the Skill tool, then handles project-specific concerns (folder layout, log destination, post-processing) in the wrapper. The base skill stays untouched.
See "Extending it for a project" in SKILL.md for the full recommendation.
Acknowledgments
This skill draws on patterns documented by Wikipedia's WikiProject AI Cleanup, structural analyses of LLM output from peer-reviewed research and community audits, and the broader community work on AI-prose detection. The three-tier system and the calibration for long-form academic register are original to this project.
License
MIT. See LICENSE.
Contributing
Issues and pull requests welcome. The pattern catalog is intentionally append-only — new patterns get the next number rather than being inserted into the existing numbering, so the modification log stays compatible with historical entries.
Methodology shifts (rule downgrades, new tier definitions, framing changes) should be documented in docs/design-rationale.md before being applied to SKILL.md and patterns-full.md.