humanizer

humanizer

A script and a skill for taking the machine sound out of a draft.

The script does the part that is mechanical: swapping utilize for use, deleting In today's fast-paced world,, dropping Additionally, from the head of a sentence. The skill does the part that needs a person: negative parallelism, em dash habits, sentences that end by restating themselves as significance.

Nothing here calls a model or the network. Every rule is a string rule you can read in scripts/humanize.mjs and delete if you disagree with it.

Install

No dependencies. Node 18 or newer.

git clone <this repo> && cd humanizer
node scripts/humanize.mjs --help

Or link the binary:

npm link
humanize draft.md

Usage

Report, without changing the file. The rewritten text goes to stdout; the findings go to stderr, so you can pipe one and read the other.

node scripts/humanize.mjs draft.md > clean.md

Rewrite in place.

node scripts/humanize.mjs draft.md --fix

From a pipe.

pbpaste | node scripts/humanize.mjs - | pbcopy

As a check in CI. --quiet suppresses the report and exits 1 if anything was found, so it fails a build on a generated-sounding README.

node scripts/humanize.mjs README.md --quiet || echo "README needs an edit"

Exit codes

Code	Meaning
0	nothing rewritten, nothing flagged
1	something was rewritten or flagged
2	bad usage

What it rewrites

Applied automatically by --fix. These are substitutions that are almost always right.

Category	Examples
Lexicon	delve into → look at, leverage → use, utilize → use, in order to → to, a myriad of → many, prior to → before
Openers	Additionally, Moreover, Furthermore, Notably, Ultimately, at the head of a sentence, deleted
Boilerplate	In today's fast-paced world,, In the ever-evolving landscape of X,, When it comes to
Promotional adjectives	seamless, robust, cutting-edge, game-changing, crucial, comprehensive, deleted before the noun
Hedged framing	It is important to note that, It should be noted that, deleted

Capitalisation follows what was replaced, and the pass tidies the double spaces and stranded punctuation its own deletions create. It is idempotent: running it twice changes nothing the second time, which is what makes it safe in a pre-commit hook.

Fenced code blocks, inline code spans and indented code are never touched. They are masked out before any rule runs and restored byte-for-byte afterwards, so `utilize()` survives a pass that rewrites the prose around it.

What it flags but will not rewrite

Reported with a line number. The fix depends on what you meant, so the script refuses to guess.

Flag	Example	The repair
negative-parallelism	It's not just a parser, it's a compiler.	Delete the negative half. Assert the positive.
em-dash	the result — a fast one — shipped	Ask whether a comma, a colon or a full stop does the work.
superficial-ing	..., highlighting the importance of testing.	Cut the clause; it restates the sentence as significance.
vague-attribution	Experts say the approach is sound.	Name the source or delete the claim.
rule-of-three	fast, cheap, and reliable	Keep the two that carry information.

skills/humanizer.md is the guidance for working through those, written to be dropped into an agent's skills directory.

Using it as a skill

Copy skills/humanizer.md into wherever your agent reads skills from. It tells the agent to run the script first, then work the flags by hand, and it carries the rules of thumb a regex cannot check: cut the summary paragraph, one claim per sentence, prefer the concrete number, keep the writer's jokes.

Roadmap

• doneDeterministic rewrite pass, idempotent, code-safe
• doneFive reported flags a regex should not decide
• not doneA --diff mode that prints a unified diff instead of the file
• not doneA dictionary file so a project can add its own swaps
• not doneA pre-commit hook example, since --quiet already exits non-zero

Details of each rule live in the skill.

Tests

npm test

Three tests, using the Node test runner, no dependencies: that the rewrite pass fires and leaves code spans alone, that the flags catch what they claim to, and that a second pass is a no-op.

Limitations, honestly

• English only, and tuned for technical prose. It will mangle poetry.
• It works on the string, not the syntax. We leverage the leverage of the lever becomes We use the use of the lever; there is no parser deciding which leverage is a noun.
• Deleting a promotional adjective sometimes leaves a sentence that is grammatical but odd. Read the diff.
• The rule-of-three flag has false positives on genuine three-item lists. It is a flag, not an error.

Licence

MIT. See LICENSE.