An open-source Agent Skill that preserves what you mean and learns how you write from real examples.
Humanise is for people who use AI to draft or edit important writing and want the result to reflect their judgement, evidence and voice. Your agent loads the skill when you ask it to write. Humanise protects the point, facts and level of certainty before it changes the style.
You need Node.js 18 or later. Python 3 runs the local writing checker and voice tools.
npx humanise@1.0.0 install --provider=codex
npx humanise@1.0.0 doctor --provider=codexStart a new Codex task and invoke $humanise rewrite. See the illustrative example,
follow the complete getting-started guide,
or check the compatibility evidence.
The example below is illustrative. It was not produced from a recorded reproducible run, and the figures are part of the example. In real use, every fact must come from the writer's brief or source.
An untreated model might write:
In today's fast-paced landscape, onboarding isn't just about reducing friction, it's about creating a seamless and engaging journey that empowers users to unlock value.
humanise starts with the facts and the writer's judgement:
We cut the signup form from nine fields to three last Tuesday. Activation moved from 41% to 58% in two weeks. The engineering was straightforward. Agreeing on what we could stop asking took longer.
The intended difference is a specific point supported by supplied evidence. Humanise is instructed to preserve the writer's meaning and never invent detail to make the prose feel more human.
- Preserves meaning before changing style. The point and facts come first, along with certainty, caveats and the ask.
- Learns from real writing evidence. Samples and draft-to-final edits show Humanise how your judgement and word choices work together.
- Models the reader and relationship. The same writer should sound different with a regulator, a colleague or a close collaborator.
- Stores the profile locally. Your samples, decisions and voice profile stay in the installed skill directory on your machine.
A profile is optional for the first rewrite. Humanise uses conservative engine defaults and does not pretend it already knows your voice. When you are ready to personalise it, initialise a local profile:
npx humanise@1.0.0 init --provider=codexThe getting-started guide covers configuration, one-sample calibration, expected output and troubleshooting without assuming you already know how Agent Skills work.
Claude Code users can install the repository as a marketplace plugin instead:
/plugin marketplace add Nisus74/humanise
/plugin install humanise@humanise
/reload-plugins
Invoke the plugin with /humanise:humanise rewrite or /humanise:humanise init.
Your profile is stored locally. Humanise itself does not upload it, although the AI host you use still has its own data policy.
Profiles may contain emails, drafts and edit history:
- User-scope installs keep the profile under your home directory.
- Project installs add the profile and configuration to Git's local exclude file.
humanise doctorchecks installation and warns when a project profile is tracked.- The local checker uses no model and no API key.
Review and redact samples before saving them. Do not put secrets, credentials or material you are not allowed to share into a profile. See Security for reporting problems.
Every draft follows the same order:
- Preserve the point and facts, the level of certainty, the caveats and the ask.
- Model the relationship, reader state and stakes.
- Prefer direct samples from the same channel and relationship.
- Draft the content and argument before applying surface style.
- Verify fidelity, voice and mechanical risks in that order.
The project keeps the shared engine and personal evidence separate:
- Body:
skill/SKILL.md, commands and references. Shared and open source. - Soul:
profile/, including samples, decisions, negative examples and relationship overlays. Private to the writer.
Read Body and soul for the design.
humanise is one skill with optional modes:
| Mode | Use it for |
|---|---|
init |
Start or deepen a private voice profile |
guide |
Draft new material |
rewrite |
Edit existing text at the right strength |
check |
Inspect mechanical and structural risks |
fingerprint |
Rebuild the evidence-backed voice model |
learn |
Capture the user's final edits |
improve |
Run the advanced engine improvement workflow |
See Commands and modes for examples.
humanise install --provider=<name> [--global|--project]
humanise doctor --provider=<name> [--global|--project]
humanise init [--provider=<name>] [--global|--project]
humanise detect <file> [dialect] [medium]
humanise voiceprint <file>
humanise voiceprint --build
humanise voiceprint --status
humanise build
Run any command as npx humanise <command>.
Good first contributions include a clearer installation step, a provider smoke test, a channel playbook or a regional English pack. Engine changes need evidence and regression coverage. Personal voice samples and edit history never belong in a pull request.
Start with Contributing and run
npm run quality before opening a PR.
humanise supports English today, with Australian, British and American guidance. Adding another language needs native writing evidence, language-specific model tells, cultural calibration, checker behaviour and fluent review. Read Adding a language before proposing one.
Stars help people discover the project. Contributions improve the shared engine. If humanise has saved you real editing time, you can also buy me a coffee.
No. The goal is faithful writing in a specific person's voice. Detector scores are unreliable and are not the product target.
Humanise itself does not upload your profile. The bundled checker is local and uses no model or API key. The AI host you use still has its own data policy, so review that separately.