Skip to main content
skill CX Codex

humanize-docs — Claude Code skill: what it does, how to install

humanize-docs is a Claude Code skill that transforms robotic documentation into natural prose. It rewrites technical docs and README files by removing repetitive checklists and rigid section structures.

MIT ★ 26 updated 2026-11-16

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add wrg32786/aigent-os --skill humanize-docs -a claude-code
Open on GitHub

What humanize-docs does

Restructures technical documentation, manuals, and README files to strip away predictable AI formatting artifacts. Unlike basic phrasing tweaks, this tool targets document architecture: rigid paragraph symmetry, endless checkbox lists, and out-of-place code snippet dumps.

Operating via Read, Write, Edit, and Glob tools, it runs a five-phase workflow: introducing varied sentence pacing, breaking identical section structures, rewriting checkboxes into natural steps, adding rationale before code blocks, and replacing stiff verbs like utilize with plain speech. Transformation intensity adjusts per document type, keeping compliance text gentle while rewriting guides and team wikis aggressively.

What it helps with

  • rewrite monotonous checklist spam into conversational step-by-step prose
  • break identical section layouts and vary sentence rhythm
  • swap robotic buzzwords for straightforward language
  • calibrate documentation tone across API specs and team guides

Example prompts for the agent

  • Rewrite README.md to make the explanations sound natural
  • Remove checkbox spam and robotic phrasing from our onboarding doc
  • Break the rigid structure of this technical guide without losing accuracy

How to install humanize-docs

1Skills CLI (Vercel)

npx skills add wrg32786/aigent-os --skill humanize-docs -a claude-code

2Manually: put the files in place

~/.claude/skills/humanize-docs/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/humanize-docs/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about humanize-docs

How to install humanize-docs in Claude Code?

Run npx skills add wrg32786/aigent-os --skill humanize-docs -a claude-code. The skill file installs to ~/.claude/skills/humanize-docs/SKILL.md.

How does humanize-docs differ from sentence humanizers?

Standard humanizers target phrasing and micro-patterns. This skill addresses macro-level documentation flaws by removing checklist spam, breaking paragraph symmetry, and contextualizing code dumps.

What is required to run humanize-docs?

No third-party accounts or API credentials are required. The skill relies entirely on standard filesystem tools: Read, Write, Edit, and Glob.

Source text

SKILL.md · MIT
---
name: humanize-docs
version: 1.0.0
description: "Rewrite AI documentation structure and flow into conversational prose. Use when humanizing docs, removing checklist spam, or making rigid documents readable."
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:
> - [x] Install package A (required for Task 3)
> - [x] Verify installation with command X
> - [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)

© wrg32786 · MIT · wrg32786/aigent-os

Similar skills

All skills for Writing and docs →

From the same set58

The whole set →
memory-bridge The memory-bridge Claude Code skill connects explicit memory requests to Hindsight and Jev. Ask it to retain, recall, or reflect on a note to trigger the bridge. CX Codex +1 ★ 26repo stars Learn The Learn Claude Code skill turns research on a repo, talk, or tool into a structured note. It records an assessment and, for HOLD decisions, a condition for reviewing it again. CX Codex +1 ★ 26repo stars learn-from-failure The learn-from-failure Claude Code skill classifies failures and checks whether their causes have appeared before. Repeated problems lead to a durable artifact meant to prevent another recurrence. CX Codex +1 ★ 26repo stars impeccable The impeccable Claude Code skill guides frontend design, helps establish a project’s visual direction, and can extract components and design tokens. It needs context about users, their tasks, and the brand’s tone. CX Codex +1 ★ 26repo stars Honesty Check The Honesty Check Claude Code skill builds an honesty ledger for completed work. It runs before an agent reports a task as done or prepares it for review. CX Codex +1 ★ 26repo stars first-win This Claude Code skill offers three starter tasks that end with a usable artifact. Run /first-win to turn a post into social content, shape an idea into a plan, or sort email into priorities. CX Codex +1 ★ 26repo stars First 10 Moves First 10 Moves — a Claude Code skill for exploring an unfamiliar repository before changing code. It starts when a task involves tracing a bug, locating a module, or finding a place to begin. CX Codex +1 ★ 26repo stars find-weakness find-weakness — a skill for Claude Code and Codex isolates the single strongest objection and the riskiest unstated assumption in any architectural choice or claim. CX Codex +1 ★ 26repo stars

Project sponsors

Companies that keep this analytics open