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
npx skills add wrg32786/aigent-os --skill humanize-docs -a claude-codeWhat 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-code2Manually: put the files in place
~/.claude/skills/humanize-docs/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/humanize-docs/
1Skills CLI (Vercel)
npx skills add wrg32786/aigent-os --skill humanize-docs -a codex2Manually: put the files in place
.agents/skills/humanize-docs/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add wrg32786/aigent-os --skill humanize-docs -a cursor2Manually: put the files in place
.cursor/skills/humanize-docs/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install wrg32786/aigent-os skills/humanize-docs2Manually: put the files in place
.github/skills/humanize-docs/SKILL.md1Skills CLI (Vercel)
npx skills add wrg32786/aigent-os --skill humanize-docs -a gemini-cli2Platform CLI
gemini skills install https://github.com/wrg32786/aigent-os --path skills/humanize-docsManually: put the files in place
.devin/skills/humanize-docs/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add wrg32786/aigent-os --skill humanize-docs -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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