# Design Principles Behind Humanizer: Architecture of the AI Text Humanization Skill > Discover the design principles behind Humanizer. Learn how AI text humanization uses 35 patterns for natural prose while preserving facts and voice. - Repository: [Siqi Chen/humanizer](https://github.com/blader/humanizer) - Tags: architecture - Published: 2026-09-05 --- **Humanizer applies 35 deterministic patterns in a two-pass rewrite process to transform AI-generated text into human-sounding prose while preserving factual integrity and matching the writer's voice, all within a pure-Markdown, agent-neutral skill architecture.** The `blader/humanizer` repository delivers a portable AI skill that converts synthetic writing into natural prose without hallucinating facts or altering meaning. Understanding the design principles behind Humanizer reveals how the system maintains deterministic behavior across Claude, Claude Code, Open-Code, and other compatible agents while enforcing strict content safety guidelines. ## Pattern-Driven Detection and Rewrite System Humanizer operates on **35 well-defined patterns** derived from Wikipedia’s *Signs of AI writing* to identify and correct artificial prose characteristics. According to the source code in [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md), these patterns organize into five distinct groups: *Content*, *Language & Grammar*, *Style*, *Chatbot*, and *Filler*. The skill does not use probabilistic generation. Instead, it applies deterministic structural transformations based on these cataloged patterns. When the skill processes text, it matches against these specific signatures—such as generic transitions, hedging language, or uniform sentence rhythm—then applies targeted rewrites to eliminate them. ## Incremental Two-Pass Processing Workflow The rewrite process follows a strict **draft-critique-finalize** methodology defined in [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) under the Rewrite Process section. During Step 1, the skill drafts an initial rewrite. Step 2 involves critiquing the draft for remaining AI patterns. Steps 3 and 4 produce the final output after this critical review. This two-pass approach ensures natural cadence and catches residual artificial phrasing that single-pass systems often miss. The incremental verification step specifically targets leftover "AI tells" before finalizing the humanized output. ## Factual Integrity and Voice Preservation Humanizer enforces **zero hallucination** and **voice fidelity** as core constraints. Per the guidelines in [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) § "What to do", the skill **never invents facts**—every claim, name, date, or citation must already exist in the source text or be supplied by the user. If a required detail is missing, the skill requests clarification rather than fabricating information. For stylistic consistency, the skill analyzes user-supplied writing samples to extract rhythm, word choice, punctuation habits, and personal quirks. As implemented in [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) § "Match the writer’s voice", these observed characteristics take precedence over generic style rules. For example, if a writer consistently uses em-dashes, Humanizer preserves that preference even when standard grammar might suggest alternatives. ## Safety-First Editing Guidelines The pattern library employs **conservative matching** to avoid over-editing protected content. According to [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) § "Check for false positives", the skill deliberately avoids modifying proper nouns, code blocks, YAML front-matter, or link targets. This safety layer reduces false positives that could corrupt technical documentation or structured data. The guidelines explicitly define "what not to flag," ensuring that legitimate technical terminology or intentional stylistic choices in specialized writing remain untouched during the humanization process. ## Agent-Neutral Architecture and Portability Humanizer implements a **pure-Markdown skill definition** with a minimal YAML header, containing no runtime code, binaries, or platform-specific hooks. As documented in [`AGENTS.md`](https://github.com/blader/humanizer/blob/main/AGENTS.md), this design ensures compatibility with any AI agent capable of loading Markdown skills, including Claude, Claude Code, and Open-Code. The repository structure separates the skill definition ([`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md)) from agent-specific wrappers (such as [`.claude-plugin/plugin.json`](https://github.com/blader/humanizer/blob/main/.claude-plugin/plugin.json) for Claude Desktop). This separation allows the core humanization logic to remain portable while permitting agent-specific installation methods. ## Versioned Metadata and Cross-Agent Installation Version control operates through the `metadata.version` field in the YAML front-matter of [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md). This centralized versioning ensures synchronized behavior across [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md), [`README.md`](https://github.com/blader/humanizer/blob/main/README.md), and the Claude plugin descriptor, guaranteeing reproducible output across different releases. Installation supports multiple pathways: ```bash # Global installation via Skills CLI npx skills add blader/humanizer --global # Agent-specific installation npx skills add blader/humanizer --agent 'claude' # Manual installation for agents with skill folders cp SKILL.md ~/.claude/skills/humanizer/ ``` As detailed in [`README.md`](https://github.com/blader/humanizer/blob/main/README.md), these methods support global, per-project, or manual deployment scenarios without modifying the core skill definition. ## Usage Examples Invoke Humanizer through direct commands or natural language requests: Direct invocation: ```text /humanizer [paste your AI‑generated text here] ``` Natural language request: ```text Please humanize this text: "The new platform—leveraging cutting‑edge AI—will revolutionize our workflow." ``` File-based rewriting: ```text Humanize the prose in docs/launch‑post.md ``` ## Summary - **Pattern-driven architecture**: Uses 35 deterministic patterns from Wikipedia’s *Signs of AI writing*, categorized into Content, Language & Grammar, Style, Chatbot, and Filler groups. - **Two-pass workflow**: Drafts content, critiques for remaining AI patterns, then finalizes to ensure natural cadence. - **Zero hallucination**: Never invents facts; requires user clarification for missing details rather than fabrication. - **Voice matching**: Analyzes and mirrors user-provided writing samples, prioritizing personal quirks over generic rules. - **Conservative editing**: Avoids modifying code blocks, front-matter, proper nouns, or link targets to prevent false positives. - **Agent-neutral design**: Pure Markdown with YAML metadata enables cross-platform compatibility without runtime dependencies. - **Centralized versioning**: `metadata.version` in [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) front-matter synchronizes behavior across documentation and plugin descriptors. - **Flexible installation**: Supports global CLI installation, agent-specific deployment, or manual file copying. ## Frequently Asked Questions ### How does Humanizer detect AI-generated text without using AI? Humanizer relies on **35 static patterns** cataloged in [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) rather than probabilistic AI detection. These patterns identify structural markers like generic transitions, hedging language, and rhythmic uniformity derived from Wikipedia’s research on AI writing signatures. The system applies deterministic structural analysis rather than machine learning inference. ### Will Humanizer change the facts in my document to make it sound more human? No. According to [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) § "What to do", Humanizer **strictly preserves original meaning** and never invents facts. If the text requires additional details to sound natural—such as specific dates or names—the skill will request clarification from you rather than hallucinating information. This design principle ensures factual integrity throughout the humanization process. ### Can I use Humanizer with AI agents other than Claude? Yes. Humanizer follows the **agent-neutral design** principles documented in [`AGENTS.md`](https://github.com/blader/humanizer/blob/main/AGENTS.md). The skill consists of pure Markdown with a YAML header, requiring no runtime binaries or platform-specific code. Any AI agent supporting Markdown-based skills—including Open-Code and future compatible systems—can load and execute the humanization patterns defined in [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md). ### How do I verify which version of Humanizer is installed? Check the `metadata.version` field in the YAML front-matter of your [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) file. The repository maintains synchronized versioning across [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md), [`README.md`](https://github.com/blader/humanizer/blob/main/README.md), and [`.claude-plugin/plugin.json`](https://github.com/blader/humanizer/blob/main/.claude-plugin/plugin.json) to ensure consistent behavior. When installed via the Skills CLI, the version aligns with the release tag in the `blader/humanizer` repository.