Humanize Docs
Overview
This skill transforms robotic AI-generated documentation into prose that sounds like an actual human wrote it. Think: destroying checkbox spam, dismantling perfect paragraph structures, and injecting the kind of conversational flow you'd get from a colleague explaining something over coffee.
The approach is aggressive deformalization - not just tweaking tone, but fundamentally restructuring how information flows to break AI's predictable patterns.
When You Need This
Clear signals you're dealing with AI-generated docs:
- Checkbox overload:
- [x] Task 1: Do the thing (AC: #1) - CAPS LOCK emphasis for CRITICAL IMPORTANT NOTES
- 8+ code templates embedded in a single document
- Every section has exactly 3 perfectly balanced paragraphs
- Headers like "LLM Developer Guardrails" (literally instructions for robots)
- Phrases: "Certainly, here is...", "It's important to note that...", "Furthermore..."
Examples from the wild:
- AI agent documentation (like your Flutter Story example)
- Auto-generated API specs
- Claude Code project scaffolds
- ChatGPT-written technical guides
Transformation Workflow
Step 1: Detect AI Patterns
Before transforming, confirm you're actually dealing with AI output. Load the detection checklist:
[See references/detection-patterns.md for complete list]
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 → might already be human-written, be careful.
Step 2: Apply Core Transformations
Execute transformations in order. Each pattern targets specific AI signatures:
[See references/core-transformations.md for detailed rules]
Quick reference:
- Burstiness Injection → Mix 5-word punches with 30-word reflections
- Structure Dismantling → Break perfect 3-paragraph blocks, add digressions
- Checkbox Annihilation → Convert to flowing prose with "anyway, you'll need..."
- Template Contextualization → Replace code dumps with "here's what worked for me..."
- Vocabulary Swap → Kill "utilize/leverage/facilitate", use "use/use/help"
Critical rule: Don't apply all transformations everywhere. Humans are inconsistent - some sections stay formal, others get playful. That's the point.
Step 3: Quality Check
Read the output aloud (or mouth the words). 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 "casual robot"
- You removed personality instead of adding it
Good signals:
- Some sentences feel almost too casual (then you toned it back)
- You had to resist adding MORE jokes
- It reads faster than before
- You can hear a specific person's voice
Step 4: Domain Adjustments (Optional)
Different doc types need different intensity levels:
High personality OK:
- READMEs for open source projects
- Internal team documentation
- Tutorial blog posts
- Onboarding guides
Moderate personality:
- API documentation
- User-facing help docs
- Technical specifications
Gentle touch only:
- Legal/compliance docs (seriously, be careful)
- Medical/safety documentation
- Financial reports
[See references/examples-gallery.md for before/after samples]
Quick Mode (30 seconds)
If you 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 → italics with context
- Add one burstiness break → throw in a 5-word sentence after a long paragraph
- Swap 3-5 AI vocabulary words → utilize→use, leverage→use, facilitate→help
Done. Not perfect, but 70% better readability.
Examples
Input (AI-generated):
## Task 2: Configure Dependencies
**CRITICAL**: The following steps MUST be completed in order.
- [x] Install package A (required for Task 3)
- [x] Verify installation with command X
- [x] Proceed to next task only after confirmation
It is important to note that failure to follow these steps will result in errors.Output (Humanized):
## Setting Up Dependencies
Okay, you'll need to install package A first - and yeah, this actually matters because
Task 3 depends on it. Run command X to verify it worked.
Once you get the confirmation, you're good to move on. If it errors out, the next step
will definitely break, so... don't skip this.Notice:
- Checkbox death ✅
- "Okay" intro (conversational)
- Sentence length variation (short → long → medium)
- "yeah, this actually matters" (human aside)
- "so... don't skip this" (trailing thought)
- Kept the warning but made it sound real
Common Mistakes
Don't:
- Remove ALL structure (humans still use headers)
- Make everything casual (inconsistency is human)
- Add emojis (that's a different kind of AI spam)
- Force humor (spontaneous > trying hard)
- Ignore domain context (legal docs stay formal)
Do:
- Vary your transformation intensity
- Keep some sections more formal for contrast
- Read aloud to check naturalness
- Preserve technical accuracy above all
- Trust your instinct on "too much"
References
This skill uses reference documentation loaded into context:
core-transformations.md
The 5 core transformation patterns with detailed rules, examples, and edge cases. Load this for complex transformations or when you need to understand WHY a pattern works.
detection-patterns.md
Complete AI signature checklist with detection heuristics. Load when you're unsure if a doc needs transformation or want to explain what makes text feel "AI-generated".
examples-gallery.md
Before/after transformation showcase across different document types (technical guides, READMEs, API docs). Load for inspiration or to calibrate transformation intensity.
advanced-techniques.md
Future: Domain-specific adjustments for legal, academic, and specialized documentation.
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 probably sound professional. Capture that tension.