naturalize
Rewrites machine-sounding or overly polished text so a real person seems to have written it. Use when the user wants existing text to sound human ("humanize this text", "make this sound less like AI")
SKILL.mdplugins/mz-creative/skills/naturalize/SKILL.md
GitHubText Naturalization Pipeline
Overview
Rewrites AI-generated text to read as if a human wrote it, in one pass with no approval gates. expert-naturalizer (sonnet) detects the AI patterns (vocabulary spikes, structural templates, sentence-rhythm uniformity) and rewrites them, removing banned punctuation such as em dashes and semicolons. With research:yes, pipeline-web-researcher (mz-base) first gathers patterns newer than the embedded list. With voice:, it rewrites toward one writer's measured habits for the register instead of a generic human target. A script then checks the rewrite for banned punctuation, minus what allow: lifts. File input is overwritten in place, with the original kept in the task folder and a diff shown at the end.
When to Use
Rewrites existing AI-generated prose so it reads as human-written.
When NOT to use
- User wants original technical documentation written from scratch — use
document(which already runs naturalize as Phase 3) - User wants new promotional copy written rather than existing text rewritten — use
copywrite(which also naturalizes) - User wants to fix grammar in human-written text — this skill assumes AI patterns are present and may damage natural prose
- User wants to translate text — use
translate
Input
$ARGUMENTS — the text to rewrite or a file reference. Forms accepted:
- Inline text following the skill invocation (the entire arg block becomes the input)
@file:<path>— read text from the specified file; the rewrite overwrites it in placepreserve:<term>[,<term>...]— terms the rewrite keeps verbatim, such as a domain word that sits on the avoid list ("leverage" in a finance text)voice:@file:<path>— a voice profile: free-form notes on how one writer writes, per register (sentence length, final periods, commas, tone markers, stock phrases, what not to copy). The agent rewrites toward the register it matchesallow:<name>[,<name>...]— punctuation the ban lets through, fromem-dash,en-dash,semicolon,ellipsisandarrow, for a writer whose formal register uses themresearch:yes—pipeline-web-researcherpulls current AI pattern data from authoritative web sources before the rewrite (use when the embedded vocabulary may be 18+ months old)
If $ARGUMENTS is empty, ask via AskUserQuestion for either inline text or a file path. Never guess.
Constants
- PROJECT_ROOT: resolved once in setup with
echo "${MZ_MEMORY_ROOT:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; expand<PROJECT_ROOT>to it in every command and agent prompt. - TASK_DIR:
<PROJECT_ROOT>/.mz/task/ - REPORT_DIR:
<PROJECT_ROOT>/.mz/reports/ - CHUNK_THRESHOLD: 2000 (words above this trigger section-by-section rewriting)
- PUNCTUATION_CHECK:
${CLAUDE_PLUGIN_ROOT}/scripts/forbidden-punctuation.sh(each--preserve <term>exempts a preserved term and each--allow <name>an allowed character; exit 0 when clean, 1 with onefile:line: <name> <char>line per hit, 2 on a usage error or a file it can't read)
Core Process
Phase Overview
| # | Phase | File | Loop? |
|---|---|---|---|
| 0 | Setup | inline below | — |
| 1 | Rewrite (expert-naturalizer, optional web research first) | phases/rewriting.md |
— |
| 2 | Punctuation check and apply | phases/rewriting.md |
one fix-only re-dispatch |
No phase asks for approval. File input is safe to overwrite because input.md keeps the original and the run ends with a diff.
Phase 0: Setup
- Resolve
PROJECT_ROOTwith the command in Constants, before anycdor worktree switch, and use it for every.mz/path below. - Parse
$ARGUMENTS. Detect inline text vs@file:reference,preserve:terms,voice:,allow:names andresearch:yes. - If empty →
AskUserQuestionfor input source. Never guess. - If
@file:referenced, read the file and verify it is text (not binary, not too large to fit in context — if >50KB, warn the user). - If
voice:is given, read the profile and verify it is text. A missing or binary profile →AskUserQuestionto fix the path or run without one. - Every
allow:name must be one ofem-dash,en-dash,semicolon,ellipsis,arrow. An unknown name →AskUserQuestion, listing the valid names. task_name=<YYYY_MM_DD>_naturalize_<slug>where slug derives from the input (file basename or first 5 words of inline text). On collision append_v2,_v3.- Write the input text verbatim to
<PROJECT_ROOT>/.mz/task/<task_name>/input.mdwith the Write tool, which creates the folder. Don't copy it with Bash, which a sandbox may mount read-only. For@file:input this copy is the original that the diff compares against and the user can restore from. - With
voice:, write the profile verbatim to<PROJECT_ROOT>/.mz/task/<task_name>/voice.mdthe same way, so the agent reads it inside the project. - Write
state.md: schema_version: 2, Status, Phase, Started, phase_complete: false, what_remains: [], InputSource, PreserveTerms, VoiceProfile, AllowedPunctuation, ResearchRequested, FilesWritten. - Emit a visible setup block:
task_name, input source, length in words, preserve terms, voice profile, allowed punctuation, research flag.
Then run Phases 1 and 2 from phases/rewriting.md.
Common Rationalizations
| Rationalization | Rebuttal |
|---|---|
| "the text looks fine, skip the rewrite" | structural AI patterns are invisible without the agent's detection pass; vocabulary alone is not enough |
| "ask before overwriting the file, to be safe" | input.md keeps the original and the diff shows every change, so a question only adds a wait |
| "swap the flagged em dash for a hyphen so the check passes" | outside chat a spaced hyphen reads the same, so the sentence has to be restructured; in chat - is a real aside mark |
| "the check failed twice, leave its lines out of the summary" | the rewrite was applied anyway, so the lines are the only sign of what's left; a concern that isn't listed is a silent pass |
| "the profile uses em dashes, so keep them" | only allow: lifts the ban; the script would flag a kept dash and the fix pass would strip it anyway |
| "skip web research, the embedded list is good enough" | AI vocabulary shifts every 18 months; research:yes exists for a reason |
Red Flags
- You rewrote the text inline without dispatching
expert-naturalizer. - You asked the user to approve an analysis or the overwrite.
- You overwrote the file before
input.mdheld the original. - You ran the punctuation check on the change report instead of the rewrite.
- You over-edited a code block, table, or proper name.
- You left a
[SPECIFICITY NEEDED]marker in the text that replaces the user's file. - You added a citation, statistic, or named source that wasn't in the input.
- You passed the agent the profile's path outside the project instead of
voice.mdin the task folder. - You "improved" text that was already human-written.
Verification
Output a visible final block:
Naturalization complete.
Task dir: .mz/task/<task_name>/
Report: .mz/reports/<task_name>.md
Input: <source> (<words>)
Output: <words> (delta: <±N>%)
Patterns: <count broken>
Rhythm: burstiness <before> to <after> | length spread <before> to <after> (chat)
Voice: <register> from <profile> | none
Punctuation: clean | <N> lines left: <file:line list> | not run: <reason>
File update: yes (original at .mz/task/<task_name>/input.md) | no | n/a
If any phase is incomplete, print the blocker explicitly.
Error Handling
- Empty input →
AskUserQuestion. Never guess. @file:path does not exist → escalate via AskUserQuestion; offer alternatives.voice:profile missing or unreadable, or an unknownallow:name → AskUserQuestion before anything is written.- Input is binary or non-text → reject with explanation.
- Input >50KB → warn user and ask whether to proceed (long inputs may exceed context).
expert-naturalizerreturnsBLOCKED→ leave the user's file untouched, escalate.expert-naturalizerreturnsNEEDS_CONTEXT→ fill the missing context (e.g., preserve list), re-dispatch once.PUNCTUATION_CHECKexits 2 → recordPunctuationCheck: not runwith its stderr; the final block reports it.- Update
state.mdbefore and after every agent dispatch.
State Management
Update <PROJECT_ROOT>/.mz/task/<task_name>/state.md after each phase:
Status:pending|running|blocked|complete|aborted_by_user|failedPhase:0|1|2|completeInputSource:inline|file:<path>PreserveTerms:list of terms,[]when noneVoiceProfile:.mz/task/<task_name>/voice.md|noneAllowedPunctuation:list ofallow:names,[]when noneResearchRequested:yes|noFilesWritten:cumulative listPunctuationCheck:clean|concerns|not runFileUpdateApplied:yes|no|n/a(n/afor inline input)
State persists to .mz/task/<task_name>/state.md under the project root, ${MZ_MEMORY_ROOT:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}, resolved once at the start of the run. Schema is v2: line 1 is schema_version: 2; line 2 is Status: with one of pending, running, blocked, complete, aborted_by_user or failed, lowercase and unquoted; then Phase, Started, phase_complete (boolean) and what_remains (YAML list of strings), with skill-specific keys below them. Milestones go in Phase; the reason for blocked or failed goes in what_remains. Set phase_complete: false on phase entry and true once the phase's artifacts are written and its gates pass. Refresh what_remains on every phase transition; it is [] when Status is complete. Write the file after every phase and before every gate, and re-read it after compaction. Record decisions worth recalling under a heading that reads exactly ## Decisions, placed before ## Notes; mz-memory harvests them only once Status is complete. Under a heading that reads exactly ## Lessons, add one line whenever a review finding is accepted and fixed, a step fails, gate feedback corrects a mistake, or an approved approach is reversed, in the form - (review|failure|correction|change) WHEN <situation> → <what to do> — WHY <cause>, concrete and under about 40 words; mz-memory harvests lessons whatever the Status. Treat a legacy completed as complete. On reading a schema_version: 1 or unversioned file, put schema_version: 2 on line 1 and Status on line 2, add the missing keys, and log the upgrade. Leave a file with a higher schema_version untouched: ask whether to Restart (archive it), start New (_v2) or Abort, and stop if nobody can answer.
Never rely on conversation memory for cross-phase state.