diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 4e4030d..62d5954 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -1,6 +1,6 @@ { "name": "author-toolkit", - "description": "Writing skills for fiction and narrative nonfiction authors", + "description": "Writing skills for fiction and narrative nonfiction authors, including an AI-writing audit/rewrite skill", "owner": { "name": "rhavekost", "email": "rob@kostlabs.com" @@ -8,8 +8,8 @@ "plugins": [ { "name": "author-toolkit", - "description": "Writing skills for fiction and narrative nonfiction authors", - "version": "1.0.0", + "description": "Writing skills for fiction and narrative nonfiction authors, including an AI-writing audit/rewrite skill", + "version": "1.1.0", "source": "./", "author": { "name": "rhavekost", diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 2d2c127..9caa7ac 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "author-toolkit", - "description": "Writing skills for fiction and narrative nonfiction authors", - "version": "1.0.0", + "description": "Writing skills for fiction and narrative nonfiction authors, including an AI-writing audit/rewrite skill", + "version": "1.1.0", "author": { "name": "rhavekost", "email": "rob@kostlabs.com" @@ -9,5 +9,5 @@ "homepage": "https://github.com/rhavekost/author-toolkit", "repository": "https://github.com/rhavekost/author-toolkit", "license": "MIT", - "keywords": ["writing", "fiction", "nonfiction", "editing", "author", "skills"] + "keywords": ["writing", "fiction", "nonfiction", "editing", "author", "skills", "ai-writing", "avoid-ai-writing"] } diff --git a/ATTRIBUTION.md b/ATTRIBUTION.md new file mode 100644 index 0000000..edd1895 --- /dev/null +++ b/ATTRIBUTION.md @@ -0,0 +1,18 @@ +# Attribution + +This project vendors third-party skills. Their original licenses and copyright +notices are preserved inside each skill directory. + +## avoid-ai-writing + +- **Skill:** `avoid-ai-writing` +- **Author:** Conor Bronsdon ([@ConorBronsdon](https://github.com/conorbronsdon)) +- **Source:** https://github.com/conorbronsdon/avoid-ai-writing +- **License:** MIT +- **Vendored commit:** [`b38ee9f8f529476ac2d4f870d2dce2d9a155f34d`](https://github.com/conorbronsdon/avoid-ai-writing/commit/b38ee9f8f529476ac2d4f870d2dce2d9a155f34d) +- **Upstream LICENSE:** [`skills/avoid-ai-writing/LICENSE`](skills/avoid-ai-writing/LICENSE) +- **Upstream README:** [`skills/avoid-ai-writing/UPSTREAM-README.md`](skills/avoid-ai-writing/UPSTREAM-README.md) + +The full MIT license text and copyright notice are preserved unmodified at +`skills/avoid-ai-writing/LICENSE`, as required by the MIT license terms. No +changes have been made to the vendored skill contents. diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..a4648fd --- /dev/null +++ b/LICENSE @@ -0,0 +1,29 @@ +MIT License + +Copyright (c) 2026 rhavekost + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. + +--- + +This project vendors third-party skills that retain their original licenses. +See ATTRIBUTION.md for a list of vendored components and their upstream +license files. The vendored `avoid-ai-writing` skill is MIT-licensed +(Copyright (c) 2026 Conor Bronsdon); its upstream LICENSE is preserved at +`skills/avoid-ai-writing/LICENSE`. diff --git a/README.md b/README.md index a40c0be..0067f3e 100644 --- a/README.md +++ b/README.md @@ -24,6 +24,21 @@ For self-help and prescriptive nonfiction with storytelling elements: - **Reveal Engineering** - Twist/reframe setup and payoff - **Voice Editing** - Tone and persona consistency +### Avoid AI Writing +Audits and rewrites text to remove AI-ism patterns that make prose sound +machine-generated. Supports two modes: +- **Detect mode** — Flag AI-isms only; no rewriting. Use when auditing + published content, someone else's writing, or when you want to decide + yourself what to fix. +- **Rewrite mode** (default) — Flag AI-isms and rewrite the text to fix them. + +Recommended workflow: run `avoid-ai-writing` after the line-edit pass in +either `fiction-workshop` or `narrative-nonfiction` to catch any residual +AI patterns before final polish. + +Vendored from [conorbronsdon/avoid-ai-writing](https://github.com/conorbronsdon/avoid-ai-writing) +(MIT). See [ATTRIBUTION.md](ATTRIBUTION.md). + ## Installation ### Direct from GitHub @@ -48,6 +63,7 @@ Invoke skills directly: ```bash /author-toolkit:fiction-workshop /author-toolkit:narrative-nonfiction +/author-toolkit:avoid-ai-writing ``` Once activated, work with the editorial personas: @@ -62,6 +78,10 @@ Once activated, work with the editorial personas: "Help me design the transformation arc for my self-help book" "Check metaphor consistency in chapters 4-8" "Engineer the reveal for chapter 16" + +# Avoid AI Writing +"Audit this chapter for AI-isms" (detect mode) +"Rewrite this chapter to remove AI patterns" (rewrite mode) ``` ## Quick Reference @@ -78,7 +98,22 @@ Once activated, work with the editorial personas: | Reader journey | `/author-toolkit:narrative-nonfiction` | "Design the transformation arc" | | Metaphor consistency | `/author-toolkit:narrative-nonfiction` | "Check metaphor consistency in chapters 4-8" | | Exercise design | `/author-toolkit:narrative-nonfiction` | "Design exercises for [concept]" | +| Audit chapter for AI-isms | `/author-toolkit:avoid-ai-writing` | "Detect mode — flag AI patterns in this chapter" | +| Clean AI-isms from chapter | `/author-toolkit:avoid-ai-writing` | "Rewrite mode — remove AI patterns from this chapter" | + +## Attribution + +This plugin vendors the `avoid-ai-writing` skill by +[Conor Bronsdon (@ConorBronsdon)](https://github.com/conorbronsdon), +sourced from +[conorbronsdon/avoid-ai-writing](https://github.com/conorbronsdon/avoid-ai-writing) +and licensed under the MIT License. The upstream `LICENSE` and `README` are +preserved unmodified inside +[`skills/avoid-ai-writing/`](skills/avoid-ai-writing/). Full attribution and +vendored commit SHA are recorded in [ATTRIBUTION.md](ATTRIBUTION.md). ## License -MIT +MIT. See [LICENSE](LICENSE). Vendored third-party skills retain their +original licenses inside their skill directories — see +[ATTRIBUTION.md](ATTRIBUTION.md) for details. diff --git a/skills/avoid-ai-writing/.gitignore b/skills/avoid-ai-writing/.gitignore new file mode 100644 index 0000000..89bf7c5 --- /dev/null +++ b/skills/avoid-ai-writing/.gitignore @@ -0,0 +1,16 @@ +# OS +.DS_Store +Thumbs.db +Desktop.ini +*.swp +*~ + +# Editors +.vscode/ +.idea/ +*.sublime-project +*.sublime-workspace + +# Environment +.env +.env.local diff --git a/skills/avoid-ai-writing/CHANGELOG.md b/skills/avoid-ai-writing/CHANGELOG.md new file mode 100644 index 0000000..6cf8233 --- /dev/null +++ b/skills/avoid-ai-writing/CHANGELOG.md @@ -0,0 +1,160 @@ +# Changelog + +All notable changes to this project are documented here. + +--- + +## [3.3.0] — 2026-04-01 + +### Added +- **"Worth [verb]ing" vague endorsement pattern**: `worth reading`, `worth paying attention to`, `worth a look`, `worth exploring`, `worth checking out`, `worth your time` — broadens existing "it's worth noting that" to the full family +- **Reader-steering frames**: `Here's what's interesting`, `Here's what caught my eye`, `Here's what stood out` — added to both transition phrases and confidence calibration sections with context on when the pattern is a genuine problem vs. when data-backed usage is acceptable + +### Changed +- Version bump to 3.3.0 + +--- + +## [3.2.0] — 2026-03-31 + +### Added +- **Detect mode**: flag-only mode that identifies AI patterns without rewriting. Trigger with "detect," "flag only," "audit only," "just flag," "scan," or similar. Returns issues grouped by severity (P0/P1/P2) plus an assessment of which flags are clear problems vs. judgment calls. Useful when flagged patterns are intentional, when auditing published or third-party content, or when you want a quick scan without a full rewrite. + +### Changed +- Output format section now documents both rewrite (default) and detect mode outputs +- Version bump to 3.2.0 + +--- + +## [3.1.0] — 2026-03-25 + +### Added +- 3 new Tier 1 words from Pangram AI detection research: `keen` (as intensifier), `symphony` (metaphor), `embrace` (metaphor) +- 2 new template phrases: "Whether you're X or Y" (false-breadth), "I recently had the pleasure of" (review/social AI pattern) +- "In summary" added to transition phrases (alongside existing "In conclusion" / "To summarize") +- Structure-priority note in Rhythm section: structural regularity is the #1 signal AI detectors weight, above vocabulary +- Over-polishing warning: aggressive editing can push writing toward AI statistical profiles by removing natural disfluency + +### Changed +- Total vocabulary: 106 → 109 entries (60 Tier 1 + 38 Tier 2 + 11 Tier 3) +- Template phrases: 2 → 4 entries + +### Source +- Pangram Labs AI detection research (pangram.com) — decoder-only classifier trained on 28M human documents. Key insight: structural uniformity and pacing consistency are weighted higher than individual word choices. + +--- + +## [3.0.0] — 2026-03-20 + +### Added +- Novelty inflation pattern (AI treats established concepts as speaker inventions) +- False concession structure pattern +- Rhetorical question openers pattern +- Parenthetical hedging pattern +- Numbered list inflation pattern +- Severity tiers (P0/P1/P2) for prioritized auditing +- Self-reference escape hatch (exempts quoted examples from flagging) +- Context profiles with tolerance matrix (linkedin, blog, technical-blog, investor-email, docs, casual) +- Auto-detection cues for context inference +- Extended frontmatter: license, compatibility, author, tags, agentskills_spec + +### Changed +- Pattern count: 30 → 35 categories + +--- + +## [2.2.0] — 2026-03-18 + +### Added +- OpenClaw compatibility — added `version` and `metadata.openclaw` to SKILL.md frontmatter +- OpenClaw installation instructions in README (ClawHub and manual) +- Skill now works with both Claude Code and OpenClaw from a single `SKILL.md` + +### Changed +- `README.md` — broadened description to reference both platforms, reorganized installation into Claude Code and OpenClaw sections + +--- + +## [2.1.0] — 2026-03-18 + +### Added +- 5 new pattern categories: reasoning chain artifacts, sycophantic tone, acknowledgment loops, confidence calibration phrases, excessive structure +- New "Rhythm and uniformity" section — checks for sentence length uniformity, paragraph length uniformity, missing first-person perspective, and read-aloud test guidance +- New "When to rewrite from scratch vs. patch" threshold — advises full rewrites when AI density is too high for patching +- 5 rewrite principles in tone calibration section (vary length, be concrete, have a voice, cut neutrality, earn emphasis) +- New "Meta Patterns" group in README pattern table +- Expanded credits: OpenClaw humanizer ecosystem (community patterns) + +### Changed +- Pattern count: 23 → 30 categories +- `README.md` — updated pattern count, added Meta Patterns table, expanded credits with source descriptions +- Communication Patterns table in README now includes all communication patterns + +--- + +## [2.0.0] — 2026-03-18 + +### Added +- **Tiered vocabulary system** — words are now organized into three tiers based on AI-signal strength: + - Tier 1 (always flag): 53 entries — dead giveaways that appear 5–20x more often in AI text + - Tier 2 (flag in clusters): 38 entries — legitimate words that signal AI when 2+ appear in the same paragraph + - Tier 3 (flag by density): 11 entries — common words that only flag when the text is saturated with them +- 39 new vocabulary entries across all tiers, including: bustling, intricate, complexities, ever-evolving, daunting, holistic, actionable, impactful, learnings, thought leadership, best practices, synergy, interplay, encompass, catalyze, reimagine, galvanize, augment, cultivate, illuminate, elucidate, juxtapose, paradigm-shifting, transformative, cornerstone, paramount, poised, burgeoning, nascent, quintessential, overarching, underpinning, significant, innovative, dynamic, scalable, compelling, unprecedented, sophisticated, instrumental, world-class +- Credit to [brandonwise/humanizer](https://github.com/brandonwise/humanizer) for tiered vocabulary research + +### Changed +- Word/phrase table reorganized from flat list to tiered structure with usage guidance +- Total vocabulary: 58 → 102 entries (53 Tier 1 + 38 Tier 2 + 11 Tier 3) +- `README.md` — updated replacement table description, pattern table, and credits + +--- + +## [1.4.0] — 2026-03-17 + +### Added +- 15 new word/phrase replacements: nuanced, crucial, multifaceted, ecosystem, myriad, plethora, deep dive/dive into, unpack, bolster, spearhead, resonate, revolutionize, facilitate, underpin +- New pattern category: "let's" constructions (false-collaborative openers like "let's explore," "let's break this down") +- Skill now covers 23 pattern categories with 58 word/phrase replacements + +### Changed +- Deduplicated filler phrases that appeared in both the word table and the filler section +- `README.md` — updated pattern count (22 → 23), replacement table count (43 → 58), added "let's" constructions row to pattern table + +--- + +## [1.3.0] — 2026-03-17 + +### Changed +- Em dash detection now catches double-hyphen (`--`) in addition to Unicode em dash (`—`) +- `README.md` — updated formatting pattern description to mention `--` + +--- + +## [1.2.0] — 2026-03-06 + +### Added +- New pattern category: emotional flatline (AI claims emotions as structural crutch without conveying them; also flags lazy human writing) +- Skill now covers 22 pattern categories with 43 word/phrase replacements + +--- + +## [1.1.0] — 2026-03-06 + +### Added +- 8 new pattern categories: notability name-dropping, superficial -ing analyses, promotional language, formulaic challenges, false ranges, inline-header lists, title case headings, cutoff disclaimers +- 5 new word table entries (nestled, vibrant, thriving, despite challenges, showcasing) +- Skill now covers 21 pattern categories with 43 word/phrase replacements + +### Changed +- `README.md` — expanded full example (6 paragraphs → 4 clean sentences, 40+ tells flagged); added per-pattern before/after table organized into Content, Language, Structure, Communication groups; updated pattern count and replacement table count throughout + +--- + +## [1.0.0] — 2026-03-05 + +### Added +- `SKILL.md` — Claude Code skill with 13 pattern categories: formatting, sentence structure, word/phrase replacements (38 entries), template phrases, transition phrases, structural issues, significance inflation, copula avoidance, synonym cycling, vague attributions, filler phrases, generic conclusions, chatbot artifacts +- Four-section output format: issues found, rewritten version, what changed, second-pass audit +- `README.md` — installation guide (3 methods), full pattern reference, usage examples +- `LICENSE` — MIT +- `.gitignore` — OS/editor exclusions diff --git a/skills/avoid-ai-writing/CLAUDE.md b/skills/avoid-ai-writing/CLAUDE.md new file mode 100644 index 0000000..f2b498b --- /dev/null +++ b/skills/avoid-ai-writing/CLAUDE.md @@ -0,0 +1,44 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## What this is + +A single-file writing skill (`SKILL.md`) that audits and rewrites content to remove AI writing patterns. No build system, no dependencies, no tests — the skill is a markdown file consumed by AI coding assistants. + +## Repository structure + +- `SKILL.md` — the skill itself (v3.2.0). This is the product. All rules, tiers, profiles, and output format live here. +- `README.md` — public-facing docs, installation instructions, pattern reference table, full before/after example. +- `CHANGELOG.md` — version history with what changed and why. + +## How to make changes + +Edit `SKILL.md` directly. There's nothing to build or test. When making changes: + +- Bump the version in the SKILL.md frontmatter (`version: X.Y.Z`) +- Add a dated entry to CHANGELOG.md +- Update README.md if the change affects installation, usage, feature list, or pattern count +- Keep the README pattern count table (currently "36 Patterns Detected") in sync with actual SKILL.md categories + +## Architecture of the skill + +The skill has two modes (`rewrite` default, `detect` flag-only) and processes text through this pipeline: + +1. **Context profile detection** — auto-detects or accepts a profile hint (linkedin, blog, technical-blog, investor-email, docs, casual) that adjusts rule strictness via the tolerance matrix +2. **Pattern matching** — 36 categories across content, language, structure, communication, and meta patterns +3. **Vocabulary flagging** — 3-tier system: Tier 1 (always flag), Tier 2 (flag in clusters), Tier 3 (flag at high density) +4. **Severity classification** — P0 (credibility killers), P1 (obvious AI smell), P2 (stylistic polish) +5. **Output** — rewrite mode: 4 sections including a second-pass audit; detect mode: 2 sections with problem vs. judgment-call assessment + +## Key constraints + +- The skill must remain a single `SKILL.md` file with agentskills.io-compatible frontmatter +- Word replacement table entries need specific alternatives, not just "rephrase" +- The self-reference escape hatch (quoted examples exempt from flagging) must be preserved — without it the skill flags its own documentation +- Technical-blog profile has explicit word table exceptions (e.g., "robust" and "ecosystem" are legitimate in technical contexts) +- "Extra strict" and "skip" in the tolerance matrix have specific meanings defined in the file + +## Compatibility + +The skill works with Claude Code, OpenClaw/ClawHub, and any agentskills.io-compatible agent. The frontmatter includes both `agentskills_spec` and `openclaw` fields. Changes must not break either format. diff --git a/skills/avoid-ai-writing/LICENSE b/skills/avoid-ai-writing/LICENSE new file mode 100644 index 0000000..2fbcd55 --- /dev/null +++ b/skills/avoid-ai-writing/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Conor Bronsdon + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/skills/avoid-ai-writing/SKILL.md b/skills/avoid-ai-writing/SKILL.md new file mode 100644 index 0000000..36e4a24 --- /dev/null +++ b/skills/avoid-ai-writing/SKILL.md @@ -0,0 +1,480 @@ +--- +name: avoid-ai-writing +description: Audit and rewrite content to remove AI writing patterns ("AI-isms"). Use this skill when asked to "remove AI-isms," "clean up AI writing," "edit writing for AI patterns," "audit writing for AI tells," or "make this sound less like AI." Supports a detection-only mode that flags patterns without rewriting. +version: 3.3.1 +license: MIT +compatibility: Any AI coding assistant that supports agentskills.io SKILL.md format (Claude Code, Cursor, VS Code Copilot, Hermes Agent, OpenHands, etc.) or OpenClaw. No external tools or APIs required. +metadata: + author: Conor Bronsdon + tags: writing editing voice quality + agentskills_spec: "1.0" + openclaw: + emoji: "\u270D\uFE0F" +--- + +# Avoid AI Writing — Audit & Rewrite + +You are editing content to remove AI writing patterns ("AI-isms") that make text sound machine-generated. + +## Modes + +This skill operates in one of two modes: + +**`rewrite`** (default) — Flag AI-isms and rewrite the text to fix them. + +**`detect`** — Flag AI-isms only. No rewriting. Use this mode when: +- The writer wants to see what's flagged and decide what to fix themselves +- The flagged patterns might be intentional (AI patterns aren't always bad — they can be effective in small doses) +- You're auditing text you don't want altered (published content, someone else's writing, reference material) +- You want a quick scan without waiting for a full rewrite + +Trigger detect mode when the user says "detect," "flag only," "audit only," "just flag," "scan," "what AI patterns are in this," or similar. Default to rewrite mode if not specified. + +--- + +In **rewrite** mode, your job is to: + +1. **Audit it**: identify every AI-ism present, citing the specific text +2. **Rewrite it**: return a clean version with all AI-isms removed +3. **Show a diff summary**: briefly list what you changed and why + +In **detect** mode, your job is to: + +1. **Audit it**: identify every AI-ism present, citing the specific text +2. **Assess it**: note which flags are clear problems vs. patterns that may be intentional or effective in context + +--- + +## What to remove or fix + +### Formatting +- **Em dashes (— and --)**: Replace with commas, periods, parentheses, or rewrite as two sentences. Target: zero. Hard max: one per 1,000 words. This applies to headings and section titles too, not just body prose. Catch both the Unicode em dash (—) and the double-hyphen substitute (--). +- **Bold overuse**: Strip bold from most phrases. One bolded phrase per major section at most, or none. If something's important enough to bold, restructure the sentence to lead with it instead. +- **Emoji in headers**: Remove entirely. No `## 🚀 What This Means`. Exception: social posts may use one or two emoji sparingly — at the end of a line, never mid-sentence. +- **Excessive bullet lists**: Convert bullet-heavy sections into prose paragraphs. Bullets only for genuinely list-like content (feature comparisons, step-by-step instructions, API parameters). + +### Sentence structure +- **"It's not X — it's Y" / "This isn't about X, it's about Y"**: Rewrite as a direct positive statement. Max one per piece, and only if it serves the argument. +- **Hollow intensifiers**: Cut `genuine`, `real` (as in "a real improvement"), `truly`, `quite frankly`, `to be honest`, `let's be clear`, `it's worth noting that`. Just state the fact. +- **Vague endorsement ("worth [verb]ing")**: Cut or replace `worth reading`, `worth paying attention to`, `worth a look`, `worth exploring`, `worth checking out`, `worth your time`. These substitute a generic thumbs-up for a specific reason. Say *why* something matters instead. +- **Hedging**: Cut `perhaps`, `could potentially`, `it's important to note that`, `to be clear`. Make the point directly. +- **Missing bridge sentences**: Each paragraph should connect to the last. If paragraphs could be rearranged without the reader noticing, add connective tissue. +- **Compulsive rule of three**: Vary groupings. Use two items, four items, or a full sentence instead of triads. Max one "adjective, adjective, and adjective" pattern per piece. + +### Words and phrases to replace + +Words are organized into three tiers based on how reliably they signal AI-generated text. This tiered approach — adapted from [brandonwise/humanizer](https://github.com/brandonwise/humanizer)'s vocabulary research — reduces false positives on words that are fine in isolation but suspicious in clusters. + +- **Tier 1 — Always flag.** These words appear 5–20x more often in AI text than human text. Replace on sight. +- **Tier 2 — Flag in clusters.** Individually fine, but two or more in the same paragraph is a strong AI signal. Flag when they appear together. +- **Tier 3 — Flag by density.** Common words that AI simply overuses. Only flag when they make up a noticeable fraction of the text (roughly 3%+ of total words). + +#### Tier 1 — Always replace + +| Replace | With | +|---|---| +| delve / delve into | explore, dig into, look at | +| landscape (metaphor) | field, space, industry, world | +| tapestry | (describe the actual complexity) | +| realm | area, field, domain | +| paradigm | model, approach, framework | +| embark | start, begin | +| beacon | (rewrite entirely) | +| testament to | shows, proves, demonstrates | +| robust | strong, reliable, solid | +| comprehensive | thorough, complete, full | +| cutting-edge | latest, newest, advanced | +| leverage (verb) | use | +| pivotal | important, key, critical | +| underscores | highlights, shows | +| meticulous / meticulously | careful, detailed, precise | +| seamless / seamlessly | smooth, easy, without friction | +| game-changer / game-changing | describe what specifically changed and why it matters | +| hit differently / hits different | (say what specifically changed, or cut) | +| utilize | use | +| watershed moment | turning point, shift (or describe what changed) | +| marking a pivotal moment | (state what happened) | +| the future looks bright | (cut — say something specific or nothing) | +| only time will tell | (cut — say something specific or nothing) | +| nestled | is located, sits, is in | +| vibrant | (describe what makes it active, or cut) | +| thriving | growing, active (or cite a number) | +| despite challenges… continues to thrive | (name the challenge and the response, or cut) | +| showcasing | showing, demonstrating (or cut the clause) | +| deep dive / dive into | look at, examine, explore | +| unpack / unpacking | explain, break down, walk through | +| bustling | busy, active (or cite what makes it busy) | +| intricate / intricacies | complex, detailed (or name the specific complexity) | +| complexities | (name the actual complexities, or use "problems" / "details") | +| ever-evolving | changing, growing (or describe how) | +| enduring | lasting, long-running (or cite how long) | +| daunting | hard, difficult, challenging | +| holistic / holistically | complete, full, whole (or describe what's included) | +| actionable | practical, useful, concrete | +| impactful | effective, significant (or describe the impact) | +| learnings | lessons, findings, takeaways | +| thought leader / thought leadership | expert, authority (or describe their actual contribution) | +| best practices | what works, proven methods, standard approach | +| at its core | (cut — just state the thing) | +| synergy / synergies | (describe the actual combined effect) | +| interplay | relationship, connection, interaction | +| in order to | to | +| due to the fact that | because | +| serves as | is | +| features (verb) | has, includes | +| boasts | has | +| presents (inflated) | is, shows, gives | +| commence | start, begin | +| ascertain | find out, determine, learn | +| endeavor | effort, attempt, try | +| keen (as intensifier) | interested, eager, enthusiastic (or cut — just state the interest) | +| symphony (metaphor) | (describe the actual coordination or combination) | +| embrace (metaphor) | adopt, accept, use, switch to | + +#### Tier 2 — Flag when 2+ appear in the same paragraph + +These words are legitimate on their own. When two or more show up together, the paragraph likely needs a rewrite. + +| Replace | With | +|---|---| +| harness | use, take advantage of | +| navigate / navigating | work through, handle, deal with | +| foster | encourage, support, build | +| elevate | improve, raise, strengthen | +| unleash | release, enable, unlock | +| streamline | simplify, speed up | +| empower | enable, let, allow | +| bolster | support, strengthen, back up | +| spearhead | lead, drive, run | +| resonate / resonates with | connect with, appeal to, matter to | +| revolutionize | change, transform, reshape (or describe what changed) | +| facilitate / facilitates | enable, help, allow, run | +| underpin | support, form the basis of | +| nuanced | specific, subtle, detailed (or name the actual nuance) | +| crucial | important, key, necessary | +| multifaceted | (describe the actual facets, or cut) | +| ecosystem (metaphor) | system, community, network, market | +| myriad | many, numerous (or give a number) | +| plethora | many, a lot of (or give a number) | +| encompass | include, cover, span | +| catalyze | start, trigger, accelerate | +| reimagine | rethink, redesign, rebuild | +| galvanize | motivate, rally, push | +| augment | add to, expand, supplement | +| cultivate | build, develop, grow | +| illuminate | clarify, explain, show | +| elucidate | explain, clarify, spell out | +| juxtapose | compare, contrast, set side by side | +| paradigm-shifting | (describe what actually shifted) | +| transformative / transformation | (describe what changed and how) | +| cornerstone | foundation, basis, key part | +| paramount | most important, top priority | +| poised (to) | ready, set, about to | +| burgeoning | growing, emerging (or cite a number) | +| nascent | new, early-stage, emerging | +| quintessential | typical, classic, defining | +| overarching | main, central, broad | +| underpinning / underpinnings | basis, foundation, what supports | + +#### Tier 3 — Flag only at high density + +These are normal words. Only flag them when the text is saturated with them — a sign that AI filled space with vague praise instead of specifics. + +| Word | What to do | +|---|---| +| significant / significantly | Replace some with specifics: numbers, comparisons, examples | +| innovative / innovation | Describe what's actually new | +| effective / effectively | Say how or cite a metric | +| dynamic / dynamics | Name the actual forces or changes | +| scalable / scalability | Describe what scales and to what | +| compelling | Say why it compels | +| unprecedented | Name the precedent it breaks (or cut) | +| exceptional / exceptionally | Cite what makes it an exception | +| remarkable / remarkably | Say what's worth remarking on | +| sophisticated | Describe the sophistication | +| instrumental | Say what role it played | +| world-class / state-of-the-art / best-in-class | Cite a benchmark or comparison | + +### Template phrases (avoid) + +These slot-fill constructions signal that a sentence was generated, not written. If a phrase has a blank where a noun or adjective could go and still sound the same, it's too generic. + +- "a [adjective] step towards [adjective] AI infrastructure" → describe the specific capability, benchmark, or outcome +- "a [adjective] step forward for [noun]" → same rule: say what actually changed +- "Whether you're [X] or [Y]" → false-breadth construction. Pick the audience you're actually addressing, or cut. "Whether you're a startup founder or an enterprise architect" means nothing — it's just "everyone." +- "I recently had the pleasure of [verb]-ing" → review/social AI pattern. Just say what happened: "I talked to," "I read," "I attended." + +### Transition phrases to remove or rewrite +- "Moreover" / "Furthermore" / "Additionally" → restructure so the connection is obvious, or use "and," "also," "on top of that" +- "In today's [X]" / "In an era where" → cut or state specific context +- "It's worth noting that" / "Notably" → just state the fact +- "Here's what's interesting" / "Here's what caught my eye" / "Here's what stood out" → reader-steering frames. Let the content signal its own importance. If you need a lead-in, make it specific: "The revenue number matters because..." not "Here's the interesting part." +- "In conclusion" / "In summary" / "To summarize" → your conclusion should be obvious +- "When it comes to" → just talk about the thing directly +- "At the end of the day" → cut +- "That said" / "That being said" → cut or use "but," "yet," or "however." Don't overuse any one of them. + +### Structural issues +- **Uniform paragraph length**: Vary deliberately. Include some 1-2 sentence paragraphs and some longer ones. If every paragraph is roughly the same size, fix it. +- **Formulaic openings**: If the piece opens with broad context before getting to the point ("In the rapidly evolving world of..."), rewrite to lead with the news or the insight. Context can come second. +- **Suspiciously clean grammar**: Don't sand away all personality. Deliberate fragments, sentences starting with "And" or "But," comma splices for effect: if the natural voice uses them, keep them. + +### Significance inflation +- Phrases like "marking a pivotal moment in the evolution of..." or "a watershed moment for the industry" inflate routine events into history-making ones. State what happened and let the reader judge significance. +- If the sentence still works after you delete the inflation clause, delete it. + +### Copula avoidance +- AI text avoids "is" and "has" by substituting fancier verbs: "serves as," "features," "boasts," "presents," "represents." These sound like a press release. +- Default to "is" or "has" unless a more specific verb genuinely adds meaning. + +### Synonym cycling +- AI rotates synonyms to avoid repeating a word: "developers… engineers… practitioners… builders" in the same paragraph. Human writers repeat the clearest word. +- If the same noun or verb appears three times in a paragraph and that's the right word, keep all three. Forced variation reads as thesaurus abuse. + +### Vague attributions +- "Experts believe," "Studies show," "Research suggests," "Industry leaders agree" — without naming the expert, study, or leader. Either cite a specific source or drop the attribution and state the claim directly. + +### Filler phrases +- Strip mechanical padding that adds words without meaning: + - "It is important to note that" → (just state it) + - "In terms of" → (rewrite) + - "The reality is that" → (cut or just state the claim) +- Note: "In order to," "Due to the fact that," and "At the end of the day" are covered in the word/phrase table and transition sections above — don't duplicate rules. + +### Generic conclusions +- "The future looks bright," "Only time will tell," "One thing is certain," "As we move forward" — these are filler disguised as conclusions. Cut them. If the piece needs a closing thought, make it specific to the argument. + +### Chatbot artifacts +- "I hope this helps!", "Certainly!", "Absolutely!", "Great question!", "Feel free to reach out," "Let me know if you need anything else" — these are conversational tics from chat interfaces, not writing. Remove entirely. +- Also watch for: "In this article, we will explore…" or "Let's dive in!" — these are AI-generated meta-narration. Cut or rewrite with a direct opening. + +### "Let's" constructions +- "Let's explore," "Let's take a look," "Let's break this down," "Let's examine" — AI uses "let's" as a false-collaborative opener to ease into a topic. It's filler that delays the actual point. Just start with the point. "Let's dive in" is covered above under chatbot artifacts, but the pattern is broader than that — flag any "let's + verb" that's functioning as a transition rather than a genuine invitation to act. + +### Notability name-dropping +- AI text piles on prestigious citations to manufacture credibility: "cited in The New York Times, BBC, Financial Times, and The Hindu." If a source matters, use it with context: "In a 2024 NYT interview, she argued..." One specific reference beats four name-drops. + +### Superficial -ing analyses +- Strings of present participles used as pseudo-analysis: "symbolizing the region's commitment to progress, reflecting decades of investment, and showcasing a new era of collaboration." These say nothing. Replace with specific facts or cut entirely. + +### Promotional language +- AI defaults to tourism-brochure prose: "nestled within the breathtaking foothills," "a vibrant hub of innovation," "a thriving ecosystem." Replace with plain description: "is a town in the Gonder region," "has 12 startups." If you wouldn't say it in conversation, cut it. + +### Formulaic challenges +- "Despite challenges, [subject] continues to thrive" or "While facing headwinds, the organization remains resilient." This is a non-statement. Name the actual challenge and the actual response, or cut the sentence. + +### False ranges +- AI creates false breadth by pairing unrelated extremes: "from the Big Bang to dark matter," "from ancient civilizations to modern startups." These sound sweeping but say nothing. List the actual topics or pick the one that matters. + +### Inline-header lists +- Bullet lists where each item starts with a bold header that repeats itself: "**Performance:** Performance improved by..." Strip the bold header and write the point directly. If the list items need headers, they should probably be paragraphs. + +### Title case headings +- AI over-capitalizes headings: "Strategic Negotiations And Key Partnerships" instead of "Strategic negotiations and key partnerships." Use sentence case for subheadings. Title case only for the piece's main title, if at all. + +### Cutoff disclaimers +- "While specific details are limited based on available information," "As of my last update," "I don't have access to real-time data." These are model limitations leaking into prose. Either find the information or remove the hedge. Never publish a sentence that admits the writer didn't look something up. + +### Novelty inflation +- AI text treats established concepts as if the speaker invented or discovered them: "He introduced a term," "She coined the phrase," "a concept nobody's naming," "a failure mode nobody talks about." In reality, most ideas in a conversation are applications of existing concepts, not inventions. +- Two problems. First, it's factually risky: if the concept already has a Wikipedia page or conference talks from last year, claiming novelty makes the writer look uninformed. Second, it flatters the subject in a way that reads as promotional rather than analytical. +- The fix: describe what the person *did with* the concept, not that they discovered it. "Michel walked through how context poisoning works in practice" instead of "Michel introduced a term I hadn't heard before: context poisoning." If you're unsure whether something is novel, assume it isn't and frame accordingly. +- Related patterns to flag: "the failure mode nobody's naming," "a problem nobody talks about," "the insight everyone's missing," "what nobody tells you about." These are engagement-bait framings that claim scarcity of knowledge where none exists. + +### Emotional flatline +- AI claims emotions as a structural crutch without conveying them through the writing: "What surprised me most," "I was fascinated to discover," "What struck me was," "I was excited to learn," "The most interesting part." +- Two problems. First, it's tell-don't-show: if the thing is genuinely surprising, the reader should feel that from the content, not from the writer announcing it. Second, these phrases are massively overused as list introductions and transitions. They're filler wearing an emotion costume. +- This pattern isn't always AI. It's also a sign of lazy human writing on autopilot. Flag it either way. +- The fix isn't "never say surprised." It's: if you claim an emotion, the writing around it should earn it. Otherwise cut the claim and present the thing directly. +- Related pattern: "hit differently" / "hits different." AI uses trendy colloquialisms as a shortcut to sound relatable without earning the emotional beat. If something genuinely affected you, describe how. Otherwise cut. + +### False concession structure +- "While X is impressive, Y remains a challenge" or "Although X has made strides, Y is still an open question." AI uses this to sound balanced without actually weighing anything. Both halves are vague. Either make the concession specific (name what's impressive, name the actual challenge) or pick a side and argue it. + +### Rhetorical question openers +- "But what does this mean for developers?" / "So why should you care?" / "What's next?" � AI uses rhetorical questions to stall before the actual point. If you know the answer, just say it. Rhetorical questions are earned by strong setup, not dropped as section transitions. + +### Parenthetical hedging +- "(and, increasingly, Z)" / "(or, more precisely, Y)" / "(and perhaps more importantly, W)" � AI inserts parenthetical asides to sound nuanced without committing. If the aside matters, give it its own sentence. If it doesn't, cut it. + +### Numbered list inflation +- "Three key takeaways" / "Five things to know" / "Here are the top seven" � AI defaults to numbered lists because they're structurally safe. Only use numbered lists when the content genuinely has that many discrete, parallel items. If you're padding to hit a number, the list shouldn't exist. + +### Reasoning chain artifacts +- "Let me think step by step," "Breaking this down," "To approach this systematically," "Step 1:," "Here's my thought process," "First, let's consider," "Working through this logically" — these are artifacts of chain-of-thought reasoning leaking into published prose. The reader doesn't need to see the scaffolding. State the conclusion, then the evidence. +- Also watch for numbered reasoning steps that read like an internal monologue rather than an argument meant for an audience. + +### Sycophantic tone +- "Great question!", "Excellent point!", "You're absolutely right!", "That's a really insightful observation" — these are conversational rewards from chat interfaces, not writing. Remove entirely. +- Distinct from chatbot artifacts: sycophancy specifically validates the reader/questioner rather than just performing helpfulness. + +### Acknowledgment loops +- "You're asking about," "The question of whether," "To answer your question," "That's a great question. The..." — AI restates the prompt before answering. In writing, this is pure filler. The reader knows what they asked. Just answer. +- Related pattern: opening a section by summarizing what the previous section said. If the structure is clear, the reader doesn't need a recap. + +### Confidence calibration phrases +- "It's worth noting that," "Interestingly," "Surprisingly," "Importantly," "Significantly," "Notably," "Certainly," "Undoubtedly," "Without a doubt" — AI uses these to signal how the reader should feel about a fact instead of letting the fact speak for itself. +- "Here's what's interesting," "Here's the interesting part," "Here are the parts I found interesting" — reader-steering cue that pre-interprets importance. Works when followed by genuinely surprising data; fails when it introduces a restatement of something obvious (which is the AI default). +- One "notably" in a 2,000-word piece is fine. Three in 500 words is AI-style emphasis stacking. Flag by density. + +### Excessive structure +- Too many headers in short text: more than 3 headings in under 300 words is almost always AI trying to look organized. Merge sections or use prose transitions instead. +- Too many list items: 8+ bullet points in under 200 words means the content should be a paragraph, not a list. +- Formulaic section headers: "Overview," "Key Points," "Summary," "Conclusion," "Introduction" — these are default AI scaffolding. Use headers that tell the reader something specific about what follows. + +### Rhythm and uniformity + +These aren't individual word or phrase problems — they're patterns in how the text flows as a whole. AI text is metronomic; human text has varied rhythm. + +**Structure is the #1 detection signal.** AI detection tools (including Pangram, which trains a classifier on 28M human documents) weight structural regularity higher than vocabulary. Consistent sentence construction, uniform pacing, and symmetrical phrasing patterns are harder to mask than swapping out a few flagged words. If you fix every word on the Tier 1 list but leave the rhythm untouched, the text still reads as AI-generated. + +- **Sentence length uniformity**: If most sentences are 15–25 words, the text sounds robotic. Mix short punchy sentences (3–8 words) with longer flowing ones (20+). Fragments work. Questions break the monotony. +- **Paragraph length uniformity**: If every paragraph is 3–5 sentences and roughly the same size, vary deliberately. Some paragraphs should be one sentence. Some should be longer. +- **Vocabulary repetition vs. synonym cycling**: AI either repeats the same word mechanically or cycles through synonyms conspicuously. Human writers repeat when the word is right and vary when it's natural — there's no formula. +- **Read-aloud test**: If the text sounds like it could be read by a text-to-speech engine without sounding weird, it's probably too uniform. Human writing has rhythm that resists robotic delivery. +- **Missing first-person perspective**: Where appropriate, the writer should have opinions, preferences, and reactions. AI is relentlessly neutral. If the piece is supposed to have a voice, the absence of "I think," "in my experience," or a stated preference is itself an AI tell. +- **Over-polishing**: Aggressively editing out every irregularity can push human writing *toward* AI statistical profiles. Natural disfluency, idiosyncratic word choices, and uneven pacing are what keep text out of the "AI-generated" classification. Don't sand away all personality in pursuit of clean prose. This skill should make writing sound more human, not less — if you apply every rule at maximum strictness, you risk creating the very uniformity you're trying to avoid. + +### When to rewrite from scratch vs. patch + +If the text has 5+ flagged vocabulary hits across multiple categories, 3+ distinct pattern categories triggered, and uniform sentence/paragraph length, patching individual phrases won't fix it — the structure itself is AI-generated. Advise a full rewrite: state the core point in one sentence, then rebuild from there. + +--- + +## Severity tiers + +Not all AI-isms are equal. When doing a quick pass or triaging a large document, prioritize by tier: + +### P0 � Credibility killers (fix immediately) +- Cutoff disclaimers ("As of my last update") +- Chatbot artifacts ("I hope this helps!", "Great question!") +- Vague attributions without sources ("Experts believe") +- Significance inflation on routine events + +### P1 � Obvious AI smell (fix before publishing) +- Word-list violations (delve, leverage, harness, robust, etc.) +- Template phrases and slot-fill constructions +- "Let's" transition openers +- Synonym cycling within a paragraph +- Formulaic openings ("In the rapidly evolving world of...") +- Bold overuse +- Em dash frequency (above 1 per 1,000 words) + +### P2 � Stylistic polish (fix when time allows) +- Generic conclusions ("The future looks bright") +- Compulsive rule of three +- Uniform paragraph length +- Copula avoidance (serves as, features, boasts) +- Transition phrases (Moreover, Furthermore, Additionally) + +Use P0+P1 for quick passes. Full audit covers all three tiers. + +--- + +## Self-reference escape hatch + +When writing *about* AI writing patterns (blog posts, tutorials, skill documentation like this file), quoted examples are exempt from flagging. Text inside quotation marks, code blocks, or explicitly marked as illustrative ("for example, AI might write...") should not be rewritten. Only flag patterns that appear in the author's own prose, not in cited examples of bad writing. + +--- + +## Context profiles + +Pass an optional context hint to adjust rule strictness. If no context is specified, auto-detect from content cues (short + hashtags = social, code blocks = technical, salutation = email, default = blog). + +### Profile definitions + +**`linkedin`** � Short-form social. Punchy fragments, visual formatting matter. +**`blog`** � Default. Standard long-form prose. All rules apply at full strength. +**`technical-blog`** � Long-form with code, architecture, APIs. Technical terms get a pass. +**`investor-email`** � High-trust audience. Tighten everything; promotional language is the biggest risk. +**`docs`** � Documentation, READMEs, guides. Clarity over voice. +**`casual`** � Slack messages, internal notes, quick replies. Only catch the worst offenders. + +### Tolerance matrix + +Rules not listed in the table apply at full strength across all profiles. + +| Rule | linkedin | blog | technical-blog | investor-email | docs | casual | +|------|----------|------|----------------|----------------|------|--------| +| Em dashes | relaxed (2/post OK) | strict | strict | strict | relaxed | skip | +| Bold overuse | relaxed (bold hooks OK) | strict | strict | strict | relaxed | skip | +| Emoji in headers | relaxed (1-2 end-of-line OK) | strict | strict | strict | skip | skip | +| Excessive bullets | skip (lists work on LinkedIn) | strict | relaxed (technical lists OK) | strict | skip (lists are docs) | skip | +| Hedging | strict | strict | relaxed ("may" is accurate in technical) | strict | relaxed | skip | +| Word table (full list) | strict | strict | **partial** (see below) | strict | relaxed | P0 only | +| Promotional language | relaxed (some sell is expected) | strict | strict | **extra strict** | strict | skip | +| Significance inflation | strict | strict | strict | **extra strict** | relaxed | skip | +| Copula avoidance | skip | strict | relaxed | strict | skip | skip | +| Uniform paragraph length | skip (short-form) | strict | strict | strict | relaxed | skip | +| Numbered list inflation | relaxed | strict | relaxed | strict | skip | skip | +| Rhetorical questions | relaxed (1 as hook OK) | strict | strict | strict | strict | skip | +| Transition phrases | skip (short-form) | strict | strict | strict | relaxed | skip | +| Generic conclusions | skip | strict | strict | **extra strict** | skip | skip | + +**Technical-blog word table exceptions:** These terms have legitimate technical meaning and should not be flagged in technical context: `robust`, `comprehensive`, `seamless`, `ecosystem`, `leverage` (when discussing actual platform leverage/APIs), `facilitate`, `underpin`, `streamline`. Still flag: `delve`, `tapestry`, `beacon`, `embark`, `testament to`, `game-changer`, `harness`. + +**"Extra strict"** means: flag even borderline instances. In investor emails, a single "thriving ecosystem" can undermine the whole message. + +**"Skip"** means: don't audit this category for this profile. The rule doesn't apply or isn't worth the edit. + +### Auto-detection cues + +When no context is specified, infer from these signals: + +| Signal | Inferred context | +|--------|-----------------| +| Under 300 words + hashtags or mentions | `linkedin` | +| Code blocks, API references, or technical architecture | `technical-blog` | +| Salutation ("Hi [name]", "Dear") + investor/fundraising language | `investor-email` | +| Step-by-step instructions, parameter docs, README structure | `docs` | +| No strong signals | `blog` (safest default � all rules apply) | + +If auto-detection feels wrong, say which profile you're using and why. The user can override. + +--- + + +## Output format + +### Rewrite mode (default) + +Return your response in four sections: + +**1. Issues found** +A bulleted list of every AI-ism identified, with the offending text quoted. + +**2. Rewritten version** +The full rewritten content. Preserve the original structure, intent, and all specific technical details. Only change what the guidelines require. + +**3. What changed** +A brief summary of the major edits made. Not every word, just the meaningful changes. + +**4. Second-pass audit** +Re-read the rewritten version from section 2. Identify any remaining AI tells that survived the first pass — recycled transitions, lingering inflation, copula avoidance, filler phrases, or anything else from the categories above. Fix them, return the corrected text inline, and note what changed in this pass. If the rewrite is clean, say so. + +### Detect mode + +Return your response in two sections: + +**1. Issues found** +A bulleted list of every AI-ism identified, with the offending text quoted. Group by severity (P0, P1, P2). + +**2. Assessment** +For each flag, note whether it's a clear problem or a judgment call. Some AI-associated patterns are effective writing techniques — uniform paragraph length is a problem, but a well-placed "however" isn't. Call out which flags the writer should definitely fix vs. which ones are worth a second look but might be fine in context. If the text is clean, say so. + +--- + +## Tone calibration + +The goal is writing that sounds like a person wrote it. Direct. Specific. The writing should demonstrate confidence, not assert it. + +Five principles for human-sounding rewrites: +1. **Vary sentence length** — mix short with long. Fragments are fine. +2. **Be concrete** — replace vague claims with numbers, names, dates, or examples. +3. **Have a voice** — where appropriate, use first person, state preferences, show reactions. +4. **Cut the neutrality** — humans have opinions. If the piece is supposed to take a position, take it. +5. **Earn your emphasis** — don't tell the reader something is interesting. Make it interesting. + +If the original writing is already strong, say so and make only the necessary cuts. Don't over-edit for the sake of it. + +The replacement table provides defaults, not mandates. If a flagged word is clearly the right choice in context, preserve it. diff --git a/skills/avoid-ai-writing/UPSTREAM-README.md b/skills/avoid-ai-writing/UPSTREAM-README.md new file mode 100644 index 0000000..f69c2c8 --- /dev/null +++ b/skills/avoid-ai-writing/UPSTREAM-README.md @@ -0,0 +1,238 @@ +
+ +# avoid-ai-writing + +Audit & rewrite content to remove AI writing patterns. A practical skill for any AI agent. Supports detection-only mode. + +[![GitHub stars](https://img.shields.io/github/stars/conorbronsdon/avoid-ai-writing?style=social)](https://github.com/conorbronsdon/avoid-ai-writing/stargazers) +[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE) +[![X](https://img.shields.io/badge/X-@ConorBronsdon-black?style=flat-square&logo=x)](https://x.com/ConorBronsdon) +[![Web App](https://img.shields.io/badge/Try_the_web_app-ff6b35?style=flat-square&logo=vercel&logoColor=white)](https://avoid-ai-writing-app.vercel.app) + +
+
+The community made a meme coin to support the project🤯 CA: BsidWuYJnayqMXVsLGr34524vmZ1BrWFhPer3198pump +
+ +--- + + +A portable writing skill for [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [OpenClaw](https://github.com/openclaw/openclaw), [Hermes](https://github.com/NousResearch/hermes-agent), and any other [agentskills.io](https://agentskills.io)-compatible agent. Audits and rewrites content to remove AI writing patterns ("AI-isms"). + +**Two modes:** +- **Rewrite** (default) — flags AI patterns and rewrites the text to fix them. A built-in second pass catches patterns that survived the first edit. +- **Detect** — flags AI patterns without rewriting. Shows which flags are real problems vs. judgment calls. Useful when patterns might be intentional, when auditing content you don't want altered, or when you just want a quick scan. + +## Quick demo + +**Input:** +> Certainly! Acme Analytics, a vibrant startup nestled in the heart of Boulder's thriving tech ecosystem, has secured $40M in Series B funding — marking a watershed moment for the observability landscape. The platform serves as a unified hub, featuring real-time dashboards, boasting sub-second queries, and presenting a seamless integration layer. Moreover, experts believe Acme is poised to disrupt the market. In conclusion, the future looks bright! + +**Output:** +> Acme Analytics raised a $40M Series B led by Sequoia. The Boulder-based startup makes an observability platform that runs queries in under a second and plugs into existing monitoring stacks without custom integration work. + +**What it caught:** chatbot opener ("Certainly!"), promotional language ("vibrant," "nestled," "thriving"), significance inflation ("watershed moment"), copula avoidance ("serves as," "featuring," "boasting"), 4 word replacements, vague attribution ("experts believe"), filler ("Moreover"), generic conclusion ("the future looks bright"), over-polished uniformity. 15+ AI tells in one paragraph. + +## Why a skill, not just a prompt + +A one-shot "make this sound human" prompt catches the obvious stuff. This skill is different: + +- **Structured audit** — returns identified issues with quoted text, the rewrite, a change summary, and a second-pass audit in four discrete sections. You see exactly what changed and why. +- **Two-pass detection** — the second pass re-reads the rewrite and catches patterns that survive the first edit: recycled transitions, lingering inflation, copula swaps that snuck through. +- **109-entry word replacement table across 3 tiers** — not vibes-based. Every flagged word has a specific, plainer alternative. "Leverage" → "use." "Commence" → "start." Tier 1 words are always flagged, Tier 2 words flag when they cluster, Tier 3 words flag only at high density. This reduces false positives while catching real AI tells. +- **36 pattern categories** — see the full list below, each with before/after examples. Includes rhythm/uniformity checks and a rewrite-vs-patch threshold. +- **Detect mode** — flag patterns without rewriting. See which flags are real problems vs. judgment calls. Useful when patterns might be intentional or you're auditing content you don't want altered. +- **Works with Claude Code and OpenClaw** — single `SKILL.md` with compatible frontmatter for both platforms. + +## Installation & Usage + +### Claude Code + +**Option 1: Clone into skills directory** + +```bash +git clone https://github.com/conorbronsdon/avoid-ai-writing ~/.claude/skills/avoid-ai-writing +``` + +**Option 2: Copy the file directly** + +Download `SKILL.md` and place it in any directory that Claude Code can read. Reference it in your `CLAUDE.md`: + +```markdown +- Editing for AI patterns → read `path/to/avoid-ai-writing/SKILL.md` +``` + +**Option 3: Use as a slash command** + +Create a command file (e.g., `~/.claude/commands/clean-ai-writing.md`): + +```markdown +--- +description: Audit and rewrite content to remove AI writing patterns +--- + +$ARGUMENTS + +Read and follow the instructions in ~/.claude/skills/avoid-ai-writing/SKILL.md +``` + +Then use `/clean-ai-writing ` in Claude Code. + +### OpenClaw + +**Option 1: [Install from ClawHub](https://clawhub.ai/conorbronsdon/avoid-ai-writing)** + +```bash +clawhub install avoid-ai-writing +``` + +**Option 2: Clone into skills directory** + +```bash +git clone https://github.com/conorbronsdon/avoid-ai-writing ~/.openclaw/skills/avoid-ai-writing +``` + +### Triggering the skill + +Once installed, ask your assistant to clean up AI writing: + +- "Remove AI-isms from this post" +- "Audit this draft for AI tells" +- "Make this sound less like AI" +- "Clean up AI writing in this paragraph" + +In **rewrite mode** (default), the skill returns four sections: + +1. **Issues found** — every AI-ism identified, with the text quoted +2. **Rewritten version** — clean version with all AI-isms removed +3. **What changed** — summary of the major edits +4. **Second-pass audit** — re-reads the rewrite and catches any surviving tells + +In **detect mode**, the skill returns two sections: + +1. **Issues found** — every AI-ism identified, grouped by severity (P0/P1/P2) +2. **Assessment** — which flags are clear problems vs. patterns that may be intentional or effective in context + +Trigger detect mode with: "detect," "flag only," "audit only," "just flag," "scan," or similar. + +## 36 Patterns Detected + +### Content Patterns + +| # | Pattern | Before | After | +|---|---------|--------|-------| +| 1 | **Significance inflation** | "marking a pivotal moment in the evolution of..." | "was founded in 2019 to solve X" | +| 2 | **Notability name-dropping** | "cited in NYT, BBC, and Wired" | "In a 2024 NYT interview, she argued..." | +| 3 | **Superficial -ing analyses** | "symbolizing... reflecting... showcasing..." | Replace with specific facts or cut | +| 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" | "according to a 2019 survey by Gartner" | +| 6 | **Formulaic challenges** | "Despite challenges... continues to thrive" | Name the challenge and the response | +| 7 | **Novelty inflation** | "He introduced a term I hadn't heard before" | "He walked through how X works in practice" | + +### Language Patterns + +| # | Pattern | Before | After | +|---|---------|--------|-------| +| 8 | **Word/phrase replacements (3 tiers)** | "leverage... robust... seamless... utilize" | "use... reliable... smooth... use" | +| 9 | **Copula avoidance** | "serves as... features... boasts" | "is... has" | +| 10 | **Synonym cycling** | "developers... engineers... practitioners... builders" | "developers" (repeat the clear word) | +| 11 | **Template phrases** | "a [adj] step towards [adj] infrastructure" | Describe the specific outcome | +| 12 | **Filler phrases** | "In order to," "Due to the fact that" | "To," "Because" | +| 13 | **False ranges** | "from the Big Bang to dark matter" | List the actual topics | +| 14 | **Parenthetical hedging** | "tools (like X and Y)" | Name them directly or cut | + +### Structure Patterns + +| # | Pattern | Before | After | +|---|---------|--------|-------| +| 15 | **Formatting** | Em dashes (— and --), bold overuse, emoji headers, bullet-heavy | Commas/periods, prose paragraphs | +| 16 | **Sentence structure** | "It's not X, it's Y" + hollow intensifiers + hedging | Direct positive statements | +| 17 | **Structural issues** | Uniform paragraphs, formulaic openings, too-clean grammar | Varied length, lead with the point | +| 18 | **Transition phrases** | "Moreover," "Furthermore," "In today's [X]" | "and," "also," or restructure | +| 19 | **Inline-header lists** | "**Speed:** Speed improved by..." | Write the point directly | +| 20 | **Title case headings** | "Strategic Negotiations And Partnerships" | "Strategic negotiations and partnerships" | +| 21 | **Numbered list inflation** | "Here are 7 reasons why..." | Cut to the 2-3 that matter | +| 22 | **False concession** | "While X has limitations, it's still remarkable" | State the real tradeoff | +| 23 | **Rhetorical question openers** | "What if there were a better way to...?" | Lead with the claim | + +### Communication Patterns + +| # | Pattern | Before | After | +|---|---------|--------|-------| +| 24 | **Chatbot artifacts** | "I hope this helps! Let me know if..." | Remove entirely | +| 25 | **"Let's" constructions** | "Let's explore," "Let's break this down" | Just start with the point | +| 26 | **Cutoff disclaimers** | "While details are limited in available sources..." | Find sources or remove | +| 27 | **Generic conclusions** | "The future looks bright," "Only time will tell" | Specific closing thought or cut | +| 28 | **Emotional flatline** | "What surprised me most," "I was fascinated to discover" | Earn the emotion or cut the claim | +| 29 | **Reasoning chain artifacts** | "Let me think step by step," "Breaking this down" | State conclusion, then evidence | +| 30 | **Sycophantic tone** | "Great question!", "You're absolutely right!" | Remove entirely | +| 31 | **Acknowledgment loops** | "You're asking about," "To answer your question" | Just answer directly | +| 32 | **Confidence calibration** | "It's worth noting," "Interestingly," "Surprisingly" | Let the fact speak for itself | + +### Meta Patterns + +| # | Pattern | Before | After | +|---|---------|--------|-------| +| 33 | **Excessive structure** | 5 headers in 200 words, "Overview:", "Key Points:" | Merge sections, use specific headers | +| 34 | **Rhythm and uniformity** | All sentences 15–25 words, all paragraphs same length | Mix short/long, fragments, questions | +| 35 | **Over-polishing** | Every irregularity sanded away, perfectly uniform prose | Keep natural disfluency, varied rhythm | +| 36 | **Rewrite-vs-patch threshold** | 5+ vocabulary flags + 3+ pattern categories + uniform rhythm | Advise full rewrite, not patching | + +## Full Example + +**Before (AI-generated):** + +> Certainly! Here's a comprehensive overview of Acme's Series B. +> +> Acme Analytics, a vibrant startup nestled in the heart of Boulder's thriving tech ecosystem, has secured $40M in Series B funding — marking a watershed moment for the company and the observability landscape at large. The round was led by Sequoia, with participation from Andreessen Horowitz, Y Combinator, and Index Ventures, underscoring the robust investor confidence in Acme's vision. +> +> The platform serves as a unified hub for engineering teams, featuring real-time dashboards, boasting sub-second query performance, and presenting a seamless integration layer. It's not just another monitoring tool — it's a paradigm shift in how organizations navigate complex distributed systems. Experts believe Acme is poised to disrupt the $15B observability market. Studies show that companies utilizing comprehensive monitoring solutions can ascertain issues 40% faster. +> +> - 🚀 **Performance:** The platform streamlines incident response, empowering engineers to resolve issues faster. +> - 💡 **Scale:** Acme fosters collaboration across teams, from frontend developers to SRE practitioners to platform builders to infrastructure engineers. +> - ✅ **Adoption:** Customer adoption continues to accelerate, reflecting broader industry trends. +> +> Moreover, Acme's approach showcases the potential of modern observability — symbolizing a shift toward proactive monitoring, reflecting years of R&D investment, and highlighting the intricate interplay between data collection and actionable intelligence. Despite challenges common in the crowded monitoring space, Acme continues to thrive. In order to fully capitalize on this momentum, the company plans to expand its go-to-market endeavors. +> +> In conclusion, the future looks bright for Acme Analytics. Only time will tell how this game-changer will reshape the observability paradigm. Feel free to reach out if you'd like more details! + +**After (cleaned up):** + +> Acme Analytics raised a $40M Series B led by Sequoia. The Boulder-based startup makes an observability platform that runs queries in under a second and plugs into existing monitoring stacks without custom integration work. +> +> The pitch is speed. Their median time-to-resolution is 12 minutes, compared to the 45-minute industry average that Datadog reported in 2024. That gap is why 380 companies are paying for it. +> +> They'll use the money to hire sales reps in EMEA and add log management. The monitoring market is crowded, but Acme's bet is that most teams still stitch together three or four tools and lose time switching between them. + +**What the skill caught:** chatbot artifacts (Certainly!, Feel free to reach out), 3 em dashes, promotional language (vibrant, nestled, thriving), significance inflation (watershed moment), copula avoidance (serves as, featuring, boasting, presenting), 10 word replacements (landscape, robust, seamless, paradigm, streamline, empower, foster, utilize, ascertain, endeavor), synonym cycling (developers/practitioners/builders/engineers), negative parallelism (It's not just X, it's Y), notability name-dropping (Sequoia, a16z, YC, Index stacked for credibility), vague attributions (Experts believe, Studies show), filler phrases (In order to, Moreover), inline-header list with emoji, superficial -ing analysis (symbolizing... reflecting... highlighting...), formulaic challenges (Despite challenges... continues to thrive), generic conclusion (the future looks bright, only time will tell), false range implied in the adoption bullet. + +That's 35+ AI tells. + +## $avoid token + web app + +The community created a Solana token around this project. You can burn $avoid tokens to run the audit skill through a web app: + +**[avoid-ai-writing-app.vercel.app](https://avoid-ai-writing-app.vercel.app)** — paste text, burn 1,000 $avoid, get a full audit + rewrite. Every token burned is permanently removed from circulation. + +| | | +|---|---| +| Web App | [avoid-ai-writing-app.vercel.app](https://avoid-ai-writing-app.vercel.app) | +| DexScreener | [dexscreener.com/solana/4b5m...](https://dexscreener.com/solana/4b5mprekzapcwybrsbbaiewtk4amck62rpcznjcxz69m) | +| Telegram | [t.me/avoidaiwriting](https://t.me/avoidaiwriting) | +| X Community | [x.com/i/communities/2036440377356591415](https://x.com/i/communities/2036440377356591415) | +| CA | `BsidWuYJnayqMXVsLGr34524vmZ1BrWFhPer3198pump` | + +## Credits + +Pattern research informed by: +- [Pangram Labs](https://www.pangram.com/) AI detection research — structural regularity insights, vocabulary flags from a decoder-only classifier trained on 28M human documents +- Wikipedia's [Signs of AI-generated text](https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing) documentation — the canonical reference for AI writing tells, maintained by Wikipedia editors +- [blader/humanizer](https://github.com/blader/humanizer) Claude Code skill +- [brandonwise/humanizer](https://github.com/brandonwise/humanizer) — tiered vocabulary system, statistical analysis research (burstiness, sentence length variation, trigram repetition), and rewrite philosophy +- [OpenClaw](https://github.com/openclaw/openclaw) humanizer skill ecosystem — community patterns and vocabulary research + +Authored by [Conor Bronsdon](https://github.com/conorbronsdon) · [LinkedIn](https://www.linkedin.com/in/conorbronsdon/) · [Chain of Thought podcast](https://chainofthought.show) + +## License + +MIT