humanizer-skill
AGENTS.md248 starsChanged 4 months agoMITView on GitHub
Universal harness context file (AAIF/Linux Foundation spec). Auto-discovered by Claude Code, Cursor, Copilot, Codex CLI, Windsurf, Cline, Gemini CLI, Aider, Zed, Jules, RooCode, Factory, and 10+ other harnesses. Humanizer is a pure-Markdown Claude Code skill that detects 55 AI writing patterns and rewrites text to sound like a human wrote it. It scores text 0-100 (higher = more AI smell), applies one of 5 named voice profiles, and injects sentence-length burstiness. The installable skill core is a single zero-dependency Markdown…
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 33,315 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
The file
We split this AGENTS.md into the rules it gives an agent
4 rules. About 0 are common, 0 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 115
Run: /humanizer "..." --voice casual — verify the rewrite has shorter/varied sentences and no "pivotal"/"reshaping"/"rapidly evolving".
- Very specific: line 121
All 55 patterns are numbered P1-P55 in SKILL.md.
- Very specific: line 122
Every new pattern needs: a name, what to look for, and a before/after example.
- Very specific: line 124
No em dashes in SKILL.md — the skill bans em dashes (P13), so the skill file enforces its own rules.
≈ “Common” is an estimate: at least 1 in 5 of the 42,283 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
AGENTS.md — Humanizer Skill
Universal harness context file (AAIF/Linux Foundation spec). Auto-discovered by Claude Code, Cursor, Copilot, Codex CLI, Windsurf, Cline, Gemini CLI, Aider, Zed, Jules, RooCode, Factory, and 10+ other harnesses.
What this repo is
Humanizer is a pure-Markdown Claude Code skill that detects 55 AI writing patterns and rewrites text to sound like a human wrote it. It scores text 0-100 (higher = more AI smell), applies one of 5 named voice profiles, and injects sentence-length burstiness. The installable skill core is a single zero-dependency Markdown file: skills/humanizer/SKILL.md. The repo also ships optional extras (on-demand reference files and a zero-dependency metrics CLI) that the skill core never requires.
File map
skills/
humanizer/
SKILL.md # the skill — the only file you need to install (zero-dep)
README.md # skill-specific docs
references/
patterns.md # per-pattern deep dives and provenance (on demand)
patterns.zh.md # provisional native-Chinese appendix
always-on-templates.md # copy-paste blocks for CLAUDE.md / SOUL.md / etc.
evals/
evals.json # should-trigger / should-NOT-trigger eval cases
cli/ # optional zero-dependency metrics + CI gate (Node, node:test)
.github/
actions/humanizer-gate/ # reusable GitHub Action for CI docs-quality gating
.claude-plugin/
plugin.json # Claude Code plugin manifest (name, version, author, keywords)
marketplace.json # single-plugin marketplace entry (installable via claude plugin marketplace add)
examples/
blog-post/
before.md # raw AI-generated blog paragraph (high AI-tell score)
after.md # humanized output with annotations
docs/
VIRAL-AUDIT.md # supernova engine score/tier/gap report
LAUNCH-PLAN.md # June 2026 channel-sequenced launch plan
README.zh-CN.md # Simplified-Chinese README (English-writing wedge)
docs-site/ # full MDX documentation site (Docusaurus, deploy-ready)
landing/ # static landing page (humanizer-skill.vercel.app)
tools/ # demo.sh + demo.tape (VHS terminal demo)
submissions/ # awesome-list / marketplace submission draftsHow to install the skill
Cross-agent via the skills CLI (vercel-labs/skills):
npx skills add Aboudjem/humanizer-skill # any supported agent
npx skills add Aboudjem/humanizer-skill -a claude-codeThe repo uses the standard skills/<name>/SKILL.md layout the CLI auto-discovers.
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.mdGlobal (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.mdVia Claude Code plugin marketplace:
claude plugin marketplace add Aboudjem/humanizer-skillClaude Code auto-discovers skills in .claude/skills/, ~/.claude/skills/, or any plugin's skills/ directory. No restart needed.
How to invoke the skill
/humanizer "Your AI-generated text here"
/humanizer "text" --voice casual
/humanizer "text" --mode detect --score
/humanizer --file docs/README.md --voice technical
/humanizer "text" --aggressive --iterate 3The skill is invoked as /humanizer. It auto-triggers when a user asks to:
- "make this sound more human"
- "rewrite this to avoid AI detection"
- "check this for AI tells"
- "humanize this text"
- "clean up the AI writing in this"
Modes
| Mode | What it does |
rewrite | Full transformation with voice injection (default) |
detect | Scan-only — reports patterns and score, no rewrite |
edit | In-place file editing with minimal changes |
Voice profiles
| Voice | Best for |
casual | Blog posts, social media, community docs |
professional | Business comms, reports, formal docs |
technical | API docs, READMEs, architecture docs |
warm | Tutorials, onboarding, support content |
blunt | Reviews, internal comms, direct feedback |
How to test
The skill itself is pure Markdown, so test it by running it:
- Install the skill (see above).
- Open Claude Code in any project.
- Run:
/humanizer "In today's rapidly evolving landscape, AI is reshaping how we think about creativity. This groundbreaking shift represents a pivotal moment in human history." --mode detect --score - Expected output: a high score with patterns P1, P4, P7, P29, P30 flagged.
- Run:
/humanizer "..." --voice casual— verify the rewrite has shorter/varied sentences and no "pivotal"/"reshaping"/"rapidly evolving".
The optional CLI has an automated suite: cd cli && node --test (25 tests, zero dependencies). Smoke it with node cli/index.js compare --before examples/blog-post/before.md --after examples/blog-post/after.md. See examples/blog-post/ for a documented before/after reference case.
Conventions for contributors
- All 55 patterns are numbered P1-P55 in
SKILL.md. New patterns continue the sequence. - Every new pattern needs: a name, what to look for, and a before/after example. Deep dives and sources go in
references/patterns.md, not the core. - The badge count in
README.md(patterns-55), the CI threshold (EXPECTEDinci.yml), and the CHANGELOG must move together when patterns are added. - No em dashes in
SKILL.md— the skill bans em dashes (P13), so the skill file enforces its own rules. - CI runs a markdown lint pass and a self-check that scans
SKILL.mdfor its own banned patterns.
Cross-harness notes
- Claude Code: full support via
/humanizercommand. - Cursor / Windsurf / Continue.dev: copy
SKILL.mdto the editor's rules/skills directory and reference in system prompt. - Codex CLI / Gemini CLI: copy to the tool's skills directory (see README for per-editor install).
- VS Code + Copilot: paste
SKILL.mdcontent into your Copilot instructions. - The skill contains no tool calls to Claude-specific APIs. All instructions are model-agnostic Markdown.
Author
Adam Boudjemaa — github.com/Aboudjem · LinkedIn · X
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

