Parcourir la source

Rewrite Humanizer in Plain Language (v2.11.0) (#223)

Rewrite the skill and all repo-authored guidance in Plain Language. Keep all 35 patterns, examples, commands, schemas, and package behavior.
Siqi Chen il y a 2 semaines
Parent
commit
43c97670b5
8 fichiers modifiés avec 318 ajouts et 271 suppressions
  1. 2 2
      .claude-plugin/marketplace.json
  2. 2 2
      .claude-plugin/plugin.json
  3. 5 5
      .github/workflows/validate.yml
  4. 39 20
      AGENTS.md
  5. 88 87
      README.md
  6. 140 133
      SKILL.md
  7. 2 2
      agents/openai.yaml
  8. 40 20
      scripts/validate-package.py

+ 2 - 2
.claude-plugin/marketplace.json

@@ -5,12 +5,12 @@
     "name": "blader",
     "url": "https://github.com/blader"
   },
-  "description": "The humanizer skill, installable as a Claude Code plugin.",
+  "description": "Install Humanizer as a Claude plugin.",
   "plugins": [
     {
       "name": "humanizer",
       "source": "./",
-      "description": "Remove signs of AI-generated writing from text, making it sound more natural and human. Based on Wikipedia's \"Signs of AI writing\" guide.",
+      "description": "Rewrite text that sounds AI-generated while keeping the writer's facts, meaning, and voice.",
       "license": "MIT",
       "keywords": ["writing", "editing", "ai-detection", "humanize", "prose", "style"]
     }

+ 2 - 2
.claude-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "humanizer",
-  "description": "Remove signs of AI-generated writing from text, making it sound more natural and human. Based on Wikipedia's \"Signs of AI writing\" guide.",
-  "version": "2.10.2",
+  "description": "Rewrite text that sounds AI-generated while keeping the writer's facts, meaning, and voice.",
+  "version": "2.11.0",
   "author": {
     "name": "blader",
     "url": "https://github.com/blader"

+ 5 - 5
.github/workflows/validate.yml

@@ -1,4 +1,4 @@
-name: Validate package
+name: Check package
 
 on:
   pull_request:
@@ -9,7 +9,7 @@ permissions:
   contents: read
 
 jobs:
-  validate:
+  check:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -19,11 +19,11 @@ jobs:
       - uses: actions/setup-python@v5
         with:
           python-version: "3.12"
-      - name: Validate synchronized package metadata
+      - name: Check package files
         run: python3 scripts/validate-package.py
-      - name: Verify Agent Skills discovery
+      - name: Check skill discovery
         run: npx --yes skills@1.5.20 add . --list
-      - name: Validate Claude Code marketplace
+      - name: Check Claude marketplace
         run: |
           npm install --global @anthropic-ai/claude-code
           claude plugin validate .

+ 39 - 20
AGENTS.md

@@ -1,31 +1,50 @@
-# AGENTS.md
+# Guide for agents
 
-Guidance for AI coding agents (Claude Code, Codex, Warp, etc.) working in this repository.
+This file explains how to change Humanizer without breaking its package or prompt.
 
-## What this repo is
+## What this repo contains
 
-A portable agent skill implemented entirely as Markdown. The runtime artifact is `SKILL.md`: the agent reads its YAML frontmatter and editor prompt. There is no build step, and the repo should avoid wording that limits support to one or two harnesses.
+Humanizer is an agent skill written in Markdown. `SKILL.md` is the prompt that agents read. The repo has no build step.
+
+Keep the skill portable. Do not write instructions that limit it to one or two agent tools.
 
 ## Key files
 
-- `SKILL.md` — the skill itself. Portable YAML frontmatter (`name`, `description`, `license`, `metadata.version`) followed by the canonical, numbered pattern list with before/after examples. **This is the source of truth.**
-- `skills/humanizer/SKILL.md` — relative link to the canonical root skill for Claude Desktop and older plugin loaders. Never replace it with a second copy or edit it as a separate authority.
-- `README.md` — for humans: installation, usage, a summary table of the patterns, and a version history.
-- `.claude-plugin/plugin.json` — optional Claude Code plugin manifest.
-- `.claude-plugin/marketplace.json` — optional single-repo marketplace entry so `/plugin marketplace add blader/humanizer` works.
-- `scripts/validate-package.py` — dependency-free package and synchronization checks used locally and in CI.
+- `SKILL.md` is the source of truth. It contains portable YAML metadata, 35 numbered patterns, and their examples.
+- `skills/humanizer/SKILL.md` links to the root skill for Claude Desktop and older plugin loaders. Do not replace the link with a copy or edit it as a separate file.
+- `README.md` explains installation, use, patterns, and version history.
+- `.claude-plugin/plugin.json` describes the Claude plugin.
+- `.claude-plugin/marketplace.json` lets users add this repo as a Claude marketplace.
+- `scripts/validate-package.py` checks package files and shared values.
+
+## Rules for changes
+
+Keep `SKILL.md` and `README.md` in sync.
+
+- **Patterns:** The skill has 35 numbered patterns. If you add, remove, or renumber a pattern, update the README table, heading, validator, and every pattern reference.
+- **Version:** Keep the same version in `SKILL.md` under `metadata.version`, the first README version entry, and `.claude-plugin/plugin.json`. Do not add a top-level `version` field to the skill.
+- **Compatibility:** Keep install and use instructions neutral across agents. Names such as Claude Code, OpenCode, and Codex are examples, not limits.
+- **History:** Add a short README version note for any behavior change or non-obvious fix.
+- **Checks:** Before publishing, run `python3 scripts/validate-package.py`, `npx skills add . --list`, and `claude plugin validate .`.
 
-## The maintenance contract
+## Writing style
 
-`SKILL.md` and `README.md` must stay in sync. When you change behavior or content:
+Use Plain Language in code comments, prompts, documentation, descriptions, validation messages, and progress reports.
 
-- **Patterns:** the skill currently defines **35 numbered patterns**. If you add, remove, or renumber any, update the README pattern table, its "N Patterns Detected" heading, and every cross-reference in the same change. Keep numbering stable unless you are deliberately renumbering.
-- **Version:** `SKILL.md` frontmatter stores the version under `metadata.version`, `README.md` has a "Version History" section, and `.claude-plugin/plugin.json` has a `version` field. Bump them together so package metadata matches the skill. Keep the skill version under `metadata`; a top-level `version` key is not portable across Agent Skills hosts. (`marketplace.json` intentionally omits a version so `plugin.json` stays the package source of truth.)
-- **Compatibility:** keep install and usage language harness-neutral. The skill should work in any agent harness that can load Markdown skill instructions; Claude Code, OpenCode, Codex, and other harnesses are examples, not limits.
-- **Validation:** run `python3 scripts/validate-package.py`, `npx skills add . --list`, and `claude plugin validate .` before publishing.
-- **Non-obvious fixes:** if you change the prompt to handle a tricky failure mode (a repeated mis-edit, an unexpected tone shift), add a short note to the README version history explaining what was fixed and why.
+- Lead with the main point.
+- Use common words and active voice.
+- Keep sentences and paragraphs short.
+- Use one term for the same item.
+- Use `must` for requirements.
+- Use headings, lists, and tables when they help the reader.
+- Remove repeated or unnecessary words.
+- Limit acronyms and explain technical terms.
+- Avoid double negatives.
+- Keep exact identifiers, commands, paths, schema fields, quotations, watched phrases, and behavior-bearing examples.
+- Keep the full technical meaning.
 
-## Editing SKILL.md
+## Editing the skill
 
-- Preserve valid YAML frontmatter (formatting and indentation).
-- The prompt below the frontmatter is the product. Edit it like a careful instruction document, not code.
+- Keep the YAML metadata valid.
+- Treat the prompt below the metadata as the product.
+- Prefer a short, clear instruction over another exception or repeated explanation.

+ 88 - 87
README.md

@@ -2,13 +2,13 @@
 
 [![skills.sh installs](https://skills.sh/b/blader/humanizer)](https://skills.sh/blader/humanizer)
 
-A portable agent skill that removes signs of AI-generated writing from text, making it sound more natural and human. It is plain Markdown, so it can run in any harness that supports skill-style instructions.
+Humanizer rewrites text that sounds AI-generated while keeping the writer's facts, meaning, and voice. The skill is plain Markdown and works in any agent that supports skills.
 
 ## Installation
 
 ### Skills CLI
 
-Install globally with the cross-agent skills CLI so Humanizer is available in every project:
+Install Humanizer for all projects:
 
 ```bash
 npx skills add blader/humanizer --global
@@ -20,19 +20,19 @@ Update an existing install:
 npx skills update humanizer --global
 ```
 
-To install globally into every supported agent harness:
+Install it for every supported agent:
 
 ```bash
 npx skills add blader/humanizer --global --agent '*'
 ```
 
-To target one configured harness, pass its agent name:
+Install it for one agent:
 
 ```bash
 npx skills add blader/humanizer --global --agent <agent-name>
 ```
 
-Omit `--global` for a project-local install that can be committed and shared with collaborators. Start a new agent session or reload skills after installation.
+Omit `--global` to install it in the current project. Start a new agent session or reload skills after installation.
 
 ### Claude Code plugin
 
@@ -43,13 +43,13 @@ Claude Code users can also install Humanizer as a plugin:
 /plugin install humanizer@humanizer
 ```
 
-The skill is then invoked as `/humanizer:humanizer`.
+Run the installed skill with `/humanizer:humanizer`.
 
-The plugin also exposes the canonical root `SKILL.md` through `skills/humanizer/SKILL.md`. That internal link supports Claude Desktop and older plugin loaders without maintaining a second copy of the prompt.
+The plugin links `skills/humanizer/SKILL.md` to the root `SKILL.md`. This lets Claude Desktop and older plugin loaders find the skill without creating a second prompt.
 
 ### Manual
 
-Any agent harness can use the skill directly because the runtime artifact is `SKILL.md`. Install it wherever your harness expects skill directories, or copy `SKILL.md` into an existing skill folder.
+You can also place `SKILL.md` in any agent's skill folder.
 
 For example:
 
@@ -66,7 +66,7 @@ cp SKILL.md /path/to/your/skills/humanizer/
 
 ## Usage
 
-Invoke the skill however your agent harness exposes installed skills. Common forms include a slash command or a direct request:
+Use a slash command or ask the agent directly:
 
 ```
 /humanizer
@@ -78,15 +78,15 @@ Invoke the skill however your agent harness exposes installed skills. Common for
 Please humanize this text: [your text]
 ```
 
-Point it at a file and the skill rewrites it in place:
+You can also ask Humanizer to rewrite a file:
 
 ```
 Humanize the prose in docs/launch-post.md
 ```
 
-### Voice Calibration
+### Match your voice
 
-To match your personal writing style, provide a sample of your own writing:
+Provide a writing sample when you want Humanizer to match your style:
 
 ```
 /humanizer
@@ -98,85 +98,85 @@ Now humanize this text:
 [paste AI text to humanize]
 ```
 
-The skill will analyze your sentence rhythm, word choices, and quirks, then apply them to the rewrite instead of producing generic "clean" output.
+Humanizer matches the sample's rhythm, word choice, punctuation, and deliberate quirks.
 
-## Overview
+## How it works
 
-Based on [Wikipedia's "Signs of AI writing"](https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing) guide, maintained by WikiProject AI Cleanup. This comprehensive guide comes from observations of thousands of instances of AI-generated text.
+Humanizer uses patterns from Wikipedia's ["Signs of AI writing"](https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing), maintained by WikiProject AI Cleanup.
 
-The skill also includes a final "obviously AI generated" audit pass and a second rewrite, to catch lingering AI-isms in the first draft.
+It drafts a rewrite, checks the draft for remaining AI patterns and changed claims, then writes the final version.
 
-Rewrites follow a no-fabrication rule: they never add facts, names, dates, or citations that aren't in the source text. Specificity has to come from the source or the author, not from the rewrite.
+It does not invent facts, names, dates, quotes, or citations. Any added detail must come from the source or the writer.
 
-### Key Insight from Wikipedia
+### Wikipedia's main point
 
 > "LLMs use statistical algorithms to guess what should come next. The result tends toward the most statistically likely result that applies to the widest variety of cases."
 
-## 35 Patterns Detected (with Before/After Examples)
+## 35 patterns with examples
 
-### Content Patterns
+### Content patterns
 
 | # | Pattern | Before | After |
 |---|---------|--------|-------|
-| 1 | **Significance inflation** | "marking a pivotal moment in the evolution of..." | "was established in 1989 as part of a wider decentralization" |
-| 2 | **Notability name-dropping** | "cited in NYT, BBC, FT, and The Hindu" | Trim the list; keep only sourced context |
-| 3 | **Superficial -ing analyses** | "symbolizing... reflecting... showcasing..." | Remove, or keep only what the source supports |
-| 4 | **Promotional language** | "nestled within the breathtaking region" | "is a town in the Gonder region" |
-| 5 | **Vague attributions** | "Experts believe it plays a crucial role" | Name a real source or cut the claim |
-| 6 | **Formulaic challenges** | "Despite challenges... continues to thrive" | Keep the sourced facts; cut the boosterism |
+| 1 | **Inflated importance and legacy** | "marking a pivotal moment in the evolution of..." | "was established in 1989 as part of a wider decentralization" |
+| 2 | **Name-dropping to prove importance** | "cited in NYT, BBC, FT, and The Hindu" | Keep only useful, sourced context |
+| 3 | **Shallow -ing analysis** | "symbolizing... reflecting... showcasing..." | Keep only what the source supports |
+| 4 | **Sales language** | "nestled within the breathtaking region" | "is a town in the Gonder region" |
+| 5 | **Vague sources** | "Experts believe it plays a crucial role" | Name a real source or remove the claim |
+| 6 | **Formulaic challenges and outlook** | "Despite challenges... continues to thrive" | Keep the facts and remove the sales pitch |
 
-### Language Patterns
+### Language and grammar patterns
 
 | # | Pattern | Before | After |
 |---|---------|--------|-------|
-| 7 | **AI vocabulary** | "Actually... additionally... gated on... quietly... testament... landscape... showcasing" | "also... needs... remain common" |
-| 8 | **Copula avoidance** | "serves as... features... boasts" | "is... has" |
-| 9 | **Negative parallelisms / tailing negations** | "It's not just X, it's Y", "..., no guessing" | State the point directly |
-| 10 | **Rule of three** | "innovation, inspiration, and insights" | Use natural number of items |
-| 11 | **Synonym cycling / repeated openings** | "protagonist... main character... hero" or "She noted... She noted... She filed..." | Settle on one referent; merge the repeated run |
-| 12 | **False ranges** | "from the Big Bang to dark matter" | List topics directly |
-| 13 | **Passive voice / subjectless fragments** | "No configuration file needed" | Name the actor when it helps clarity |
+| 7 | **Overused AI words** | "Actually... additionally... gated on... quietly... testament... landscape... showcasing" | "also... needs... remain common" |
+| 8 | **Avoiding is and are** | "serves as... features... boasts" | "is... has" |
+| 9 | **Not X but Y and clipped endings** | "It's not just X, it's Y", "..., no guessing" | State the point directly |
+| 10 | **Forced groups of three** | "innovation, inspiration, and insights" | Use the number of items the meaning needs |
+| 11 | **Changing names and repeated openings** | "protagonist... main character... hero" or "She noted... She noted... She filed..." | Use one name or merge the repeated sentences |
+| 12 | **False from X to Y ranges** | "from the Big Bang to dark matter" | List the topics directly |
+| 13 | **Passive voice and missing subjects** | "No configuration file needed" | Name the actor when that helps |
 
-### Style Patterns
+### Style patterns
 
 | # | Pattern | Before | After |
 |---|---------|--------|-------|
 | 14 | **Em/en dashes** | "institutions—not the people—yet this continues—" | Cut them: periods, commas, colons, or parentheses |
-| 15 | **Boldface overuse** | "**OKRs**, **KPIs**, **BMC**" | "OKRs, KPIs, BMC" |
-| 16 | **Inline-header lists** | "**Performance:** Performance improved" | Convert to prose |
-| 17 | **Title Case Headings** | "Strategic Negotiations And Partnerships" | "Strategic negotiations and partnerships" |
+| 15 | **Too much bold text** | "**OKRs**, **KPIs**, **BMC**" | "OKRs, KPIs, BMC" |
+| 16 | **Lists with bold mini-headings** | "**Performance:** Performance improved" | Use prose when a list adds no value |
+| 17 | **Title case in headings** | "Strategic Negotiations And Partnerships" | "Strategic negotiations and partnerships" |
 | 18 | **Emojis** | "🚀 Launch Phase: 💡 Key Insight:" | Remove emojis |
 | 19 | **Curly quotes** | `said “the project”` | `said "the project"` |
-| 26 | **Hyphenated word pairs** | “cross-functional, data-driven, client-facing” | Drop hyphens on common word pairs |
-| 27 | **Persuasive authority tropes** | "At its core, what matters is..." | State the point directly |
-| 28 | **Signposting announcements** | "Let's dive in", or casual "one thing that bit me, heads up on X" | Start with the content, drop the announcement entirely |
-| 29 | **Fragmented headers** | "## Performance" + "Speed matters." | Let the heading do the work |
-| 30 | **Diff-anchored writing** | "This function was added to replace..." | Describe what it does, not what changed |
-| 31 | **Manufactured punchlines / staccato drama** | "It had no preference. No prior. No nostalgia." | Use varied sentence lengths and concrete claims |
-| 32 | **Aphorism formulas** | "Symmetry is the language of trust" | Replace the formula with the actual claim |
-| 33 | **Conversational rhetorical openers** | "Honestly? It depends..." | Remove the fake-candid setup |
-| 34 | **Shadowboxing** | "This isn't mainly about prompt length..." | Cut the unraised objection; restate any claim it concedes |
-| 35 | **Editorial scar tissue** | "A tempting option would be to..., but" | Cut the phantom alternative; keep options a reader would actually weigh |
-
-### Communication Patterns
+| 26 | **Too many hyphenated word pairs** | “cross-functional, data-driven, client-facing” | Keep only the hyphens grammar needs |
+| 27 | **A fake deeper truth** | "At its core, what matters is..." | State the point directly |
+| 28 | **Announcing the next point** | "Let's dive in", or "one thing that bit me" | Start with the content |
+| 29 | **A heading repeated below itself** | "## Performance" + "Speed matters." | Let the heading do the work |
+| 30 | **Writing about the old version** | "This function was added to replace..." | Describe what it does now |
+| 31 | **Forced punchlines and fragments** | "It had no preference. No prior. No nostalgia." | Use natural sentence lengths and specific claims |
+| 32 | **Formulaic sayings** | "Symmetry is the language of trust" | State the specific claim |
+| 33 | **Fake-candid openings** | "Honestly? It depends..." | State the answer directly |
+| 34 | **Answering objections no one raised** | "This isn't mainly about prompt length..." | Remove the unsupported defense and keep any real claim |
+| 35 | **Rejecting fake alternatives** | "A tempting option would be to..., but" | Remove the fake option and keep real choices |
+
+### Chatbot patterns
 
 | # | Pattern | Before | After |
 |---|---------|--------|-------|
-| 20 | **Chatbot artifacts** | "I hope this helps! Let me know if..." | Remove entirely |
-| 21 | **Cutoff disclaimers** | "While details are limited in available sources..." | Find sources or remove |
-| 22 | **Sycophantic tone** | "Great question! You're absolutely right!" | Respond directly |
+| 20 | **Chatbot text left in the answer** | "I hope this helps! Let me know if..." | Remove it |
+| 21 | **Knowledge-limit disclaimers and guesses** | "While details are limited in available sources..." | State what is known or remove the claim |
+| 22 | **Overly agreeable tone** | "Great question! You're absolutely right!" | Answer directly |
 
-### Filler and Hedging
+### Filler and hedging
 
 | # | Pattern | Before | After |
 |---|---------|--------|-------|
 | 23 | **Filler phrases** | "In order to", "Due to the fact that" | "To", "Because" |
-| 24 | **Excessive hedging** | "could potentially possibly" | "may" |
-| 25 | **Generic conclusions** | "The future looks bright" | Specific plans or facts |
+| 24 | **Too many qualifiers** | "could potentially possibly" | "may" |
+| 25 | **Generic positive endings** | "The future looks bright" | End with a fact or a sourced plan |
 
-## Full Example
+## Full example
 
-*(Illustration note: the rewrite below adds specifics, like the month and the neighborhoods, that stand in for details the author would supply. In a real session those come from the user; the skill asks rather than invents.)*
+*The example includes details that a real writer would provide, such as the month and neighborhood. Humanizer must ask for missing details instead of inventing them.*
 
 **Before (AI-sounding):**
 > I recently spent five unforgettable days in Lisbon, and let me tell you — this city completely stole my heart. From the moment I arrived, I knew I was somewhere truly special.
@@ -191,7 +191,7 @@ Rewrites follow a no-fabrication rule: they never add facts, names, dates, or ci
 >
 > Would I go back? Absolutely. Lisbon isn't just a place to visit — it's a place to fall in love with, again and again. If you're dreaming of your next getaway, this is one destination that promises memories to last a lifetime. ✨
 
-**After (Humanized):**
+**After:**
 > I spent five days in Lisbon last October and still have mixed feelings about it. Beautiful, yes. Also harder on the knees than anyone warned me.
 >
 > The hills are the whole story and somehow never make the brochures. My hotel was up in Alfama, which photographs beautifully and translates, in practice, to climbing what felt like a six-story staircase every time I wanted coffee. By the second day my calves had opinions. I started planning each walk around which way was downhill, which is a strange way to see a city but probably an honest one.
@@ -204,34 +204,35 @@ Rewrites follow a no-fabrication rule: they never add facts, names, dates, or ci
 >
 > I would go back, but in spring and with better shoes. Lisbon does not bend over backward to make things easy for you. I think I liked that, even when my legs disagreed.
 
-## References
-
-- [Wikipedia: Signs of AI writing](https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing) - Primary source
-- [WikiProject AI Cleanup](https://en.wikipedia.org/wiki/Wikipedia:WikiProject_AI_Cleanup) - Maintaining organization
-
-## Version History
-
-- **2.10.2** - Exposed the canonical root `SKILL.md` through the standard `skills/humanizer/` plugin layout so Claude Desktop and pre-2.1.142 loaders discover it without a duplicated prompt copy (fixes #202). No change to the 35 patterns.
-- **2.10.1** - Added `gate` / `gated` / `gating` to §7 when used figuratively as the default metaphor for ordinary prerequisites, while preserving established technical uses such as feature gating and CI quality gates. No change to the 35 patterns.
-- **2.10.0** - Added patterns #34 (shadowboxing) and #35 (editorial scar tissue) for drafting-conversation residue: unattributed meta-level negations answering objections nobody raised, and phantom "tempting alternative" rebuttals recycled from the model's own corrected mistakes. Both come with false-positive guards protecting real disclaimers, scoping statements, engaged objections, and alternatives a reader would actually weigh (fixes #198). Also expanded #24 to catch accumulated fairness clauses from iterative editing, and changed the revision step to rewrite from the point rather than patch flagged phrases, since patches are how scar tissue forms. 35 patterns total.
-- **2.9.2** - Extended pattern #11 to cover repeated sentence openings, with a deliberate-anaphora guard (fixes #206). Broadened §28 so casual rewordings of signposting are still treated as announcements rather than fixes. No change to the 33 patterns.
-- **2.9.1** - Improved distribution and portability: removed nonportable frontmatter and tool preapprovals, made global installation the documented default, added package validation, and removed the duplicated long-form example from the runtime prompt. No change to the 33 patterns.
-- **2.9.0** - Added a no-fabrication rule: rewrites may not invent facts, names, dates, or citations not present in the source, and every example that modeled invented specifics was re-cut to use only source information (fixes #187). Replaced paragraph-count parity with an information-over-shape rule, made a user's voice sample outrank the em dash ban, and added invocation modes (pasted text / file / embedded). No change to the 33 patterns.
-- **2.8.3** - Moved the skill version from the unsupported top-level frontmatter key to `metadata.version` for Agent Skills and Claude compatibility. No change to the 33 patterns.
-- **2.8.2** - Replaced the full before/after example with a first-person Lisbon trip recap. The after now keeps the same topic, perspective, and rough length as the before while removing the AI tells without becoming clipped or slogan-like. No change to the 33 patterns.
-- **2.8.1** - Added cross-agent installation docs, optional Claude Code plugin packaging, and a compact secondhand-text false-positive guard. No change to the 33 patterns.
-- **2.8.0** - Added style/cadence patterns #31-33 for manufactured punchlines, aphorism formulas, and conversational rhetorical openers; expanded #20 to catch offer-to-continue chatbot closers. 33 patterns total.
-- **2.7.0** - Added pattern #30 (diff-anchored writing); made em/en dashes a hard cut rather than "overuse"; expanded #21 to cover speculative gap-filling ("maintains a low profile"). 30 patterns total.
-- **2.6.0** - Cleanup pass: consolidated the duplicated workflow sections, gated the personality guidance to content where voice is wanted, removed the model-fingerprinting subsection, and condensed the worked example. No change to the 29 patterns.
-- **2.5.1** - Added a passive-voice / subjectless-fragment rule, raising the total to 29 patterns
-- **2.5.0** - Added patterns for persuasive framing, signposting, and fragmented headers; expanded negative parallelisms to cover tailing negations; tightened wording around em dash overuse; fixed frontmatter wording to use "filler phrases"
-- **2.4.0** - Added voice calibration: match the user's personal writing style from samples
-- **2.3.0** - Added pattern #25: hyphenated word pair overuse
-- **2.2.0** - Added a final "obviously AI generated" audit + second-pass rewrite prompts
-- **2.1.1** - Fixed pattern #18 example (curly quotes vs straight quotes)
-- **2.1.0** - Added before/after examples for all 24 patterns
-- **2.0.0** - Complete rewrite based on raw Wikipedia article content
-- **1.0.0** - Initial release
+## Sources
+
+- [Wikipedia: Signs of AI writing](https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing) - Main source
+- [WikiProject AI Cleanup](https://en.wikipedia.org/wiki/Wikipedia:WikiProject_AI_Cleanup) - Maintains the source page
+
+## Version history
+
+- **2.11.0** - Rewrote all repo guidance, descriptions, checks, and skill instructions in Plain Language. Kept all 35 patterns and their behavior.
+- **2.10.2** - Added the standard `skills/humanizer/` plugin path for Claude Desktop and older loaders. The path links to the root skill, so there is still one prompt (fixes #202).
+- **2.10.1** - Added figurative uses of `gate`, `gated`, and `gating` to §7. Kept real technical uses, such as feature gating and CI quality gates.
+- **2.10.0** - Added patterns #34 and #35 for old drafting ideas left in final text. Added safeguards for real limits, objections, and alternatives (fixes #198). Also improved §24 and the final rewrite step. 35 patterns total.
+- **2.9.2** - Added repeated sentence openings to pattern #11, with a safeguard for deliberate repetition (fixes #206). Expanded §28 to cover casual announcements. 33 patterns total.
+- **2.9.1** - Improved installation and package checks. Removed unsupported metadata, tool approvals, and a repeated long example. 33 patterns total.
+- **2.9.0** - Added the rule against invented facts and updated every example to follow it (fixes #187). Made information more important than paragraph shape, let writing samples override §14, and added three output modes. 33 patterns total.
+- **2.8.3** - Moved the version to `metadata.version` for Agent Skills compatibility. 33 patterns total.
+- **2.8.2** - Replaced the main example with a first-person Lisbon story that keeps the original topic, view, and detail. 33 patterns total.
+- **2.8.1** - Added cross-agent installation, Claude plugin files, and a safeguard for quoted text. 33 patterns total.
+- **2.8.0** - Added patterns #31-33 and expanded pattern #20 to catch chatbot offers. 33 patterns total.
+- **2.7.0** - Added pattern #30, strengthened the dash rule, and expanded pattern #21 to cover unsupported guesses. 30 patterns total.
+- **2.6.0** - Combined repeated workflow text, limited personality guidance to the right content, removed model guesses, and shortened the main example. 29 patterns total.
+- **2.5.1** - Added passive voice and missing subjects. 29 patterns total.
+- **2.5.0** - Added deeper-truth claims, announcements, repeated headings, and clipped negative endings. Tightened the dash rule and corrected the frontmatter. 28 patterns total.
+- **2.4.0** - Added writing-sample matching.
+- **2.3.0** - Added hyphenated word pairs.
+- **2.2.0** - Added a draft check and second rewrite.
+- **2.1.1** - Corrected the curly-quote example.
+- **2.1.0** - Added before/after examples for all 24 patterns.
+- **2.0.0** - Rewrote the skill from the Wikipedia source.
+- **1.0.0** - First release.
 
 ## License
 

+ 140 - 133
SKILL.md

@@ -1,134 +1,136 @@
 ---
 name: humanizer
 description: |
-  Remove signs of AI-generated writing from text. Use when editing or reviewing
-  text to make it sound more natural and human-written. Based on Wikipedia's
-  comprehensive "Signs of AI writing" guide. Detects and fixes patterns including:
-  inflated symbolism, promotional language, superficial -ing analyses, vague
-  attributions, em dash overuse, rule of three, AI vocabulary words, passive
-  voice, negative parallelisms, and filler phrases.
+  Rewrite text that sounds AI-generated while keeping the writer's facts,
+  meaning, and voice. Use when editing or reviewing prose for inflated claims,
+  sales language, vague sources, repetitive structure, stock AI words, passive
+  voice, filler, or chatbot artifacts. Based on Wikipedia's "Signs of AI writing."
 license: MIT
 metadata:
-  version: "2.10.2"
+  version: "2.11.0"
 ---
 
-# Humanizer: Remove AI Writing Patterns
+# Humanizer: remove AI writing patterns
 
-You are a writing editor that identifies and removes signs of AI-generated text to make writing sound more natural and human. This guide is based on Wikipedia's "Signs of AI writing" page, maintained by WikiProject AI Cleanup.
+Rewrite text that sounds AI-generated so it reads like the writer, not a chatbot. Keep the writer's facts, meaning, and voice.
 
-## Your Task
+The patterns below come from Wikipedia's ["Signs of AI writing"](https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing), maintained by WikiProject AI Cleanup.
+
+## What to do
 
 When given text to humanize:
 
-1. **Identify AI patterns** - Scan for the patterns listed below.
-2. **Preserve the information, not the shape** - Every claim in the original survives into the rewrite, but depth doesn't have to be uniform: compress the dull parts, dwell where a human would, and merge or split paragraphs freely. When keeping the information and mirroring the original's structure pull in different directions, the information wins.
-3. **Never invent facts** - The rewrite must not contain any fact, name, number, date, quote, or citation that isn't in the source text. Swapping a vague claim for a specific one is allowed only when the specific comes from the source or from the user; if a sentence needs real-world detail to work, ask for it or write the plain version without it. Opinions and reactions are voice, not facts: where PERSONALITY AND SOUL applies you may add stance, but never new factual claims. (In fiction, invented detail is the job. This rule governs everything else.)
-4. **Match the voice** - Fit the intended tone (formal, casual, technical). Add personality only when the content and the author's voice call for it (see PERSONALITY AND SOUL).
+1. **Find AI patterns.** Check the text against the patterns below.
+2. **Keep every claim.** You may shorten dull parts, expand useful parts, and merge or split paragraphs. Keep the information even when you change the structure.
+3. **Do not invent facts.** Do not add a fact, name, number, date, quote, or citation unless it comes from the source or the user. If a sentence needs a missing detail, ask for it or use a simpler sentence. You may add an opinion or reaction when the writer's voice calls for one, but you may not add a factual claim. Fiction is exempt because invented details are part of the task.
+4. **Match the voice.** Use the right tone for the text, such as formal, casual, or technical. Add personality only when the text and the writer call for it.
 
-How you're invoked changes what you deliver (see Invocation Modes). The draft → audit → final loop itself is defined under Process and Output, below.
+The input type controls what you return. See [How to return the result](#how-to-return-the-result). Use the same rewrite process in every mode.
 
-## Voice Calibration
+## Match the writer's voice
 
 If the user provides a writing sample (their own previous writing), analyze it before rewriting:
 
-1. Read the sample first. Note its sentence lengths, vocabulary, paragraph openings, punctuation, recurring phrases, and transitions.
-2. Match those habits instead of merely deleting AI patterns. Do not upgrade casual words or regularize deliberate quirks.
-3. Without a sample, use the default behavior below.
+1. Read the sample first. Note its sentence length, word choice, paragraph openings, punctuation, repeated phrases, and transitions.
+2. Match those habits. Do not replace casual words with formal ones or remove deliberate quirks.
+3. If there is no sample, use the guidance below.
 
-A sample outranks this skill's style rules, including the em dash rule in §14: if the sample uses em dashes, keep them at roughly the sample's frequency. Matching the author beats scrubbing the tell.
+A writing sample takes priority over these style rules. If the sample uses em dashes, keep them at about the same rate. Do not apply §14 as a ban.
 
-## PERSONALITY AND SOUL
+## Add personality only when it fits
 
-Avoiding AI patterns is only half the job. Sterile, voiceless writing is just as obvious as slop. Good writing has a human behind it.
+Removing AI patterns is only half the job. The result should still sound like a person.
 
-**Apply this section only when the content and the author's voice call for it** - blog posts, essays, opinion, personal writing. For encyclopedic, technical, legal, or reference text, neutral and plain *is* the correct human voice; don't inject opinions or first person there.
+Use personality in blog posts, essays, opinions, and personal writing when it fits the writer. Keep reference, technical, legal, and factual text neutral. Do not add opinions or first-person language where they do not belong.
 
-When voice is appropriate, avoid uniform sentence structures, bloodless neutrality, and perfect organization. Let the writer have opinions, uncertainty, mixed feelings, humor, asides, and uneven rhythm. Never add factual claims to create that personality.
+When personality fits, keep the writer's opinions, uncertainty, mixed feelings, humor, asides, and uneven rhythm. Never invent facts to make the text feel personal.
 
-## CONTENT PATTERNS
+## Content patterns
 
-### 1. Undue Emphasis on Significance, Legacy, and Broader Trends
+### 1. Inflated claims about importance and legacy
 
 **Words to watch:** stands/serves as, is a testament/reminder, a vital/significant/crucial/pivotal/key role/moment, underscores/highlights its importance/significance, reflects broader, symbolizing its ongoing/enduring/lasting, contributing to the, setting the stage for, marking/shaping the, represents/marks a shift, key turning point, evolving landscape, focal point, indelible mark, deeply rooted
-**Problem:** LLM writing puffs up importance by adding statements about how arbitrary aspects represent or contribute to a broader topic.
+**Problem:** AI writing often claims that ordinary details mark a major change, prove a legacy, or reflect a broad trend.
 **Before:**
 > The Statistical Institute of Catalonia was officially established in 1989, marking a pivotal moment in the evolution of regional statistics in Spain. This initiative was part of a broader movement across Spain to decentralize administrative functions and enhance regional governance.
 **After:**
 > The Statistical Institute of Catalonia was established in 1989, part of a wider decentralization of administrative functions in Spain.
 
-### 2. Undue Emphasis on Notability and Media Coverage
+### 2. Name-dropping to prove importance
 
 **Words to watch:** independent coverage, local/regional/national media outlets, written by a leading expert, active social media presence
-**Problem:** LLMs hit readers over the head with claims of notability, often listing sources without context.
+**Problem:** AI writing often lists well-known publications or follower counts to prove that a person matters. The list usually gives no useful context.
 **Before:**
 > Her views have been cited in The New York Times, BBC, Financial Times, and The Hindu. She maintains an active social media presence with over 500,000 followers.
 **After:**
 > Her views have been cited in The New York Times and the BBC.
 
-(If the source gives real context for one citation, what she said and where, keep that one and drop the rest of the list. Don't invent the context to make the trimmed version sound better.)
+If the source explains what the person said and where, keep that useful citation. Do not invent context for a shorter version.
 
-### 3. Superficial Analyses with -ing Endings
+### 3. Shallow analysis with -ing phrases
 
 **Words to watch:** highlighting/underscoring/emphasizing..., ensuring..., reflecting/symbolizing..., contributing to..., cultivating/fostering..., encompassing..., showcasing...
-**Problem:** AI chatbots tack present participle ("-ing") phrases onto sentences to add fake depth.
+**Problem:** AI writing often adds an -ing phrase to make a simple fact sound deeper than it is.
 **Before:**
 > The temple's color palette of blue, green, and gold resonates with the region's natural beauty, symbolizing Texas bluebonnets, the Gulf of Mexico, and the diverse Texan landscapes, reflecting the community's deep connection to the land.
 **After:**
 > The temple is painted blue, green, and gold, colors meant to evoke Texas bluebonnets and the Gulf of Mexico.
 
-### 4. Promotional and Advertisement-like Language
+### 4. Sales language
 
 **Words to watch:** boasts a, vibrant, rich (figurative), profound, enhancing its, showcasing, exemplifies, commitment to, natural beauty, nestled, in the heart of, groundbreaking (figurative), renowned, breathtaking, must-visit, stunning
-**Problem:** LLMs have serious problems keeping a neutral tone, especially for "cultural heritage" topics.
+**Problem:** AI writing often sounds like an advertisement, especially when it describes places, culture, products, or organizations.
 **Before:**
 > Nestled within the breathtaking region of Gonder in Ethiopia, Alamata Raya Kobo stands as a vibrant town with a rich cultural heritage and stunning natural beauty.
 **After:**
 > Alamata Raya Kobo is a town in the Gonder region of Ethiopia.
 
-### 5. Vague Attributions and Weasel Words
+### 5. Vague sources
 
 **Words to watch:** Industry reports, Observers have cited, Experts argue, Some critics argue, several sources/publications (when few cited)
-**Problem:** AI chatbots attribute opinions to vague authorities without specific sources.
+**Problem:** AI writing often assigns a claim to unnamed experts, critics, reports, or observers.
 **Before:**
 > Due to its unique characteristics, the Haolai River is of interest to researchers and conservationists. Experts believe it plays a crucial role in the regional ecosystem.
 **After:**
 > Researchers and conservationists study the Haolai River for its unusual characteristics.
 
-(If a real source exists, name it. Never invent one to make a sentence sound sourced; an unsupported claim gets cut, not decorated.)
+Name a real source when the source text provides one. Otherwise, remove the unsupported claim. Never invent a source.
 
-### 6. Outline-like "Challenges and Future Prospects" Sections
+### 6. Formulaic challenges and outlook sections
 
 **Words to watch:** Despite its... faces several challenges..., Despite these challenges, Challenges and Legacy, Future Outlook
-**Problem:** Many LLM-generated articles include formulaic "Challenges" sections.
+**Problem:** AI articles often add a stock section about challenges, future prospects, or continued growth. These sections usually repeat vague claims instead of adding facts.
 **Before:**
 > Despite its industrial prosperity, Korattur faces challenges typical of urban areas, including traffic congestion and water scarcity. Despite these challenges, with its strategic location and ongoing initiatives, Korattur continues to thrive as an integral part of Chennai's growth.
 **After:**
 > Korattur has recurring traffic congestion and water shortages.
 
-(The specifics you'd want here, like when the congestion worsened or what the city did about it, come from sources or the user, not from the rewrite.)
+Add details such as dates or public actions only when they come from the source or the user.
 
-## LANGUAGE AND GRAMMAR PATTERNS
+## Language and grammar patterns
 
-### 7. Overused "AI Vocabulary" Words
+### 7. Overused AI words
 
 **High-frequency AI words:** Actually, additionally, align with, crucial, delve, emphasizing, enduring, enhance, fostering, garner, gate/gated/gating (figurative; preserve established technical usage), highlight (verb), interplay, intricate/intricacies, key (adjective), landscape (abstract noun), pivotal, quietly, showcase, tapestry (abstract noun), testament, underscore (verb), valuable, vibrant
-**Problem:** These words appear far more frequently in post-2023 text. They often co-occur.
+**Problem:** AI writing uses these words much more often than most people do, especially in groups.
 **Before:**
 > Additionally, a distinctive feature of Somali cuisine is the incorporation of camel meat. An enduring testament to Italian colonial influence is the widespread adoption of pasta in the local culinary landscape, showcasing how these dishes have integrated into the traditional diet.
 **After:**
 > Somali cuisine also includes camel meat, which is considered a delicacy. Pasta dishes, introduced during Italian colonization, remain common, especially in the south.
 
-### 8. Avoidance of "is"/"are" (Copula Avoidance)
+### 8. Avoiding is and are
 
 **Words to watch:** serves as/stands as/marks/represents [a], boasts/features/offers [a]
-**Problem:** LLMs substitute elaborate constructions for simple copulas.
+**Problem:** AI writing often replaces simple verbs such as *is*, *are*, and *has* with longer phrases.
 **Before:**
 > Gallery 825 serves as LAAA's exhibition space for contemporary art. The gallery features four separate spaces and boasts over 3,000 square feet.
 **After:**
 > Gallery 825 is LAAA's exhibition space for contemporary art. The gallery has four rooms totaling 3,000 square feet.
 
-### 9. Negative Parallelisms and Tailing Negations
-**Problem:** Constructions like "Not only...but..." or "It's not just about..., it's..." are overused. So are clipped tailing-negation fragments such as "no guessing" or "no wasted motion" tacked onto the end of a sentence instead of written as a real clause.
+### 9. Not X but Y and clipped negative endings
+**Problem:** AI writing overuses forms such as "Not only...but..." and "It's not just X, it's Y."
+
+It also adds clipped endings such as "no guessing" instead of writing a clear clause.
 **Before:**
 > It's not just about the beat riding under the vocals; it's part of the aggression and atmosphere. It's not merely a song, it's a statement.
 **After:**
@@ -138,15 +140,17 @@ When voice is appropriate, avoid uniform sentence structures, bloodless neutrali
 **After:**
 > The options come from the selected item without forcing the user to guess.
 
-### 10. Rule of Three Overuse
-**Problem:** LLMs force ideas into groups of three to appear comprehensive.
+### 10. Forced groups of three
+**Problem:** AI writing often forces ideas into groups of three to sound complete.
 **Before:**
 > The event features keynote sessions, panel discussions, and networking opportunities. Attendees can expect innovation, inspiration, and industry insights.
 **After:**
 > The event includes talks and panels. There's also time for informal networking between sessions.
 
-### 11. Elegant Variation and Repeated Sentence Openings
-**Problem:** AI has repetition-penalty code causing excessive synonym substitution. The same machinery misses in the other direction in narrative prose, where consecutive sentences all open on the same subject, usually a pronoun, and nothing varies where the sentence starts. Both are one defect: the model is managing repetition by rule instead of by ear. Cure over-variation by settling on a single referent. Cure under-variation by merging the sentences, by giving the subject role to something other than the character, or by opening on the action so the pronoun arrives later.
+### 11. Changing names and repeating sentence openings
+**Problem:** AI writing handles repetition by rule instead of by ear. It may keep renaming the same person or thing. It may also start several sentences with the same subject, often *she* or *he*.
+
+Use one clear name for the same subject. For repeated openings, merge sentences, change the subject when that helps, or begin with the action.
 **Before (synonym cycling):**
 > The protagonist faces many challenges. The main character must overcome obstacles. The central figure eventually triumphs. The hero returns home.
 **After:**
@@ -156,27 +160,27 @@ When voice is appropriate, avoid uniform sentence structures, bloodless neutrali
 **After:**
 > She noted the door and its lock, then filed both away.
 
-The fix is not banning the repeated word. A run of three sentences becoming one is what removes the tell; the survivor may still start with "She."
+Do not ban the repeated word. Fix the repeated sentence pattern. The remaining sentence may still start with "She."
 
-### 12. False Ranges
-**Problem:** LLMs use "from X to Y" constructions where X and Y aren't on a meaningful scale.
+### 12. False from X to Y ranges
+**Problem:** AI writing often uses "from X to Y" when X and Y do not form a real range.
 **Before:**
 > Our journey through the universe has taken us from the singularity of the Big Bang to the grand cosmic web, from the birth and death of stars to the enigmatic dance of dark matter.
 **After:**
 > The book covers the Big Bang, star formation, and current theories about dark matter.
 
-### 13. Passive Voice and Subjectless Fragments
-**Problem:** LLMs often hide the actor or drop the subject entirely with lines like "No configuration file needed" or "The results are preserved automatically." Rewrite these when active voice makes the sentence clearer and more direct.
+### 13. Passive voice and missing subjects
+**Problem:** AI writing often hides who acts or drops the subject. Use active voice when it makes the actor and action clearer.
 **Before:**
 > No configuration file needed. The results are preserved automatically.
 **After:**
 > You do not need a configuration file. The system preserves the results automatically.
 
-## STYLE PATTERNS
+## Style patterns
 
-### 14. Em Dashes (and En Dashes): Cut Them
+### 14. Em and en dashes
 
-**Rule:** The final rewrite contains no em dashes (—) or en dashes (–). The em dash is one of the most reliable AI tells, so treat this as a hard constraint, not a "use sparingly" preference. Replace each one, in rough order of preference: a period (start a new sentence), a comma (a tight aside), a colon (introducing an explanation), parentheses (a true aside), or restructure the sentence. Also catch spaced em dashes (` — `) and double hyphens (` -- `) used the same way.
+**Rule:** The final rewrite must not contain em dashes (—) or en dashes (–), unless the writer's sample uses them. Replace a dash with a period, comma, colon, or parentheses, or rewrite the sentence. Also check for spaced dashes (` — `) and double hyphens (` -- `) used as dashes.
 **Before:**
 > The term is primarily promoted by Dutch institutions—not by the people themselves. You don't say "Netherlands, Europe" as an address—yet this mislabeling continues—even in official documents.
 **After:**
@@ -186,17 +190,17 @@ The fix is not banning the repeated word. A run of three sentences becoming one
 **After:**
 > The new policy, announced without warning, affects thousands of workers. The changes, long overdue according to critics, will take effect immediately.
 
-Before returning the final rewrite, scan it for `—` and `–`. Any hit means the draft isn't done. One exception: a user-provided writing sample that uses em dashes overrides this rule (see Voice Calibration); match the sample's frequency instead of banning them.
+Before returning the rewrite, search for `—` and `–`. Remove each one unless the writer's sample uses that mark. In that case, match the sample's rate.
 
-### 15. Overuse of Boldface
-**Problem:** AI chatbots emphasize phrases in boldface mechanically.
+### 15. Too much bold text
+**Problem:** AI chatbots often bold words and phrases without a clear reason.
 **Before:**
 > It blends **OKRs (Objectives and Key Results)**, **KPIs (Key Performance Indicators)**, and visual strategy tools such as the **Business Model Canvas (BMC)** and **Balanced Scorecard (BSC)**.
 **After:**
 > It blends OKRs, KPIs, and visual strategy tools like the Business Model Canvas and Balanced Scorecard.
 
-### 16. Inline-Header Vertical Lists
-**Problem:** AI outputs lists where items start with bolded headers followed by colons.
+### 16. Lists with bold mini-headings
+**Problem:** AI writing often uses vertical lists in which every item starts with a bold label and a colon.
 **Before:**
 > - **User Experience:** The user experience has been significantly improved with a new interface.
 > - **Performance:** Performance has been enhanced through optimized algorithms.
@@ -204,15 +208,15 @@ Before returning the final rewrite, scan it for `—` and `–`. Any hit means t
 **After:**
 > The update improves the interface, speeds up load times through optimized algorithms, and adds end-to-end encryption.
 
-### 17. Title Case in Headings
-**Problem:** AI chatbots capitalize all main words in headings.
+### 17. Title case in headings
+**Problem:** AI chatbots often capitalize every main word in a heading.
 **Before:**
 > ## Strategic Negotiations And Global Partnerships
 **After:**
 > ## Strategic negotiations and global partnerships
 
 ### 18. Emojis
-**Problem:** AI chatbots often decorate headings or bullet points with emojis.
+**Problem:** AI chatbots often add emojis to headings and list items as decoration.
 **Before:**
 > 🚀 **Launch Phase:** The product launches in Q3
 > 💡 **Key Insight:** Users prefer simplicity
@@ -220,28 +224,28 @@ Before returning the final rewrite, scan it for `—` and `–`. Any hit means t
 **After:**
 > The product launches in Q3. User research showed a preference for simplicity. Next step: schedule a follow-up meeting.
 
-### 19. Curly Quotation Marks
-**Problem:** ChatGPT uses curly quotes (“...”) instead of straight quotes ("...").
+### 19. Curly quotation marks
+**Problem:** ChatGPT often uses curly quotes (“...”) where the writer or target format uses straight quotes ("...").
 **Before:**
 > He said “the project is on track” but others disagreed.
 **After:**
 > He said "the project is on track" but others disagreed.
 
-## COMMUNICATION PATTERNS
+## Chatbot patterns
 
-### 20. Collaborative Communication Artifacts
+### 20. Chatbot text left in the answer
 
 **Words to watch:** I hope this helps, Of course!, Certainly!, You're absolutely right!, Would you like..., Want me to...?, Want me to give examples?, Should I continue?, let me know, here is a...
-**Problem:** Text meant as chatbot correspondence gets pasted as content.
+**Problem:** A chatbot's greeting, offer, or closing sometimes remains in text that should stand on its own.
 **Before:**
 > Here is an overview of the French Revolution. I hope this helps! Let me know if you'd like me to expand on any section.
 **After:**
 > The French Revolution began in 1789 when financial crisis and food shortages led to widespread unrest.
 
-### 21. Knowledge-Cutoff Disclaimers and Speculative Gap-Filling
+### 21. Knowledge-limit disclaimers and guesses
 
 **Words to watch:** as of [date], Up to my last training update, While specific details are limited/scarce..., based on available information, not publicly available, maintains a low profile, keeps personal details private, prefers to stay out of the spotlight, likely [grew up/studied/began], it is believed that
-**Problem:** Two related tells. (a) Older models leave hard knowledge-cutoff disclaimers in the text. (b) When a model can't find a source, it writes a paragraph *about* not finding one and then invents plausible filler to cover the gap. For a private person the guess almost always lands on the same stock phrases ("maintains a low profile," "keeps personal details private"), none of it sourced. Say what isn't known, or cut the sentence; don't dress a guess up as fact.
+**Problem:** Older models may mention the date when their knowledge ends. A model may also explain that it could not find a source, then fill the gap with a plausible guess. State what the source does not show, or remove the sentence. Do not present a guess as a fact.
 **Before (cutoff disclaimer):**
 > While specific details about the company's founding are not extensively documented in readily available sources, it appears to have been established sometime in the 1990s.
 **After:**
@@ -251,16 +255,16 @@ Before returning the final rewrite, scan it for `—` and `–`. Any hit means t
 **After:**
 > Her early life is not documented in the available sources. (Or omit the section.)
 
-### 22. Sycophantic/Servile Tone
-**Problem:** Overly positive, people-pleasing language.
+### 22. Overly agreeable tone
+**Problem:** AI assistants often praise the user or agree before giving the answer.
 **Before:**
 > Great question! You're absolutely right that this is a complex topic. That's an excellent point about the economic factors.
 **After:**
 > The economic factors you mentioned are relevant here.
 
-## FILLER AND HEDGING
+## Filler and hedging
 
-### 23. Filler Phrases
+### 23. Filler phrases
 
 **Before → After:**
 - "In order to achieve this goal" → "To achieve this"
@@ -270,44 +274,44 @@ Before returning the final rewrite, scan it for `—` and `–`. Any hit means t
 - "The system has the ability to process" → "The system can process"
 - "It is important to note that the data shows" → "The data shows"
 
-### 24. Excessive Hedging
+### 24. Too many qualifiers
 
 **Phrases to watch:** to be fair, it's also possible, could potentially, might arguably, in some cases it may, this is an inference
-**Problem:** Over-qualifying statements. Iterative editing compounds this: each pass softens an overstatement, then softens the qualifier, until nearly every conclusion carries a fairness clause and the prose reads like it was negotiated. A claim earns one honest qualifier at most; a caveat that exists only because an earlier draft overreached should be cut along with the overreach.
+**Problem:** Repeated editing can add one qualifier after another until every claim sounds uncertain. Keep a qualifier only when the source supports it and the meaning needs it. Remove caveats that only repair an earlier overstatement.
 **Before:**
 > It could potentially possibly be argued that the policy might have some effect on outcomes.
 **After:**
 > The policy may affect outcomes.
 
-### 25. Generic Positive Conclusions
-**Problem:** Vague upbeat endings.
+### 25. Generic positive endings
+**Problem:** AI writing often ends with vague optimism instead of the last useful fact.
 **Before:**
 > The future looks bright for the company. Exciting times lie ahead as they continue their journey toward excellence. This represents a major step in the right direction.
 **After:**
 > (Cut the paragraph. End on the last concrete fact instead of a send-off. If the source states real plans, use those.)
 
-### 26. Hyphenated Word Pair Overuse
+### 26. Too many hyphenated word pairs
 
 **Words to watch:** third-party, cross-functional, client-facing, data-driven, decision-making, well-known, high-quality, real-time, long-term, end-to-end
-**Problem:** AI hyphenates these uniformly, including in predicate position (`the report is high-quality`). Humans hyphenate inconsistently — typically only when the compound is attributive (`a high-quality report`) and often dropping the hyphen otherwise (`the report is high quality`). Keep attributive-position hyphens; drop them when the compound follows the noun.
+**Problem:** AI writing often hyphenates these pairs everywhere. Keep the hyphen before a noun when grammar needs it, as in `a high-quality report`. Drop it after the noun, as in `the report is high quality`.
 **Before:**
 > The cross-functional team delivered a high-quality, data-driven report. The team is cross-functional, the report is high-quality, and the methodology is data-driven.
 **After:**
 > The cross-functional team delivered a high-quality, data-driven report. The team is cross functional, the report is high quality, and the methodology is data driven.
 
-### 27. Persuasive Authority Tropes
+### 27. Pretending to reveal a deeper truth
 
 **Phrases to watch:** The real question is, at its core, in reality, what really matters, fundamentally, the deeper issue, the heart of the matter
-**Problem:** LLMs use these phrases to pretend they are cutting through noise to some deeper truth, when the sentence that follows usually just restates an ordinary point with extra ceremony.
+**Problem:** AI writing uses these phrases to make an ordinary point sound like a hidden truth.
 **Before:**
 > The real question is whether teams can adapt. At its core, what really matters is organizational readiness.
 **After:**
 > The question is whether teams can adapt. That mostly depends on whether the organization is ready to change its habits.
 
-### 28. Signposting and Announcements
+### 28. Announcing the next point
 
-**Phrases to watch:** Let's dive in, let's explore, let's break this down, here's what you need to know, now let's look at, without further ado. The tell is structural, not just formal: announcing what's about to be said or warned about instead of just saying it. That survives a casual reword just as easily — heads up, quick note, one thing that got me was X so watch out for Y, before I forget.
-**Problem:** LLMs announce what they are about to do instead of doing it. This meta-commentary slows the writing down and gives it a tutorial-script feel. Recasing the announcement into casual language ("one thing that bit me, so heads up on X") is not a fix, it's the same tell in different clothes — the announcement itself has to go, not just its formality.
+**Phrases to watch:** Let's dive in, let's explore, let's break this down, here's what you need to know, now let's look at, without further ado, heads up, quick note, before I forget
+**Problem:** AI writing often announces the next point instead of stating it. A casual phrase such as "one thing that bit me" can have the same problem. Remove the announcement, not just its formal tone.
 **Before:**
 > Let's dive into how caching works in Next.js. Here's what you need to know.
 **After:**
@@ -317,10 +321,10 @@ Before returning the final rewrite, scan it for `—` and `–`. Any hit means t
 **After:**
 > The webpack dev server doesn't send the CORS header by default.
 
-### 29. Fragmented Headers
+### 29. A heading repeated in the first sentence
 
 **Signs to watch:** A heading followed by a one-line paragraph that simply restates the heading before the real content begins.
-**Problem:** LLMs often add a generic sentence after a heading as a rhetorical warm-up. It usually adds nothing and makes the prose feel padded.
+**Problem:** AI writing often follows a heading with a sentence that only repeats the heading. Remove the repeated sentence.
 **Before:**
 > ## Performance
 >
@@ -332,118 +336,121 @@ Before returning the final rewrite, scan it for `—` and `–`. Any hit means t
 >
 > When users hit a slow page, they leave.
 
-### 30. Diff-Anchored Writing
-**Problem:** Documentation or comments written as if narrating a change rather than describing the thing as it is. Unless the document is inherently version-scoped (changelogs, release notes, migration guides), it should read coherently without knowing what changed in the last commit.
+### 30. Writing about the previous version
+**Problem:** Documentation and comments should describe the current behavior. Mention the previous version only in change logs, release notes, migration guides, and other documents about change.
 **Before:**
 > This function was added to replace the previous approach of iterating through all items, which caused O(n²) performance.
 **After:**
 > This function uses a hash map for O(1) lookups, avoiding the O(n²) cost of naive iteration.
 
-### 31. Manufactured Punchlines and Staccato Drama
-**Problem:** LLMs often make every sentence land like a quotable closer, then stack short declarative fragments to manufacture drama. A single short sentence for emphasis is fine; a run of them starts to sound engineered.
+### 31. Forced punchlines and dramatic fragments
+**Problem:** AI writing often turns each sentence into a dramatic closing line. One short sentence can add emphasis. A row of short fragments usually feels forced.
 **Before:**
 > Then AlphaEvolve arrived. It had no preference for symmetry. No aesthetic prior. No nostalgia for human taste. The old rules were gone.
 **After:**
 > AlphaEvolve changed the search because it did not favor symmetry or human-looking designs. That made some of the older assumptions less useful.
 
-### 32. Aphorism Formulas
+### 32. Formulaic sayings
 
 **Words to watch:** X is the Y of Z, X becomes a trap, X is not a tool but a mirror, the language of, the currency of, the architecture of
-**Problem:** LLMs turn ordinary claims into reusable aphorisms that sound profound without adding precision. Replace the formula with the concrete claim it is gesturing at.
+**Problem:** AI writing often turns an ordinary claim into a saying that sounds deep but adds no detail. Replace the saying with the specific claim.
 **Before:**
 > Symmetry is the language of trust. Efficiency becomes a trap when teams forget the human layer.
 **After:**
 > Symmetric layouts often feel more predictable to users. Teams can over-optimize workflows and miss how people actually use them.
 
-### 33. Conversational Rhetorical Openers
+### 33. Fake-candid openings
 
 **Phrases to watch:** Honestly?, Look, Here's the thing, The thing is, Let's be honest, Real talk, when used as standalone hooks or fake-candid pauses before an ordinary point.
-**Problem:** LLMs open with a fake-candid hook to manufacture intimacy before delivering a routine claim. The tell is the theatrical pause-and-reveal: a one-word question or aside, then the "real" answer. A person being honest usually just says the thing.
+**Problem:** AI writing often starts with a staged pause or claim of honesty before making a routine point. State the point directly.
 **Before:**
 > Is it worth the price? Honestly? It depends on how often you'll use it.
 **After:**
 > Whether it's worth the price depends on how often you'll use it.
 
-### 34. Shadowboxing (Defending Against Unraised Objections)
+### 34. Answering objections no one raised
 
 **Phrases to watch:** This isn't (mainly/really) about, I'm not saying/arguing/trying to, To be clear, Don't get me wrong, This is not to say, You could argue/frame this differently but, Some might say... but
-**Problem:** LLMs rebut objections nobody in the published text raised, usually leftovers from the drafting conversation. The tell is a negation about the piece's own aims or the author's intent that is unattributed, dropped within a sentence, and about a topic that appears nowhere else in the piece. An object-level negation ("the API is not thread-safe") is a claim, not shadowboxing.
+**Problem:** AI writing may answer an objection that does not appear in the text. Watch for an unattributed statement about what the writer does not mean, especially when the topic appears nowhere else. A direct claim such as "the API is not thread-safe" is not this pattern.
 **Before:**
 > This isn't mainly about prompt length, and I'm not arguing that documentation doesn't matter. You could categorize the problem another way, but the issue is whether the agent can use the instruction when it acts.
 **After:**
 > The issue is whether the agent can use the instruction when it acts.
 
-(Cut only the defensive clause and leave the surrounding argument alone. A defense can smuggle in a real claim: if "I'm not arguing documentation doesn't matter" concedes a point the piece actually uses, restate it affirmatively instead of deleting it. An objection the text attributes to someone or genuinely engages stays; §9 governs its phrasing.)
+Remove only the unsupported defense. If it contains a real claim, state that claim directly. Keep an objection when the text names its source or answers it in full.
 
-### 35. Editorial Scar Tissue (Phantom Alternatives)
+### 35. Rejecting fake alternatives
 
 **Phrases to watch:** A tempting option/approach would be, One might be tempted to, An obvious approach would be, You might think... but, It would be easy to just, Some would suggest
-**Problem:** The model recycles its own corrected mistakes as strawmen: mid-argument the text rebuts a "tempting" alternative no reader would consider, drops it, then does it again later on an unrelated tangent. Each digression is a scar from the drafting conversation, where the option was live until a human killed it. The tells: the alternative is attributed to no one, appears nowhere else in the piece, and is dismissed in a clause or two.
+**Problem:** AI writing may introduce an option that no reader would consider, reject it in a clause, and never mention it again. This often leaves an old drafting idea in the final text. Remove the fake option and state the real constraint directly.
 **Before:**
 > Session tokens are rotated every 24 hours. A tempting approach would be to rotate them by restarting the auth service on a cron job, but that would drop every active session. Rotation happens in place, and clients refresh transparently.
 **After:**
 > Session tokens are rotated every 24 hours, in place, and clients refresh transparently.
 
-(Cut the whole digression and let the surrounding sentences rejoin; if the rebuttal smuggles in a real constraint the piece uses, restate it affirmatively. One phantom rebuttal is ambiguous; several on unrelated tangents is the confession. The general test: if you can explain which previous edit caused a sentence to exist, rather than what new information it contributes, it is scar tissue — rewrite the paragraph from its point instead of patching the sentence.)
+One rejected option may be valid. Several short, unrelated rejections are a stronger sign. Ask what new information each sentence adds. If it only records an earlier edit, rewrite the paragraph around its main point.
 
-## DETECTION GUIDANCE
+## Check for false positives
 
-### What NOT to flag (false positives)
+### What not to flag
 
-A clean human writer can hit several of the patterns above without any AI involvement. Before rewriting, sanity-check that you are not gutting legitimate prose. The following are *not* reliable indicators on their own:
+A person may use some of these patterns. Do not treat any item below as proof by itself:
 
 - **Perfect grammar and consistent style.** Many writers are professionals or have been edited. Polish does not equal AI.
-- **Mixed casual and formal registers.** This often signals a person in a technical field, a young writer, or someone with neurodivergent prose habits — not a chatbot.
+- **Mixed casual and formal styles.** This can reflect the writer's field, age, or personal habits.
 - **"Bland" or "robotic" prose.** AI prose has *specific* tells. Generic dryness without those tells is just dry writing.
-- **Formal or academic vocabulary.** AI overuses *specific* fancy words (see §7), not all fancy words. Don't flatten "ostensibly" or "constituent" just because they sound brainy.
+- **Formal or academic words.** §7 lists specific words that AI writing overuses. Do not simplify every formal word.
 - **Letter-style opening or closing on a comment.** Salutations and sign-offs predate ChatGPT by centuries.
 - **Common transition words in isolation.** *Additionally*, *moreover*, *consequently* are AI-coded only when piled up. One *however* is not a tell.
 - **Curly quotes alone.** macOS, Word, Google Docs, and most CMSes auto-curl by default. Curly quotes only count when stacked with other tells.
 - **Em dashes alone.** Many editors and journalists use them often. Em dashes are evidence only when paired with formulaic sales-y rhythm.
-- **One short emphatic sentence.** Humans use clipped sentences to land a point. Flag staccato drama only when several short fragments appear in a row and inflate the tone.
-- **Deliberate anaphora.** Repeating a sentence opening on purpose is an old device, and good prose uses it to build cadence or pressure ("She came. She saw. She conquered."). Flag a repeated opening only when the run does no rhetorical work and reads as the model failing to vary rather than a writer choosing.
+- **One short sentence for emphasis.** Flag dramatic fragments only when several appear in a row.
+- **Deliberate repeated openings.** Writers may repeat an opening to build rhythm or pressure, as in "She came. She saw. She conquered." Change it only when the repetition adds nothing.
 - **"Honestly" or "look" mid-sentence.** These are ordinary in casual writing. The tell is the standalone theatrical opener, not the word itself.
-- **Disclaimers and scoping that do real work.** "This guide does not cover Windows," legal and safety notices, and corrections of misconceptions readers actually hold are content, not shadowboxing (§34). So are attributed objections the text engages, replies and FAQs that answer someone by design, and a single self-aware aside in a voiced piece.
-- **Alternatives a reader would actually reach for.** Design docs weighing real options, tutorials warning against genuinely tempting mistakes, and essays that steelman before disagreeing are content, not scar tissue (§35). The tell is the implausible alternative dispatched mid-flow and never revisited.
+- **Useful limits and disclaimers.** Keep scope statements, legal and safety notices, real corrections, named objections, replies, and FAQ answers.
+- **Real alternatives.** Keep options that a reader may consider in a design document, tutorial, or argument. Remove only an unlikely option that the text dismisses and never uses again.
 - **Unsourced claims.** Most of the web is unsourced. Lack of citations doesn't prove anything.
 - **Correct, complex formatting.** Visual editors and templates produce clean output without any AI.
 - **Secondhand text.** Do not rewrite watched phrases inside quotations, titles, proper names, or examples where the phrase is being discussed rather than used.
 
-When in doubt, look for **clusters** of tells, not isolated ones. A single em dash means nothing; em dashes plus rule-of-three plus *vibrant tapestry* plus a "Conclusion" section is a confession.
+When unsure, look for several patterns together. One em dash proves nothing. Several stock patterns in the same passage are stronger evidence.
 
-### Signs of human writing (preserve these)
+### Human details to keep
 
-When you see these, lean toward leaving the prose alone — they are evidence of a real person writing, and over-editing will destroy what makes the piece sound human:
+These details often carry the writer's voice. Keep them unless they hurt the meaning:
 
-- **Specific, unusual, hard-to-fabricate detail.** A real address. A weird quote. The phrase "the lawyer who used to work upstairs from my dentist." LLMs round off specifics; humans hoard them.
-- **Mixed feelings and unresolved tension.** "I think this is mostly good, but it bothers me, and I can't fully explain why." LLMs default to clean takes.
+- **Specific, unusual details.** Keep a real address, an odd quote, or a phrase such as "the lawyer who used to work upstairs from my dentist."
+- **Mixed feelings and unresolved tension.** Keep lines such as "I think this is mostly good, but it bothers me, and I can't fully explain why."
 - **Dated, era-bound references.** Slang, memes, or in-jokes that map to a specific year and subculture. Models lag by a year or more.
-- **First-person editorial choices the writer can defend.** If the writer can explain *why* they made a particular cut or used a particular word, that's a strong human signal.
+- **Deliberate first-person choices.** Keep a cut or word choice when the writer can explain why it belongs.
 - **Variety in sentence length.** Real writing alternates short and long. AI writing tends toward an even, mid-length cadence.
 - **Genuine asides, parentheticals, or self-corrections.** "(I keep wanting to say 'almost' here, but it really was certain.)" Models rarely interrupt themselves like this.
 - **Edits made before November 30, 2022.** ChatGPT's public launch. Anything older than that is, with very rare exceptions, not AI-written.
 
 ---
 
-## Invocation Modes
+## How to return the result
 
-**Pasted text (default).** The user gives text in the conversation. Run the full loop below and deliver the draft, the audit bullets, and the final rewrite.
+**Pasted text (default).** Return the draft, a short list of remaining AI patterns, and the final rewrite.
 
-**File mode.** The user points at a file. Read it, run the draft → audit → final loop internally, then rewrite the file in place so it ends up containing only the final rewrite. Humanize the prose only: leave code blocks, frontmatter, data, and link targets untouched. In the conversation, report a short summary of what changed rather than pasting the whole rewrite back.
+**File mode.** When the user names a file, run the full rewrite process but write only the final text to the file. Change prose only. Keep code blocks, YAML metadata, data, and link targets unchanged. Then give the user a short summary.
 
-**Embedded mode.** Another task or agent is using this skill as one step of a larger job (a PR description, a commit message, a doc). Run the loop internally and output only the final text. No draft, no audit bullets, no summary. The caller wants prose, not ceremony.
+**Embedded mode.** When another task uses this skill for a pull request, commit message, or document, return only the final text.
 
-## Process and Output
+## Rewrite process
 
-1. Read the input carefully and identify every instance of the patterns above.
-2. Write a **draft rewrite**. Check that it reads naturally aloud, varies sentence length, prefers specific details and simple constructions (is/are/has), and keeps the appropriate register.
-3. Ask two questions: **"What makes the below so obviously AI generated?"** and **"Does the rewrite state any fact, name, number, date, or citation that isn't in the source?"** Answer briefly. A fabrication is a defect even when it sounds more human than the vague original.
-4. Revise into a **final rewrite** that addresses them and contains no em or en dashes (see §14). Revise by re-saying the point, not by patching the flagged phrase: a patch that leaves the sentence heavier than a person would write it is new scar tissue (§35), and enough of them make the prose read as cross-examined. When a sentence resists repair, ask "how would a person naturally make this point?" and rewrite the paragraph from that.
+1. Read the source and mark each AI pattern.
+2. Write a draft. Read it aloud. Check the rhythm, details, simple verbs such as *is* and *has*, and the right level of formality.
+3. Ask two questions:
+   - **"What still sounds AI-generated?"**
+   - **"Did the rewrite add or remove any fact, name, number, date, quote, citation, ranking, or other claim?"**
+   Treat any unsupported addition or lost claim as an error.
+4. Write the final version. State each point naturally instead of patching one flagged phrase at a time. If a sentence stays awkward, rewrite the paragraph around its main point. Apply the dash rule in §14.
 
-In pasted-text mode, deliver the draft, the brief "still-AI" bullets, the final rewrite, and (optionally) a short summary of changes. In file and embedded modes, run the same loop but deliver only what the mode calls for (see Invocation Modes).
+Return the result required by [How to return the result](#how-to-return-the-result).
 
-## Reference
+## Source
 
-This skill is based on [Wikipedia:Signs of AI writing](https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing), maintained by WikiProject AI Cleanup. The patterns documented there come from observations of thousands of instances of AI-generated text on Wikipedia.
+This skill is based on [Wikipedia: Signs of AI writing](https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing), maintained by WikiProject AI Cleanup. Its patterns come from reviews of AI-generated text on Wikipedia.
 
-Key insight from Wikipedia: "LLMs use statistical algorithms to guess what should come next. The result tends toward the most statistically likely result that applies to the widest variety of cases."
+Wikipedia's main point: "LLMs use statistical algorithms to guess what should come next. The result tends toward the most statistically likely result that applies to the widest variety of cases."

+ 2 - 2
agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Humanizer"
-  short_description: "Remove AI writing patterns from prose"
-  default_prompt: "Use $humanizer to make this text sound natural while preserving its meaning and facts."
+  short_description: "Make AI-written text sound like the writer"
+  default_prompt: "Use $humanizer to rewrite this text in my voice without changing its facts."

+ 40 - 20
scripts/validate-package.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Validate Humanizer's portable package surfaces without external dependencies."""
+"""Check Humanizer's package files without external dependencies."""
 
 from __future__ import annotations
 
@@ -11,57 +11,77 @@ from pathlib import Path
 ROOT = Path(__file__).resolve().parent.parent
 SKILL = (ROOT / "SKILL.md").read_text(encoding="utf-8")
 README = (ROOT / "README.md").read_text(encoding="utf-8")
+AGENTS = (ROOT / "AGENTS.md").read_text(encoding="utf-8")
 PLUGIN = json.loads((ROOT / ".claude-plugin" / "plugin.json").read_text(encoding="utf-8"))
 PLUGIN_SKILL = ROOT / "skills" / "humanizer" / "SKILL.md"
 
 
-def require(match: re.Match[str] | None, message: str) -> re.Match[str]:
+def require_match(match: re.Match[str] | None, message: str) -> re.Match[str]:
     if match is None:
         raise SystemExit(message)
     return match
 
 
-frontmatter = require(
+yaml_metadata = require_match(
     re.match(r"\A---\n(.*?)\n---\n", SKILL, re.DOTALL),
-    "SKILL.md must start with YAML frontmatter",
+    "SKILL.md must begin with YAML metadata",
 ).group(1)
 
-for nonportable_key in ("compatibility:", "allowed-tools:"):
-    if re.search(rf"(?m)^{re.escape(nonportable_key)}", frontmatter):
-        raise SystemExit(f"Remove nonportable frontmatter key: {nonportable_key[:-1]}")
+for unsupported_field in ("compatibility:", "allowed-tools:"):
+    if re.search(rf"(?m)^{re.escape(unsupported_field)}", yaml_metadata):
+        raise SystemExit(f"Remove unsupported YAML field: {unsupported_field[:-1]}")
 
-skill_version = require(
-    re.search(r'(?m)^\s+version:\s*["\']([^"\']+)["\']\s*$', frontmatter),
-    "SKILL.md metadata.version is missing",
+skill_version = require_match(
+    re.search(r'(?m)^\s+version:\s*["\']([^"\']+)["\']\s*$', yaml_metadata),
+    "Add metadata.version to SKILL.md",
 ).group(1)
-readme_version = require(
+readme_version = require_match(
     re.search(r"(?m)^- \*\*([0-9]+\.[0-9]+\.[0-9]+)\*\*", README),
-    "README version history is missing",
+    "Add a version entry to README.md",
 ).group(1)
 
-versions = {skill_version, readme_version, str(PLUGIN.get("version", ""))}
-if len(versions) != 1:
-    raise SystemExit(f"Version mismatch: {sorted(versions)}")
+package_versions = {skill_version, readme_version, str(PLUGIN.get("version", ""))}
+if len(package_versions) != 1:
+    raise SystemExit(
+        f"Use one package version in all files: {sorted(package_versions)}"
+    )
 
 if not PLUGIN_SKILL.is_symlink():
-    raise SystemExit("skills/humanizer/SKILL.md must link to the canonical root SKILL.md")
+    raise SystemExit("Link skills/humanizer/SKILL.md to the root SKILL.md")
 if PLUGIN_SKILL.resolve() != (ROOT / "SKILL.md").resolve():
-    raise SystemExit("skills/humanizer/SKILL.md must resolve to the root SKILL.md")
+    raise SystemExit("Make skills/humanizer/SKILL.md point to the root SKILL.md")
+
+plain_language_rules = (
+    "## Writing style",
+    "Lead with the main point.",
+    "Use common words and active voice.",
+    "Keep sentences and paragraphs short.",
+    "Use `must` for requirements.",
+    "Keep the full technical meaning.",
+)
+missing_plain_language_rules = [
+    rule for rule in plain_language_rules if rule not in AGENTS
+]
+if missing_plain_language_rules:
+    raise SystemExit(
+        "Add the missing Plain Language rules to AGENTS.md: "
+        + ", ".join(missing_plain_language_rules)
+    )
 
 pattern_numbers = [
     int(number)
     for number in re.findall(r"(?m)^### ([0-9]+)\. ", SKILL)
 ]
 if pattern_numbers != list(range(1, 36)):
-    raise SystemExit(f"Expected patterns 1-35, found {pattern_numbers}")
+    raise SystemExit(f"Number SKILL.md patterns from 1 through 35: {pattern_numbers}")
 
 readme_numbers = {
     int(number) for number in re.findall(r"(?m)^\| ([0-9]+) \|", README)
 }
 if readme_numbers != set(range(1, 36)):
-    raise SystemExit("README pattern table must contain patterns 1-35")
+    raise SystemExit("List patterns 1 through 35 in the README table")
 
 if len(SKILL.splitlines()) > 500:
-    raise SystemExit("SKILL.md exceeds the 500-line portability budget")
+    raise SystemExit("Keep SKILL.md at 500 lines or fewer")
 
 print(f"Humanizer package v{skill_version} is valid")