Add humanizer-classics: book-grounded writing skill (v3 fork)#108
Open
bdevz wants to merge 6 commits intoblader:mainfrom
Open
Add humanizer-classics: book-grounded writing skill (v3 fork)#108bdevz wants to merge 6 commits intoblader:mainfrom
bdevz wants to merge 6 commits intoblader:mainfrom
Conversation
New sibling skill at humanizer-classics/ that refines AI-generated text using craft prescriptions from foundational writing books (Zinsser, Strunk & White, HBR Guide), in addition to the existing Wikipedia detection layer. The v2 humanizer at the repo root is unchanged so existing v2.5.1 users stay stable. Why a fork: v2 catalogs what AI writing looks like (29 detection patterns); v3 adds what good human writing does (16 craft rules, each sourced and citable). The architecture also moves from a single 559-line SKILL.md to a slim catalog + lazy-loaded references/ files, matching the SKILL.md + references/ convention used by other Claude Code skills. Includes: - 45 rules total (29 W-Wikipedia + 6 Z-Zinsser + 5 S-Strunk-White + 5 H-HBR), each with citation, pull-quote (10-25 words fair use), cross-references, context tags, before/after, and a how-to-apply mechanical move - context_tags system to resolve rule conflicts across forms (memo, email, blog, book-draft, technical-doc, dictation, meeting-notes) - Live Granola integration via mcp__granola__* tools (workflow doc at references/granola-meeting-transcripts.md, tools listed in SKILL.md frontmatter); Wispr Flow guidance covered in same file - 6 corpus samples with expected-fixes pairs covering marketing slop, business memo, dictation, meeting-notes, AI LinkedIn, book draft - CONTRIBUTING.md, CHANGELOG.md, MAINTAINERS.md, issue templates for the ongoing-repository contribution model
Mines four additional craft rules from The Elements of Style, 4th ed., each with verified pull-quote and section reference (II.x or V.x): - S-6: Express coordinate ideas in similar form (II.19) — parallel construction. Catches AI's tendency to vary form where parallel was needed. - S-7: Place the emphatic words of a sentence at the end (II.22) — the sentence-level analog of H-1; the news goes at the end, not buried mid-sentence with weak qualifiers tacked on. - S-8: Avoid a succession of loose sentences (II.18) — Strunk's name for the "every sentence is the same shape" failure mode that the Personality and Soul section calls out without prescribing a fix. - S-9: Do not affect a breezy manner (V.9) — the calibrating partner to Z-5 (be present on the page). Fires on the same contexts (blog, email, dictation) and prevents Z-5 from over-correcting into manufactured spontaneity. Pull-quotes were verified against the user-provided 4th edition PDF. Page citations dropped from the source line in favor of stable Roman numeral + rule number references (matching existing S-1..S-5 format). Updates total rule count from 45 to 49 across SKILL.md catalog table, README.md launch summary, _rule-index.md totals + cross-reference graph, and CHANGELOG.md.
…urce Mines three more craft rules from On Writing Well, each with verified pull-quote and chapter reference: - Z-7: A lead must capture the reader immediately or the article is dead (Ch. 9). Lead-side companion to Z-6 endings. Catches AI's habit of warming up for three paragraphs before saying anything; pairs with Z-6 since both come from the same chapter and Zinsser argues the lead and ending are the two highest-leverage sentences in any piece. - Z-8: Maintain unity of pronoun, tense, and mood (Ch. 8). Catches the pronoun drift, tense flips, and tone shifts that make AI-assembled long-form text read as if written by three different writers. - Z-9: Most adjectives and adverbs are unnecessary (Ch. 10 — Adverbs and Adjectives sections). Adds the positive prescription that pairs with W-4 (promotional language) detection: every modifier must do necessary work; "blared loudly" weakens "blared". While in the source PDF, also corrected several inaccurate citations in the existing Z-1..Z-6 rules: - Edition: was "30th anniversary ed., HarperCollins, 2006" — actual is "25th Anniversary Edition (6th ed.), HarperResource, 2001". Fixed throughout the file, README, and CHANGELOG. - Z-1: replaced the "Clutter is the disease of American writing" pull- quote, which does not appear in this edition, with the actual Ch. 3 closing exhortation that captures the same rule. - Z-2: "Don't dialogue with someone you can talk to" is actually from Ch. 3 (p. 16), not Ch. 4. Updated source line; quote unchanged. - Z-4: pull-quote was marked (paraphrased). Now have the exact wording from Ch. 10 (p. 71); paraphrase tag dropped. Source moved from Ch. 3 to Ch. 10 — the Little Qualifiers section, where it actually appears. - Z-5: "Sell yourself, and your subject will exert its own appeal" is the closing line of Ch. 4 (p. 24), not from Ch. 5 as cited. Fixed. - Z-6: pull-quote said "the reader"; book actually says "your readers". One-word fix. Updates total rule count from 49 to 52 across SKILL.md catalog, README launch summary, _rule-index totals + cross-reference graph, and CHANGELOG.
One more Zinsser rule from Ch. 5 "The Audience" (p. 25-30). Catches a
distinct AI failure mode that Z-5 and S-9 don't cover:
- Z-5 says: be present on the page (use "I", state opinions).
- S-9 warns: don't tip into manufactured spontaneity ("Hey folks!").
- Z-10 catches the third register: prose that is technically personal
yet calibrated to please an imagined gallery — trend-chasing openers
("In today's fast-paced landscape…"), preemptive audience-pleasing
("you'll love this!", "trust me"), LinkedIn humble-brag stance,
hedge-claims that exist to manage a phantom critical reader.
Pull-quote verified from the same 25th anniversary edition we cite
elsewhere. Context tags: blog, book-draft, email, dictation. Does NOT
fire on memo, technical-doc, or meeting-notes — those have a real
specific audience and audience-awareness is appropriate.
This is the natural stopping point for Zinsser mining. The remaining
unread chapters (Forms, Attitudes, the rest of Words/Usage) would
either duplicate existing rules or be too philosophical to fire on
text. Total now 53 rules across SKILL.md catalog, README, _rule-index,
and CHANGELOG.
Local sanity check uncovered one format inconsistency: H-2 had two
parallel Before sections ("wall of prose" and "carpet of bolded
bullets") instead of the single Before/After pair every other rule
follows. Consolidated to the bolded-bullets example (the more
H-2-specific failure) and moved the wall-of-prose discussion into the
Problem section, with a note that wall-of-prose is really an H-3 /
Z-1 issue.
Adds tests/validate.py — a structural validator contributors run
before opening PRs:
- SKILL.md frontmatter parses as YAML
- Every Read references/*.md directive points to a real file
- Rule IDs consistent across SKILL.md catalog, _rule-index.md, and
reference-file rule sections
- Every book rule has the required sections (Source, pull-quote,
Cross-references, Context tags, Detection cue, Problem, Before,
After, How to apply)
- Every corpus sample has its .expected-fixes.md pair and cites only
valid rule IDs
Exit 0 = pass. The validator does NOT check behavioral correctness
(rules actually firing on corpus samples) — that still requires
running /humanizer-classics in a Claude Code session against the
samples in tests/corpus/.
Updates REVIEWING.md to point at the validator (run it first, then
the manual eyeball check). Updates CONTRIBUTING.md so the validator
shows up in the new-rule and new-book contribution flows.
All 5 structural checks pass on the current 53-rule state.
The previous README install command pointed to a placeholder URL (humanizer-classics as its own repo, which doesn't exist yet — the skill currently lives as a subdirectory inside bdevz/humanizer). Replaced with the actual three-line clone-and-symlink that works today. Adds HOW-TO-USE.md as a plain-English guide aimed at non-technical teammates: a 30-second pitch, the three-line setup, four usage patterns (paste-in, voice match, Granola, Wispr), real before/after examples, and a small troubleshooting section. The README links to it from the Installation section.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
humanizer-classics/as a v3 sibling skill, grounded in foundational writing books (Zinsser, Strunk & White, HBR Guide) plus the existing Wikipedia detection layer. v2.5.1 at the repo root is untouched so existing users stay stable.SKILL.mdcatalog (~290 lines) + lazy-loadedreferences/*.md, matching theSKILL.md+references/convention used by other Claude Code skills.mcp__granola__list_meetings/get_meeting_transcript(workflow doc atreferences/granola-meeting-transcripts.md); Wispr Flow dictation guidance covered in the same file.tests/corpus/paired with*.expected-fixes.mdcovering marketing slop, business memo, dictation, meeting-notes, AI LinkedIn, and book draft. Manual reviewer checklist attests/REVIEWING.md.CONTRIBUTING.md,CHANGELOG.md,MAINTAINERS.md, plus issue templates (new-rule,new-book) for the ongoing-repository goal.Test plan
humanizer-classics/to~/.claude/skills/humanizer-classics/and confirm/humanizer-classicsloads in Claude Code (frontmatter parses, no brokenRead references/*.mddirectives).tests/corpus/01-marketing-slop.mdand confirm the rules listed in01-marketing-slop.expected-fixes.mdactually fire.mcp__granola__list_meetings→get_meeting_transcript→ two-pass humanize.~/.claude/skills/humanizer/(v2.5.1) still works alongside v3 with no conflict.~/.config/opencode/skills/humanizer-classics/and confirm same behavior.Open items (not blocking)
git subtree split --prefix=humanizer-classicsextracts the directory cleanly to its own repo. The plan was to keep it as a subdirectory until v3 has proven out.