| name | humanize-docs |
| version | 1.0.0 |
| description | Transform AI-generated documentation into human-readable prose with personality.
USE WHEN: Converting rigid AI docs (checklist spam, CAPS LOCK emphasis, perfect symmetric
structures, template dumps) into flowing, conversational writing that feels colleague-authored.
Different from /humanizer — that skill detects AI writing patterns (Wikipedia taxonomy).
This skill does aggressive deformalization of document structure and flow.
PRIMARY TRIGGERS: "humanize this doc", "make this readable", "remove AI patterns from doc",
"add human touch to this"
See also: humanizer skill for text-level AI pattern removal.
|
| license | MIT |
| compatibility | claude-code opencode |
| source | https://github.com/skillkit-marketplace/skills/tree/main/skills/humanize-docs |
| allowed-tools | ["Read","Write","Edit","Glob"] |
Humanize Docs
Transforms robotic AI-generated documentation into prose that sounds like an actual human wrote it. The approach is aggressive deformalization — not just tweaking tone, but restructuring how information flows to break AI's predictable patterns.
This is a different tool than the humanizer skill. Humanizer removes AI writing tells at the sentence/phrase level (em-dashes, rule-of-three, vague attributions, sycophantic openers). Humanize-docs attacks structural AI-ness: checkbox spam, template overload, perfect symmetry, emotional flatness across an entire document.
When to use this
Clear signals you're dealing with AI-generated docs:
- Checkbox overload:
- [x] Task 1: Do the thing (AC: #1)
- CAPS LOCK for CRITICAL IMPORTANT NOTES
- 8+ code templates embedded in one document
- Every section has exactly 3 perfectly balanced paragraphs
- Headers like "LLM Developer Guardrails"
- Phrases: "Certainly, here is...", "It's important to note that...", "Furthermore..."
Transformation workflow
Step 1: Detect
Quick test — does the doc have 5+ of these?
- Perfect structural symmetry (every section same length)
- Zero sentence length variation (all 15-20 words)
- Checkbox addiction
- Template embedding mania
- Emotional flatness (no "wait, why?" or "honestly...")
If yes, proceed. If no, it might already be human-written — don't over-transform.
Step 2: Apply the five core transformations
Execute in order. Don't apply all of them everywhere — humans are inconsistent. Some sections stay formal, others get playful. That asymmetry is the point.
1. Burstiness injection
Mix 5-word punches with 30-word reflections. AI writes at one rhythm. Humans don't.
Before:
The system processes requests through a standardized pipeline that validates inputs and returns structured responses to the calling service.
After:
It's a pipeline. Request comes in, gets validated, structured response goes back out. Nothing exotic — but the validation step is where things quietly break.
2. Structure dismantling
Break perfect 3-paragraph blocks. Add digressions. Not every section needs the same shape.
3. Checkbox annihilation
Convert checklists to flowing prose with "anyway, you'll need..." or "first thing is..."
Before:
After:
Install package A first — Task 3 depends on it. Run command X to verify it worked. Once you get confirmation, move on. If it errors out, the next step breaks, so don't skip this.
4. Template contextualization
Replace code dumps with "here's what worked for me..." framing. Give the template a reason to exist before showing it.
5. Vocabulary swap
Kill: utilize, leverage, facilitate, ensure, enable, enhance, robust, seamless
Use: use, use, help, make sure, let, improve, solid, smooth
Step 3: Quality check
Read the output aloud. Does it sound like you'd actually say this to someone?
Red flags the transformation failed:
- Still too even (every paragraph same vibe)
- No variation in sentence rhythm
- Feels like a "professional robot" instead of a person
- You removed personality instead of adding it
Good signals:
- Some sentences feel almost too casual (then you toned it back)
- It reads faster than before
- You can hear a specific person's voice
Step 4: Domain calibration
Intensity varies by doc type:
| Doc type | Intensity |
|---|
| READMEs, internal team docs, onboarding guides, tutorials | High |
| API docs, help docs, technical specs | Moderate |
| Legal, compliance, medical, financial | Gentle only |
Quick mode (30 seconds)
Just need to make something readable without full transformation:
- Kill the checkboxes — flowing list with "you'll need: X, Y, and Z"
- Replace one CAPS LOCK section with italics + context
- Add one burstiness break — a 5-word sentence after a long paragraph
- Swap 3-5 AI vocabulary words (utilize→use, leverage→use, facilitate→help)
Not perfect, but 70% better readability.
Common mistakes
Don't:
- Remove ALL structure (humans still use headers)
- Make everything casual (inconsistency is human)
- Add emojis
- Force humor
- Ignore domain context
Do:
- Vary transformation intensity across sections
- Keep some sections more formal for contrast
- Read aloud to check naturalness
- Preserve technical accuracy above all
Philosophy
AI writes like it's afraid to break rules. Humans write like they're explaining something to a friend while occasionally remembering they should sound professional. Capture that tension.
Related skills
- humanizer — sentence/phrase level AI pattern removal (Wikipedia taxonomy, 29 rules)
