Post-processing rewrite skill that transforms dense LLM-generated documentation
into scannable, concise, human-readable text. Covers vocabulary tics, structural
anti-patterns, BLUF rewriting, and word-level editing.
Use when other skills need to produce user-facing prose: READMEs, guides,
tutorials, or commit messages. Loaded by other skills as a post-processing
step — not a standalone command.
Standardmäßig ist der Prompt ausgewählt, der zuerst die Quelle prüft. Sie können zu einem direkten Befehl wechseln oder eine lokale Kopie herunterladen.
Quelldateien prüfen
Lesen Sie SKILL.md und alle von SkillsMP angezeigten Begleitdateien, bevor Sie sich für eine Installation entscheiden.
Mit Codex oder Claude installieren Kopieren Sie diesen Prompt, fügen Sie ihn in Codex, Claude oder einen anderen Assistant ein und lassen Sie die Skill-Seite prüfen und installieren.
Ein direkter Befehl überspringt den Prüf-Prompt. Prüfen Sie die Quelle, bevor Sie ihn ausführen.
Post-processing rewrite skill that transforms dense LLM-generated documentation
into scannable, concise, human-readable text. Covers vocabulary tics, structural
anti-patterns, BLUF rewriting, and word-level editing.
Use when other skills need to produce user-facing prose: READMEs, guides,
tutorials, or commit messages. Loaded by other skills as a post-processing
step — not a standalone command.
Writing for Humans
Rewrite LLM-generated documentation into text humans actually read.
Do not apply to: Code comments, internal specs, handoffs, research documents, API docs generated from code, non-prose output (JSON, YAML, config files).
Integration Pattern
Other skills load this as a post-processing step. The calling skill produces a draft, then a sub-agent rewrites it and gates the result through the automated validation loop (Phase 6) before returning. Use a sub-agent with Bash access (for example general-purpose) so the loop can run the detector.
Task tool:
subagent_type: general-purpose
description: "Rewrite draft for readability"
prompt: |
Read: ~/.claude/skills/writing-for-humans/SKILL.md
Rewrite the following text using the writing-for-humans methodology,
then run the Phase 6 validation loop until the text passes the gate
(or the loop bails out). Return ONLY the final rewritten text —
no meta-commentary, no explanations. If any hits remain after bailout,
append a one-line note listing them.
---
[paste draft here]
Core Principles
Six rules that drive every rewrite decision:
79% scan, 21% read — Most readers scan. Front-load key information. Use headings, bold, and lists as scan anchors.
7 plus/minus 2 chunks — Group related items into 5-9 chunks. Split longer lists into categorized sub-lists.
BLUF (Bottom Line Up Front) — Lead with the conclusion, recommendation, or action. Context follows.
Active voice — The subject acts. "The server processes requests" not "Requests are processed by the server."
Show, don't tell — Replace claims with evidence. "Reduces build time by 40%" not "Significantly improves performance."
Concrete over abstract — Use specific numbers, names, and examples instead of vague qualifiers.
Quick Diagnostic Checklist
Scan the text for these issues before rewriting. Mark the top 3 to fix first.
Reverse nominalizations — "make an improvement" becomes "improve". "perform an analysis" becomes "analyze".
Split long sentences — Break sentences over 25 words at natural clause boundaries.
Cut hedging — Remove "basically", "essentially", "it's worth noting that". State the fact directly.
Phase 4: Formatting
Apply visual hierarchy:
Use markdown — Bold for key terms on first use. Code formatting for technical names.
Add headings — One heading per scroll-height (~300 words). Make headings specific and actionable.
Use whitespace — Separate sections with blank lines. Short paragraphs (2-4 sentences max).
Prefer tables for comparisons — Side-by-side data reads faster than prose descriptions.
Phase 5: Validation
Check the rewrite against these criteria:
30-50% shorter than original (word count)
Passes skim test: read only headings and bold text — do you get the gist?
No banned words or phrases remain
80%+ of sentences use active voice
No paragraph exceeds 4 sentences
No list exceeds 9 items without categorization
Every heading is specific (not "Overview" or "Details")
Phase 5 is the human-judgment pass. Phase 6 adds an automated gate on top of it.
Phase 6: Automated Validation
Gate the rewrite through scripts/validate.sh and loop on its output until the text passes. See Automated Validation Loop for the procedure.
Automated Validation Loop
Run this after Phase 5, inside the rewrite sub-agent (it has Bash). Validation runs fully locally — no text leaves the machine.
scripts/validate.sh <file> (in this skill's directory) gates a draft against two local detectors — ai-slop and ai-writing-detector — combined with OR: it fails if either flags the text, and skips only when neither is available. It reports one of three states:
Exit
Meaning
Action
0
Passes the gate
Done — return the text
1
Still reads as AI-generated
stdout lists the specific issues — fix those spans, rerun
2
Cannot validate — no detector available, bad input, or detector error
Skip; keep the Phase 5 result and note validation did not run
Prerequisites
Both detectors are optional and checked at run time: if one is absent the gate uses the other, and if both are absent validation is skipped — never failed. Install each manually, once — the script never auto-installs.
ai-slop — put it on your PATH (see the tool's own docs).
ai-writing-detector (pertrai1/ai-writing-detector) — not published as a package, so build from source pinned to a reviewed commit SHA, then point the script at the built CLI:
git clone https://github.com/pertrai1/ai-writing-detector
cd ai-writing-detector && git checkout <reviewed-sha>
npm install && npm run build
export AI_WRITING_DETECTOR_CLI="$PWD/dist/cli.js"
It runs fully locally with no network calls. Pin to a SHA, not main, and review the build before running it.
The loop
Write the current draft to a temp file under the session scratchpad.
Run scripts/validate.sh <tmpfile> and capture stdout and the exit code.
Exit 0 → done. Return the text.
Exit 1 → read the reported issues, edit exactly those spans using the replacement guidance above, rewrite the temp file, and repeat.
Exit 2 → skip the loop, keep the Phase 5 result, and note validation did not run. Never fail the rewrite because the detector could not run.
Tune strictness with the SLOP_THRESHOLD and AI_WRITING_THRESHOLD env vars documented in the script header.
Bailout
Stop and return the best version — never distort meaning to satisfy the detector:
Cap the loop at 5 iterations.
Stop early if the issues stop shrinking between iterations.
Stop if the only remaining issues are tokens the text must keep (a real em-dash, a required emoji, a quoted AI phrase).
On bailout, report the residual issues instead of forcing more edits. The detector is a guide, not an oracle — human meaning wins over a green score.
Governance
Treat scores as guidance. The gate flags likely tells; it does not certify quality. Human judgment overrides it.
Banned Words and Phrases
Remove or replace every instance:
Single Words
delve
leverage (use "use" or "apply")
robust (use specific quality: "tested", "validated", "fault-tolerant")
comprehensive (use "complete" or "full", or cut entirely)
streamline (use "simplify" or "speed up")
utilize (use "use")
facilitate (use "help" or "enable")
moreover
furthermore
nonetheless
paradigm
synergy
optimize (unless discussing actual performance optimization)
empower
foster
holistic
innovative
seamless (use "smooth" or describe the actual behavior)
Phrases
"It's important to note that" — delete entirely, state the fact
"In order to" — replace with "To"
"At the end of the day" — delete
"It goes without saying" — delete (then why say it?)
"As a matter of fact" — delete
"For all intents and purposes" — delete
"In terms of" — replace with "for" or restructure
"With regard to" — replace with "about" or "for"
"On the other hand" — replace with "But" or "However"
"Due to the fact that" — replace with "Because"
"In the event that" — replace with "If"
"Prior to" — replace with "Before"
"Subsequent to" — replace with "After"
"A wide range of" — replace with "many" or a specific number
"In a timely manner" — replace with "quickly" or a specific timeframe
"Take into consideration" — replace with "consider"
"Is able to" — replace with "can"
"Has the ability to" — replace with "can"
Word Replacement Table
Replace
With
utilize
use
facilitate
help
implement
build, add, set up
functionality
feature
in order to
to
due to the fact that
because
at this point in time
now
a large number of
many
in the event that
if
prior to
before
subsequent to
after
in terms of
for, about
with regard to
about
has the ability to
can
is able to
can
take into consideration
consider
make a determination
decide
give consideration to
consider
provide assistance
help
conduct an investigation
investigate
perform an analysis
analyze
come to a conclusion
conclude
Before/After Examples
Example 1: Feature Description
Before (87 words):
It's important to note that this comprehensive authentication module has been designed to facilitate secure user access management across a wide range of application contexts. The module utilizes industry-standard JWT tokens in order to provide robust session handling. Moreover, it leverages Redis for session storage, which enables the system to seamlessly handle distributed deployments. The implementation provides the ability to configure token expiry, refresh intervals, and role-based access controls in a highly flexible manner.
After (32 words — 63% reduction):
This auth module manages user sessions with JWT tokens stored in Redis. Configure token expiry, refresh intervals, and role-based access per environment. Works across distributed deployments.
What changed:
BLUF: led with what it does, not that it's "important to note"
Cut "comprehensive", "robust", "seamlessly", "in order to", "facilitates"
Replaced "utilizes" with implicit usage, "provides the ability to" with direct verb
Removed "moreover" transition — unnecessary between related facts
Example 2: Setup Instructions
Before (94 words):
In order to get started with the development environment setup, you'll first need to ensure that you have Docker installed on your machine. It's worth mentioning that the minimum required version is 20.10 or later. Subsequently, you should proceed to clone the repository and navigate to the project directory. At that point, you'll want to run the initialization script, which will take care of pulling the necessary images, setting up the database, and configuring the environment variables. Once this process has been completed, you should be able to access the application.
After (38 words — 60% reduction):
Prerequisites: Docker 20.10+
git clone <repo-url> && cd project
./scripts/init.sh
init.sh pulls images, creates the database, and sets environment variables. The app is available at localhost:3000 after setup.
What changed:
BLUF: prerequisites first, then the commands
Replaced prose with a code block — readers copy commands, not sentences
Cut "in order to", "it's worth mentioning", "subsequently", "at that point"
Replaced "once this process has been completed" with specific result
Output Format
Return only the rewritten text. Do not include:
Explanations of what you changed
Before/after comparisons
Meta-commentary about the rewrite process
Confidence scores or caveats
If the original text is already concise and scannable, return it unchanged with no comment.
