humanize-docs

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:

• Install package A (required for Task 3)
• Verify installation with command X
• Proceed to next task only after confirmation

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:

1. Kill the checkboxes — flowing list with "you'll need: X, Y, and Z"
2. Replace one CAPS LOCK section with italics + context
3. Add one burstiness break — a 5-word sentence after a long paragraph
4. 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)