Humanizer

Install

Works in Claude Code, Cursor, Codex, opencode, and 70+ other AI editors through vercel-labs/skills, the same community installer used by hundreds of Claude Code skills. One command, no folders to copy by hand:

npx skills add Aboudjem/humanizer-skill

Prefer to skip the installer entirely? A plain curl, and per-editor folder paths for Cursor, Copilot, Codex, Gemini CLI, Windsurf, Continue.dev, and OpenClaw, are in Install without tooling below.

See it work

Score any text right in your editor. This just scans, it doesn't rewrite:

/humanizer "In today's rapidly evolving landscape, AI is reshaping how we think about creativity." --mode detect --score

[Score: 84/100, Pure AI smell]

Patterns found: 5
| P4  | Promotional          | "rapidly evolving landscape" |
| P7  | AI Vocabulary        | "reshaping"                  |
| P22 | Filler               | "In today's"                 |
| P29 | Comprehensive Opening| meta-commentary              |
| P30 | Uniform Length       | sentences avg 19 words       |

The score runs 0 to 100. Lower is more human. Drop the flags and it rewrites instead of scanning: /humanizer "your text" --voice casual hands back the same idea in a real voice, and the score falls to single digits.

[!TIP] This is about writing better, not tricking detectors. Clean writing doesn't set off AI detectors, because it skips the lazy habits they look for. Fix the writing and the detection sorts itself out.

Why this exists

AI writing has a fingerprint. Every sentence runs about the same length. It reaches for the same safe words, and it pads with filler like "in today's landscape." Two bits of jargon worth knowing: how much your sentence lengths vary is called burstiness (people mix short and long, AI keeps them all one size), and those little giveaway habits are called AI tells.

This AI writing humanizer knows 55 of them. It finds them, scores the text, and rewrites it in a voice you pick. All from a single file your editor reads on your own machine.

Features

• 55 named patterns, from travel-brochure adjectives to invisible unicode tricks. The biggest open list of its kind.
• 5 voices: casual, professional, technical, warm, blunt. Each one changes the rhythm, not just a few words.
• 3 modes: detect (score it), rewrite (fix it), edit (change a Markdown file in place).
• A 0 to 100 AI-tell score on demand, so you can measure before and after.
• A guard against over-editing, so it sharpens real writing instead of flattening it.
• One Markdown file. No dependencies. No network calls. It runs standalone.
• Optional metrics CLI, CI check, and pre-commit hook if you want a computed score in your pipeline or a fast local gate.

The list above is the highlights. For the exhaustive version, category by category, see Every feature, in full further down.

Usage

/humanizer "text"                                rewrite it with the default voice
/humanizer "text" --voice casual                 pick a voice
/humanizer "text" --mode detect --score          scan only, add a 0 to 100 score
/humanizer --file docs/README.md --voice technical   fix a file in place
/humanizer "text" --aggressive --iterate 3       heavy rewrite, loop until the score bottoms out

Rewrite is the default, so you never have to name it.

Other flags: --mode picks detect, rewrite, or edit. --purpose layers on rules for an essay, email, marketing copy, technical doc, or general text. --iterate N runs the scan-rewrite loop up to 3 times. --aggressive uses a heavier hand. Drop a humanizer-context.md file in your project root with your own writing samples and banned words, and the skill folds it into whichever voice you chose.

More

Technical docs (--voice technical)

Before: This comprehensive guide delves into the intricacies of our authentication system. The platform leverages cutting-edge JWT technology to provide a seamless, secure, and robust authentication experience.

After: The auth system uses JWTs. Tokens expire after 15 minutes; refresh tokens last 7 days. Role-based access control restricts API endpoints by user role. The token rotation logic is in src/auth/refresh.ts.

Killed 9 patterns. Added real details. Cut the word count by 40%.

Blog post (--voice casual)

Before: In today's rapidly evolving technological landscape, artificial intelligence is reshaping how we think about creativity. This groundbreaking shift represents a pivotal moment in human history.

After: I've been messing around with AI image generators for about six months now, and I still can't decide if I love them or if they make me uneasy. The outputs are impressive. But there's something missing. It's like eating a perfect-looking meal that has no flavor.

Traded vague commentary for a lived opinion. Sentence lengths: 8, 31, 22, 4, 13 words. That's burstiness.

LinkedIn (--voice professional)

Before: Excited to announce that I've taken on a pivotal new role at TechCorp! This incredible opportunity represents a significant milestone in my professional journey. #NewBeginnings #Innovation

After: Started a new job at TechCorp this week. I'm leading their developer tools team, 12 engineers serving about 400 developers. First week has been drinking from the firehose: new codebase, new faces, new coffee machine I can't figure out.

No emojis, no hashtags. Real numbers instead of "pivotal milestone."

Project-scoped (travels with your repo):

mkdir -p .claude/skills/humanizer && curl -sL https://raw.githubusercontent.com/Aboudjem/humanizer-skill/main/skills/humanizer/SKILL.md -o .claude/skills/humanizer/SKILL.md

Global (available in every project):

mkdir -p ~/.claude/skills/humanizer && curl -sL https://raw.githubusercontent.com/Aboudjem/humanizer-skill/main/skills/humanizer/SKILL.md -o ~/.claude/skills/humanizer/SKILL.md

Prefer Claude Code plugins? Add the marketplace instead:

claude plugin marketplace add Aboudjem/humanizer-skill

Same idea for other editors, just change the folder: .cursor/skills/, .github/skills/ (Copilot), .codex/skills/, .gemini/skills/, .windsurf/skills/, .continue/skills/. For OpenClaw, run clawhub install humanizer-skill.

[!NOTE] Claude Code finds skills in .claude/skills/, ~/.claude/skills/, or any plugin's skills/ folder. No restart needed. Other editors may need you to point at the file in their config.

Every pattern has a full write-up, its triggers, and a before/after example in skills/humanizer/SKILL.md and references/patterns.md.

The core catalog (P1-P30) draws on Wikipedia: Signs of AI writing (CC BY-SA), the cited reference list most of those entries come from.

Detection and scoring

• 55 named, numbered patterns across 6 categories (Content, Language & Style, Communication, Filler & Hedging, Emerging, Craft & Forensic)
• A 0-100 AI-tell score with a 5-band verdict: Pristine, Mostly human, Mixed, AI-leaning, Pure AI smell
• Burstiness (sentence-length variance) and perplexity (word predictability) as the two measurable signals behind the score
• Tiered vocabulary confidence on the AI-word list: Tier 1A (evidence-grade, near-definitive alone), 1B (wordiness-grade, weighted lower), Tier 2 (flag only in density), Tier 3 (context only, never alone)
• A false-positive guard that protects real human writing: hard-to-fabricate specifics, mixed or unresolved feelings, lived sensory detail, era-bound in-group voice, deliberate imperfection, and content written before late 2022
• Explicit guardrails for neurodivergent writers (autistic/ADHD low-variance prose) and non-native English speakers, so the skill doesn't launder a real voice flat
• A no-fabrication rule: rewrites can sharpen and restructure, but can't invent facts, names, dates, or numbers that aren't in the source

Rewriting craft

• 5 named voice profiles: casual, professional, technical, warm, blunt, each changing rhythm and word choice, not just vocabulary
• A Voice Read, an Anti-Default Discipline pass, a Position ("teeth") engine, a Concretizer pass, and an Opening tournament (--openings N)
• 11 soul-injection techniques: real opinions, a certainty-calibration spectrum, sensory/experiential detail, shared-experience callbacks, tangents, dramatic paragraph-length variance, imperfect starts, broken parallel structure, callbacks, self-correction, and endings that just stop
• --purpose layers content-type rules on top of voice: essay, email, marketing, technical, general
• --aggressive for a heavier hand; --iterate N loops detect-rewrite-detect up to 3 times until it converges
• A draft/self-audit/final metacognitive pass, cheaper than a full --iterate loop, that asks "what still reads as AI?" after the first rewrite

Modes

• detect: scan and report every matched pattern with a severity read, no changes made
• rewrite: the full transform (default mode)
• edit: in-place file editing via the Edit tool, targeted changes only, with an explicit refusal guard for non-prose targets (source code, config, structured data)

Flags

• --score, --mode, --voice, --file, --aggressive, --iterate N, --purpose, --openings N, --ignore-code, --ignore-quotes

Integrations and tooling

• Works in Claude Code, Cursor, Codex, opencode, and 70+ AI editors via npx skills add (vercel-labs/skills)
• Claude Code plugin and marketplace support (claude plugin marketplace add)
• OpenClaw support (clawhub install humanizer-skill)
• An optional, zero-dependency metrics CLI (cli/) that computes burstiness, type-token ratio, MATTR, trigram repetition, AI-vocabulary density, and Flesch-Kincaid grade, with a transparent 0-100 score
• A CI quality gate with a hard threshold or baseline/regression mode, plus a reusable GitHub Action
• A .pre-commit-hooks.yaml for the Python pre-commit framework (fast local gate, no install step), and a documented Husky example for JS-native repos
• A zero-backend browser demo at humanizer-skill.vercel.app: client-side regex subset plus burstiness scoring, no API calls, no data leaves the browser

Docs, localization, and trust

• A full Docusaurus documentation site, deploy-ready
• A Simplified-Chinese README and a provisional native-Chinese pattern appendix
• llms.txt for AI-crawler and agent discoverability
• Worked before/after examples for technical docs, blog posts, and LinkedIn posts
• Zero dependencies, zero network calls, zero telemetry, MIT licensed
• CI enforces the skill's own rules on itself: zero em dashes in SKILL.md, and the badge/pattern-count/CHANGELOG stay in lockstep

AI detectors measure two things, and both are well documented.

Burstiness is how much sentence length varies. People write a 3-word sentence, then a 40-word one, then a 12-word one. AI parks almost every sentence around 18 words. Flat lengths read as AI.

Perplexity is how predictable each word is. AI picks the most likely next word every single time. People reach for the surprising one. Less predictable text reads as human.

Word-swap tools like QuillBot change individual words but leave the rhythm and the predictability alone. You need to change the structure, not just trade synonyms.

According to GPTZero's own detection research, human sentence length varies wildly while AI-generated text stays close to flat, which is why burstiness injection is the skill's core rewrite technique. According to a Washington Post analysis of 328,000 messages (2025), phrases like "it's not X, it's Y" are among the AI tells that analysis surfaced, alongside emoji use and the em dash. According to the RAID benchmark (ACL 2024), structural paraphrasing (not just word-swapping) drops DetectGPT's detection accuracy from 70.3% to 4.6%. According to the HC3 corpus study (Guo et al., arXiv 2301.07597), human answers average 142.5 words versus ChatGPT's 198.1 across roughly 40,000 paired answers, and humans draw from a measurably larger vocabulary.

The skill alone is enough to rewrite text. If you also want to measure your docs and block bad ones before they ship, the repo ships a small Node CLI with zero dependencies that computes the signals the skill describes.

node cli/index.js score README.md

node cli/index.js scan docs/ --fail-above 40

Drop it into a pipeline with the bundled Action:

- uses: Aboudjem/humanizer-skill/.github/actions/humanizer-gate@main
  with:
    path: docs/
    fail-above: '40'

Prefer a fast local gate over a CI-only one? The repo also ships a .pre-commit-hooks.yaml for the Python pre-commit framework, wrapping the same CLI.

No API keys, no network, no third-party packages. It's a deterministic stand-in for the skill's holistic score. Details in cli/README.md.

The skill is a Markdown prompt, so it runs on whatever model your editor points at. The patterns and voices don't care which. Only the creativity of the rewrite step shifts a little. Tested on Claude Opus/Sonnet/Haiku 4.x (Sonnet is the daily pick), GPT-4.x and GPT-5 through Codex CLI, and Gemini 2.x through Gemini CLI. Local models work too, with longer prompts and --aggressive.

No telemetry. No data collection. No API calls. Nothing leaves your machine.

What you install is one Markdown file (skills/humanizer/SKILL.md) that your editor reads locally. No JavaScript, no binaries, no network. The optional metrics CLI in cli/ is a separate layer: still plain Node, still zero dependencies, still fully offline, and the skill never calls it.

Documentation

• Skill source and full pattern catalog: skills/humanizer/SKILL.md
• Pattern deep dives, triggers, and examples: references/patterns.md
• Optional metrics CLI, CI gate, and pre-commit hook: cli/README.md and .pre-commit-hooks.yaml
• A full docs site (Docusaurus, ready to deploy) lives in docs-site/: npm --prefix docs-site install && npm --prefix docs-site run build
• Version history: CHANGELOG.md

Contributing

Found a new AI pattern, or a cleaner fix? PRs welcome. Add a short entry to SKILL.md, put the deep dive and a before/after example in references/patterns.md, and keep the badge count, CI threshold, and CHANGELOG in sync. See CONTRIBUTING.md.