# How the Humanizer Agent Skill Rewrites AI‑Sounding Text: A Complete Technical Breakdown

> Discover how the Humanizer agent skill transforms AI text into natural prose. Explore its four-stage pipeline: marking, drafting, validating, and producing human-like text without altering facts. Learn the technical details.

- Repository: [Siqi Chen/humanizer](https://github.com/blader/humanizer)
- Tags: deep-dive
- Published: 2026-09-07

---

**Humanizer removes robotic "AI‑telling" patterns through a four‑stage pipeline that marks suspicious phrases, drafts a rewrite, validates the result, and produces final natural‑sounding prose—without adding or removing any facts.**

The open‑source `blader/humanizer` repository provides a pure‑Markdown **agent skill** designed to strip artificiality from machine‑generated text. Unlike traditional text‑processing libraries, Humanizer contains no runtime code—its entire behavior lives in [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md), making it portable across any agent platform that supports Markdown‑based skills.

## How Humanizer Detects and Removes AI Patterns

The core innovation of Humanizer lies in its **pattern‑driven detection system**. According to [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md), the skill maintains a curated list of 25 "tells" derived from Wikipedia's research into signs of AI writing. Each pattern specifies a **watch phrase**, the **problem it causes**, and **before/after examples** that guide the rewrite.

### The Four‑Stage Processing Pipeline

Humanizer processes every input through these sequential steps:

1. **Mark the tells** — Scans input for all 25 patterns (e.g., "not‑X‑but‑Y" constructions, one‑line closers, forced triads, dash abuse, overused AI words). Strongest matches are prioritized.

2. **Draft the rewrite** — Generates a new version that may shorten dull passages, merge or split paragraphs, and restructure sentences. **New facts are never introduced**—only existing information is reshaped.

3. **Check the draft** — The draft is conceptually "read aloud" and re‑scanned against the pattern list. Remaining AI‑sounding fragments are removed, and factual integrity is verified.

4. **Write the final version** — Delivers natural‑sounding prose that retains the original information and voice.

This workflow is documented in the "How to work" section of [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md)【[SKILL.md – How to work](https://github.com/blader/humanizer/blob/main/SKILL.md#how-to-work)】.

## Key AI‑Telling Patterns Humanizer Targets

The pattern list addresses recurring artifacts of large language model output. While the full 25 patterns reside in [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md), representative categories include:

- **Structural tells**: Forced triads ("first, second, third"), predictable paragraph rhythms, one‑line closing statements
- **Rhetorical tells**: "Not X but Y" framing, unnecessary hedging, excessive signposting
- **Stylistic tells**: En‑dash and em‑dash abuse, overused AI vocabulary ("delve," "leverage," "tapestry")
- **Pacing tells**: Uniform sentence lengths, mechanical transitions, absence of natural variation

Each pattern includes concrete **before/after examples** that train the underlying agent on what to eliminate and how to reconstruct the thought.

## Operating Modes and Usage Patterns

Humanizer adapts to three distinct workflows, as documented in [`README.md`](https://github.com/blader/humanizer/blob/main/README.md)【[README.md – Usage](https://github.com/blader/humanizer/blob/main/README.md#usage)】:

| Mode | Trigger | Output |
|------|---------|--------|
| **Interactive** | `/humanizer` command with pasted text | Draft → critique → final rewrite |
| **File mode** | `Humanize the prose in [filepath]` | Rewritten prose only; code, YAML, and links preserved |
| **Embedded** | API call from another tool | Final text only, no intermediate steps |

### File Mode Preserves Technical Content

When processing documents, Humanizer distinguishes prose from structured content. In [`docs/launch-post.md`](https://github.com/blader/humanizer/blob/main/docs/launch-post.md) or similar files, the skill rewrites only natural‑language passages while leaving code blocks, front‑matter, URLs, and data structures intact.

## Voice Matching for Consistent Tone

Humanizer supports **adaptive voice calibration**. As described in [`README.md`](https://github.com/blader/humanizer/blob/main/README.md)【[README.md – Match your voice](https://github.com/blader/humanizer/blob/main/README.md#match-your-voice)】, users can supply a writing sample to align the rewrite with their established rhythm, word choice, punctuation habits, and dash usage.

### Voice Matching Workflow

```

/humanizer

Here's a sample of my writing for voice matching:
[2–3 paragraphs demonstrating your style]

Now humanize this text:
[AI‑sounding content to rewrite]

```

The output mirrors the supplied sample's cadence rather than defaulting to generic "human‑like" prose.

## Practical Implementation Examples

### Basic Interactive Session

```text
/humanizer

The rapid advancement of artificial intelligence technologies has 
fundamentally transformed numerous industries, not merely enhancing 
efficiency but redefining the very nature of work itself.

```

*Result*: Humanizer returns the draft rewrite, a bullet list of removed tells (e.g., "not‑X‑but‑Y construction," "abstract triad"), and the finalized version.

### Embedded API Integration

```bash
curl -X POST https://api.agent.com/execute \
  -d '{"skill":"humanizer","input":"..."}'

```

When called programmatically, the skill returns **only the final rewritten text**—suitable for automated PR descriptions, commit messages, or documentation pipelines.

## Architectural Characteristics

| Aspect | Implementation |
|--------|----------------|
| **Runtime** | None—pure Markdown prompt |
| **Configuration** | [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) contains patterns and logic |
| **Portability** | Any agent loading Markdown skills |
| **Extensibility** | Pattern list editable in [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) |

The entire behavior is expressed through the Markdown specification in [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md). This eliminates dependency management, version conflicts, or environment‑specific failures common to traditional software libraries.

## Source File Reference

| File | Purpose |
|------|---------|
| [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) | Core prompt with 25‑pattern list, four‑stage pipeline, and rewrite logic |
| [`README.md`](https://github.com/blader/humanizer/blob/main/README.md) | Installation, usage modes, and voice‑matching instructions |
| [`AGENTS.md`](https://github.com/blader/humanizer/blob/main/AGENTS.md) | Platform integration metadata for Claude, OpenAI, and other agents |

## Summary

- Humanizer operates as a **pure‑Markdown skill** with no executable code—behavior is defined entirely in [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md).

- The **four‑stage pipeline** (mark tells → draft → check → finalize) systematically strips AI artifacts while preserving factual content.

- **25 detection patterns** target structural, rhetorical, stylistic, and pacing tells common to machine‑generated text.

- **Three operating modes** (interactive, file, embedded) adapt the skill to manual editing, document processing, and automated workflows.

- **Voice matching** enables style‑consistent rewrites aligned to user‑provided writing samples.

## Frequently Asked Questions

### What makes Humanizer different from other AI text detectors?

Unlike classifiers that merely flag AI‑generated content, Humanizer **actively rewrites** the text to remove robotic patterns. It operates entirely through prompt engineering in [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) rather than trained models or heuristics, making it inspectable and modifiable.

### Can Humanizer change the meaning of my text?

No. The skill is explicitly constrained to **never add new facts** during rewriting. The "check the draft" stage verifies factual integrity before producing the final version. Only structure, rhythm, and word choice are modified.

### How do I customize which patterns Humanizer targets?

Edit the pattern list in [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md). Each pattern includes a watch phrase, problem description, and before/after examples. Adding, removing, or adjusting these entries changes the skill's detection and rewrite behavior across all modes.

### Does Humanizer work with code or only prose?

Humanizer processes **natural‑language prose only**. In file mode, it automatically preserves code blocks, YAML front‑matter, links, and data structures—rewriting only the human‑readable text surrounding them.