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.

• Install package A (required for Task 3)
• Verify installation with command 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.