humanize

LLM-agnostic skills for static AI text humanization and detection.
Grounded in 50+ peer-reviewed sources through April 2026.

Works in any LLM agent: Claude Code, Codex CLI, ChatGPT, Gemini, Cursor, Aider, OpenCode, Continue, Copilot. The install paths differ; the skill content is identical.

Contents

Get started

• What's inside — the two skills, at a glance
• Installation — one command for Claude Code, Codex CLI, ChatGPT desktop, or any agent
• Usage — how to invoke each skill
• Benchmark — 25 inputs, two independent scorers

Why the skills work

• Background — the gap between AI and human writing
• The detection literature — perplexity, burstiness, stylometry, discourse
• Detection methodology taxonomy — zero-shot, classifier, watermarking, hybrid
• Adversarial findings — what evasion techniques actually do to detectors
• The nine humanization levers — the rules the skill applies

Limits and what closes them

• Accuracy benchmarks from the literature — detector accuracy numbers from published research
• Known limitations — what this skill does not guarantee
• What this rule-based approach cannot do (the ceiling) — the learned-classifier ceiling and why it exists
• Complementary techniques — what closes the gap (cross-model paraphrase, base-model rewriting, manual edits)

Maintenance & references

• Updating · Uninstalling · Contributing · License · Citation · References

What's inside

Both are static rule-based skills (single SKILL.md per skill, zero runtime dependencies). Six advanced hybrid techniques are documented in the humanize skill for high-stakes use.

What "static" means here. No models trained, no API calls, no detector-in-the-loop. The skill is a rulebook the host LLM follows. Effective against perplexity-based detectors (ZeroGPT, QuillBot). The "What this approach cannot do" section below is honest about the learned-classifier ceiling (Grammarly, GPTZero) and what additional steps close that gap.

Installation

This repo bundles two skills (humanize and ai-check) in their own subdirectories. Installation copies both into your agent's skills folder.

Install everywhere in one command

If you use multiple agents (Claude Code, Codex CLI, ChatGPT desktop), install to all three skill directories at once:

git clone https://github.com/harshaneel/humanize.git
cd humanize && ./install.sh all

This installs to ~/.claude/skills/, ~/.codex/skills/, and ~/.agents/skills/. Add --copy if you prefer self-contained files over symlinks.

Claude Code

Clone the repo, then copy both skill folders into Claude Code's skills directory:

git clone https://github.com/harshaneel/humanize.git
mkdir -p ~/.claude/skills
cp -R humanize/humanize humanize/ai-check ~/.claude/skills/

Or use the included install script (symlinks instead of copies, so git pull updates apply automatically):

git clone https://github.com/harshaneel/humanize.git
cd humanize && ./install.sh

Codex CLI

git clone https://github.com/harshaneel/humanize.git
mkdir -p ~/.codex/skills
cp -R humanize/humanize humanize/ai-check ~/.codex/skills/

Or cd humanize && ./install.sh codex to use the install script.

ChatGPT desktop / OpenAI agents

ChatGPT desktop and several OpenAI agent harnesses read from ~/.agents/skills/.

git clone https://github.com/harshaneel/humanize.git
mkdir -p ~/.agents/skills
cp -R humanize/humanize humanize/ai-check ~/.agents/skills/

Or cd humanize && ./install.sh chatgpt to use the install script.

OpenCode

git clone https://github.com/harshaneel/humanize.git
mkdir -p ~/.config/opencode/skills
cp -R humanize/humanize humanize/ai-check ~/.config/opencode/skills/

Note: OpenCode also scans ~/.claude/skills/ for compatibility, so a single clone into ~/.claude/skills/ works for both tools.

Claude.ai / Claude Desktop

The web and desktop apps don't read from disk. Upload through the UI instead:

1. Open Settings → Capabilities → Skills.
2. Click Create skill and upload [humanize/SKILL.md](humanize/SKILL.md).
3. Repeat with [ai-check/SKILL.md](ai-check/SKILL.md).
4. Toggle each skill on in conversations where you want it active.

Any other chat agent (ChatGPT, Gemini, Cursor, Aider, Cline)

No install needed. Open [humanize/SKILL.md](humanize/SKILL.md), copy the raw contents, and paste into a new conversation prefaced with: "Use these instructions whenever I ask you to humanize text." Same for [ai-check/SKILL.md](ai-check/SKILL.md).

Usage

Humanize

/humanize

[paste your text here]

Or ask the model directly:

Please humanize this text: [your text]

AI-check

/ai-check

[paste your text here]

Or ask the model directly:

Does this sound AI? [your text]

ai-check returns a structured report: verdict (Human / Likely Human / Uncertain / Likely AI / AI), confidence, score breakdown across 9 signal categories, evidence quotes for every flag, and an AI-edited fraction estimate (Pure human / Lightly AI-assisted / Mixed authorship / Heavily AI-edited / Pure AI).

Voice matching

To match your personal writing style, provide a sample of your own writing before the text to humanize:

/humanize

Here's a sample of my writing for voice matching:
[paste 2-3 paragraphs of your own writing]

Now humanize this text:
[paste AI text to humanize]

The skill will distill style hypotheses from your sample (sentence rhythm, vocabulary preferences, structural quirks, what you never do) and apply them to the rewrite. Based on HyPerAlign (arXiv 2505.00038); more effective than the model trying to guess a generic "human voice" on its own.

Combine the two skills

Use ai-check to score, then humanize to fix:

Run ai-check on this paragraph, then humanize it to address every flag you raised.

[paste your text]

The model will produce the audit report, then a rewrite that targets the specific signals it flagged.

Benchmark

Tested on 25 AI-flavored input texts across 25 distinct registers: tech blog, postmortem, product launch, academic abstract, business email, Slack update, LinkedIn post, cover letter, marketing copy, press release, investor update, job posting, customer support, recipe intro, travel writing, restaurant review, book review, personal essay, privacy policy, tutorial, comparison article, roadmap update, conference abstract, README intro, career advice. Each input contained typical AI tells (banned vocabulary, em dashes, balanced framing, RLHF-style hedging). Each was rewritten by humanize following the full nine-lever protocol plus the Step 5.5 audit-revise loop.

The 25 humanized outputs were scored by two independent detectors.

Internal scorer: ai-check (this repo, rule-based stylometry)

All 25 outputs landed in the Human / Likely Human range. Zero scored Uncertain or higher.

External scorer: official Binoculars (cross-perplexity, different signal class)

For cross-validation, the same outputs were scored with Binoculars, the zero-shot AI detector from Hans et al. (ICML 2024, arXiv:2401.12070). Binoculars uses a different signal class than ai-check: a cross-perplexity ratio between two close LLMs rather than rule-based pattern matching. Agreement between the two scorers is independent evidence rather than scorer-implementation bias.

Model pair: TinyLlama-1.1B base + TinyLlama-1.1B-Chat. The paper uses Falcon-7B; TinyLlama is a lightweight substitute since the Binoculars algorithm is model-agnostic.

All 25 outputs scored above the threshold, on the Human side of Binoculars' decision boundary.

Scope

What this benchmark prove