# How Humanizer Rewrites AI Text to Sound Human: Inside the Prompt-Only Skill

> Discover how Humanizer rewrites AI text to sound human. This prompt-only skill uses 35 linguistic patterns to transform AI prose into natural writing, preserving all facts.

- Repository: [Siqi Chen/humanizer](https://github.com/blader/humanizer)
- Tags: how-to-guide
- Published: 2026-09-04

---

**Humanizer is a prompt-only skill that encodes 35 linguistic patterns into a structured rewrite guide, enabling any LLM to detect AI-generated prose and transform it into natural human writing while strictly preserving every factual claim.**

The `blader/humanizer` repository implements a unique approach to rewrite AI text to sound human without relying on executable code or external dependencies. Instead, the entire engine lives inside [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md), where expert-curated rewrite rules instruct large language models how to identify and eliminate artificial-sounding phrasing while maintaining strict factual integrity.

## The Three-Layer Architecture of Humanizer

According to the source code in `blader/humanizer`, the skill is organized into three distinct layers that work together to process text through pure prompt engineering.

### Metadata and Pattern Catalogue (SKILL.md)

The foundation of Humanizer resides in [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) (lines 1-11), which declares the skill’s purpose, version, and license. Below the header, lines 48-86 enumerate **35 concrete patterns** derived from Wikipedia’s *Signs of AI writing*. Each pattern entry includes:

- **"Words to watch"**: Specific vocabulary cues that signal AI generation
- **Problem description**: Why the pattern sounds artificial
- **Before/after examples**: Concrete transformations showing the fix

These patterns cover linguistic artifacts such as inflated claims, sales language, passive voice overuse, forced groups of three, and overused bold text formatting.

### The Four-Step Rewrite Process

As defined in [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) (lines 41-50), Humanizer follows a strict procedural loop when invoked:

1. **Detect**: Scan the input for every pattern from the catalogue using text-search heuristics (e.g., "-ing" phrases, structural cues)
2. **Draft**: Generate a rewrite that removes detected patterns while preserving every factual claim, name, date, and citation
3. **Validate**: Apply two sanity-check questions—"Is this still AI-like?" and "Were any facts lost or added?"
4. **Emit**: Return the final version according to the selected **output mode** (pasted text, file mode, or embedded mode)

## How the Humanizer Engine Processes Text

The "engine" is not a compiled binary but rather the LLM itself executing the rules encoded in the skill prompt. However, the source code defines specific behavioral constraints that govern the rewrite process.

### Pattern Matching and "Words to Watch"

Humanizer performs **pure text-search** pattern matching without external libraries. The engine scans for defined "words to watch" and structural cues such as excessive adjectives, hedging language, and mechanical transitions. When [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) is loaded, the LLM uses these explicit signposts to flag sections requiring intervention.

### Strict Fact Preservation Constraints

A core constraint enforced by the skill prohibits adding, removing, or altering any claim, name, date, or citation. If a proposed rewrite would change a factual element, the engine must either:
- Retain the original wording for that specific claim, or
- Request user clarification before proceeding

This ensures that humanizing the prose never compromises content accuracy.

### Voice Alignment and Output Modes

When users supply writing samples, Humanizer first analyzes sentence length, punctuation style, and lexical quirks, then mirrors those habits in the output. The skill supports three output modalities defined in the rewrite process:
- **Pasted text**: Returns rewritten prose with a short pattern checklist
- **File mode**: Returns only the cleaned text for file-write operations
- **Embedded mode**: Integrates directly into agent workflows

## Practical Implementation Examples

The repository provides integration points for multiple LLM platforms through configuration files rather than compiled SDKs.

### Claude Plugin Integration (.claude-plugin/plugin.json)

For Claude desktop users, the plugin manifest at [`.claude-plugin/plugin.json`](https://github.com/blader/humanizer/blob/main/.claude-plugin/plugin.json) points directly to [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md):

```json
{
  "name": "humanizer",
  "description": "Rewrite AI‑sounding text so it reads naturally.",
  "path": "SKILL.md"
}

```

**Prompt to Claude:**

```

Humanizer, please rewrite the following paragraph:

> The Statistical Institute of Catalonia was officially established in 1989, marking a pivotal moment in the evolution of regional statistics in Spain. This initiative was part of a broader movement across Spain to decentralize administrative functions and enhance regional governance.

```

**Result:**

> The Statistical Institute of Catalonia was established in 1989, part of a wider decentralization of administrative functions in Spain.

### OpenAI Function Calling (agents/openai.yaml)

The [`agents/openai.yaml`](https://github.com/blader/humanizer/blob/main/agents/openai.yaml) file and supporting documentation show how to invoke Humanizer through OpenAI's function calling interface:

```python
import json, openai

messages = [
    {"role":"system","content":"You are Claude with the Humanizer skill loaded."},
    {"role":"user","content":"Humanizer, rewrite this text:\n\n"
                                 "Her views have been cited in The New York Times, BBC, Financial Times, and The Hindu. "
                                 "She maintains an active social media presence with over 500,000 followers."}
]

response = openai.ChatCompletion.create(
    model="gpt-4o",
    messages=messages,
    functions=[{
        "name":"humanizer",
        "description":"Rewrite AI‑generated prose to sound human.",
        "parameters":{"type":"object","properties":{"text":{"type":"string"}}}
    }],
    function_call={"name":"humanizer","arguments":"{\"text\":\"...\"}"}
)
print(json.dumps(response, indent=2))

```

**Result:**

> Her views have been cited in *The New York Times* and the *BBC*.

### Direct Skill Invocation

Any LLM capable of loading the skill format can invoke Humanizer using XML-style tags:

```

<skill:humanizer>

The temple's color palette of blue, green, and gold resonates with the region's natural beauty, symbolizing Texas bluebonnets, the Gulf of Mexico, and the diverse Texan landscapes, reflecting the community's deep connection to the land.

</skill>

```

**Humanizer’s output:**

> The temple is painted blue, green, and gold, colors meant to evoke Texas bluebonnets and the Gulf of Mexico.

## Summary

- **Prompt-only architecture**: Humanizer contains no executable code; the entire engine lives within [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md), making it portable across any LLM that supports skill loading.
- **35 linguistic patterns**: The skill encodes specific anti-patterns derived from Wikipedia’s *Signs of AI writing*, including inflated claims, passive voice, and mechanical structure.
- **Four-step rewrite process**: Detect patterns, draft rewrites, validate for factual integrity and naturalness, then emit in the requested output mode.
- **Strict fact preservation**: The engine cannot add, remove, or alter factual claims, names, dates, or citations during the humanization process.
- **Cross-platform support**: Integration files like [`.claude-plugin/plugin.json`](https://github.com/blader/humanizer/blob/main/.claude-plugin/plugin.json), [`agents/openai.yaml`](https://github.com/blader/humanizer/blob/main/agents/openai.yaml), and [`AGENTS.md`](https://github.com/blader/humanizer/blob/main/AGENTS.md) enable deployment across Claude, OpenAI, and other agent frameworks.
- **Validation tooling**: The [`scripts/validate-package.py`](https://github.com/blader/humanizer/blob/main/scripts/validate-package.py) script ensures packaged skills adhere to repository standards before distribution.

## Frequently Asked Questions

### How does Humanizer detect AI-generated text without machine learning models?

Humanizer uses **text-search heuristics** defined in [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) to scan for "words to watch" and structural cues such as "-ing" phrases, forced groups of three, and overused bold formatting. This is a deterministic pattern-matching approach that requires no external libraries or training data, relying entirely on the LLM's ability to execute the encoded rules.

### Can Humanizer add new facts or remove existing ones during rewriting?

No. The skill enforces a strict constraint against altering factual content. According to the rewrite process defined in [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) (lines 41-50), the engine must preserve every claim, name, date, and citation. If a rewrite would change a fact, the system either retains the original phrasing or prompts the user for clarification.

### What large language models are compatible with the Humanizer skill?

Any LLM that supports structured skill loading can run Humanizer, including **Claude** (via [`.claude-plugin/plugin.json`](https://github.com/blader/humanizer/blob/main/.claude-plugin/plugin.json)) and **OpenAI models** (via function calling as shown in [`agents/openai.yaml`](https://github.com/blader/humanizer/blob/main/agents/openai.yaml)). The repository also includes [`AGENTS.md`](https://github.com/blader/humanizer/blob/main/AGENTS.md), which provides guidelines for porting the skill to other agent frameworks.

### Where is the actual rewrite logic stored in the repository?

The complete logic resides in **[`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md)** at the repository root. This file contains the metadata, the catalogue of 35 patterns, and the four-step rewrite process. Supporting files like [`README.md`](https://github.com/blader/humanizer/blob/main/README.md) provide usage documentation, while [`scripts/validate-package.py`](https://github.com/blader/humanizer/blob/main/scripts/validate-package.py) handles CI validation, but no separate source code files contain the transformation algorithms.