Humanizer: fixing AI smell without dumbing down the thinking

I draft a lot with agents. The ideas are often fine. The prose still smells like a model wrote it — generic staging, rhythm by rule, every ordinary fact dressed as a pivotal moment. That texture is what Wikipedia's Signs of AI writing catalog calls out, and once you see it you can't unsee it in your own drafts either.

Humanizer is an agent skill aimed at that smell. Useful when the thinking is already done. Dangerous when you treat “sounds human” as “is correct.” Here's how I'm using it — and when I refuse to.

What it actually is

Humanizer is a plain Markdown skill (SKILL.md), not a SaaS rewriter and not a detector. It tells a supporting agent how to rewrite AI-sounding text without changing the claims. Because the skill is just Markdown, it works with any agent that loads skills — same package, different hosts.

Under the hood the skill marks tells strongest-first, drafts a rewrite that doesn't treat the original structure as sacred, checks that draft against the patterns and the original claims, then writes the final version. Names, numbers, dates, quotes, and citations have to come from the source or from you. If a sentence needs a missing detail, Humanizer asks instead of inventing one. That ask is the feature. Don't skip it to keep a paragraph shape you liked.

Install

Skills CLI (global):

npx skills add blader/humanizer --global

Leave off --global for a project-local install. You can also pass --agent (or --agent '*') to choose which agents receive it, then reload their skills. Invoke with /humanizer.

Claude Code plugin path (2.1.142+):

/plugin marketplace add blader/humanizer
/plugin install humanizer@humanizer

The plugin may answer to /humanizer:humanizer instead of plain /humanizer. Check which slash command your install registered before you build muscle memory around the wrong one.

When it helps

I reach for it after the hard part is done — not as a first pass on a blank page:

• Polishing docs, launch posts, and READMEs once the claims, commands, and constraints are locked
• Voice matching — paste 2–3 paragraphs of your own writing so the rewrite follows your rhythm, punctuation, and deliberate quirks
• Catching the usual tells: not-X-but-Y contrasts, “let's dive in” run-ups, decorative bold, one-line closers that restate the section, chatbot residue (“Great question!” / “I hope this helps!”)

That's a texture pass on finished thinking. It strips staging and inflated significance so the concrete claim can sit in the open. It is not a substitute for having something to say, and it will not invent a better architecture for you.

When it papers over weak thinking

Running /humanizer on an empty or vague draft just makes vagueness sound confident. “Sounds human” is not “is correct.” Using it to hide missing facts is worse — the skill will ask when a detail is missing, and that prompt is a warning light. Answer it with a real fact, or cut the sentence. Don't invent to keep the paragraph shape.

The failure mode I care about most is social: a draft that was thin on evidence becomes fluent, so reviewers stop probing. Fluency is not a substitute for a measured result, a cited number, or a command you actually ran. If the draft couldn't survive a hard review before humanize, it shouldn't after.

Humanize for texture after you've drafted for truth. Never the other way around.

Illustrative before / after (not measured results)

The project's README shows pattern-level rewrites and a longer travel-story example. The snippets below are illustrative examples in that style — not A/B tests, not SEO results, not claims about detection scores or engagement.

Before (example):

It's not just a configuration change — it's a pivotal shift in how teams approach deployment. Let's dive in.

After (example):

Ship the config change behind a flag, watch error rates for one release, then remove the old path.

Same job: strip staging and inflated significance, keep (or demand) a concrete claim. If your draft doesn't have that claim yet, humanize won't invent a good one for you — and if it asks, answer with something real or delete the line.

Practical workflow

1. Draft for truth. Get the facts, commands, version pins, and constraints right first — even if the prose is stiff and the openings are ugly.
2. Humanize for texture. Point /humanizer at the paste or file. Optionally include a writing sample for voice. Prefer file mode when you want a diffable edit.
3. Re-check. Confirm numbers, paths, flags, and quotes are unchanged. Diff the file if the skill edited on disk. Re-run any command you quoted.

When you point it at a file, the skill claims it changes only the prose and leaves code, data, frontmatter, and link targets alone. Still verify — especially around command blocks, YAML, and version pins. “Leaves code alone” is a claim to spot-check, not a warranty.

Caveats

• It's a prompt pack. Output quality tracks the model running it; a weaker model will still miss tells or over-edit.
• Still verify every technical claim yourself. Humanizer is not a fact-checker.
• Don't humanize code blocks or structured data blindly.
• Voice matching needs a real sample. Without one, you get “generic human,” not “you.”

Bottom line

Humanizer is a sharp finishing tool for agent-written prose. Use it when the thinking is solid and the draft just wears AI staging. Skip it — or answer its questions — when the draft is hollow. Fixing smell without fixing the claims is how you publish confident nonsense.

Source: github.com/blader/humanizer.