# How the Humanizer Skill Architecture Works: A Pure-Markdown Agent Design

> Discover the minimalist Humanizer skill architecture. This pure-Markdown design uses a single SKILL.md file with YAML front-matter and detailed prompts for OpenAI and Claude compatibility.

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

---

**The Humanizer skill architecture is a minimalist, pure-Markdown design where a single [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) file containing YAML front-matter and a detailed prompt serves as the entire runtime, supplemented by thin agent-specific descriptors for OpenAI and Claude compatibility.**

The Humanizer project (`blader/humanizer`) demonstrates how modern AI agent skills can operate without build steps or dependencies. By treating the prompt itself as the executable artifact, the architecture achieves cross-platform portability while maintaining consistent rewrite behavior across different LLM hosts.

## Core Prompt Structure in SKILL.md

At the center of the architecture lies [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md), the sole runtime artifact required for text rewriting operations.

This file begins with **YAML front-matter** that declares the skill name, description, license, and semantic version (`metadata.version`). Everything following the front-matter constitutes the actual prompt logic that agents execute when humanizing text.

The prompt embedded in [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) encodes four critical elements:

- **25 distinct rewrite patterns** that identify AI-sounding constructions
- **A four-stage workflow**: mark "tells" → draft rewrite → check against patterns → final output
- **Three operational modes**: plain-text paste, file-mode (rewrite prose only), and embedded mode (return final text only)
- **Voice matching capabilities** for style consistency

Because the entire logic resides in Markdown, no compilation, bundling, or dependency resolution is required at installation time.

## Installation and Discovery Mechanisms

Humanizer supports two primary distribution channels that both resolve to the same [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) source.

**Skills CLI Installation:**

```bash
npx skills add blader/humanizer --global

```

The CLI copies [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) directly into the agent's skill directory, making the skill available immediately without build steps.

**Claude Marketplace Installation:**

```

/plugin marketplace add blader/humanizer
/plugin install humanizer@humanizer

```

According to the [`README.md`](https://github.com/blader/humanizer/blob/main/README.md) installation section, this method registers the skill within Claude Desktop's plugin ecosystem, referencing the same root Markdown file.

## Agent-Specific Glue Files

While [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) contains universal logic, thin descriptor files adapt the skill to specific agent runtimes.

### OpenAI Compatibility ([`agents/openai.yaml`](https://github.com/blader/humanizer/blob/main/agents/openai.yaml))

The file [`agents/openai.yaml`](https://github.com/blader/humanizer/blob/main/agents/openai.yaml) provides the display name, short description, and a default prompt pointer that exposes the skill as the `/humanizer` command. When an OpenAI-compatible agent loads the skill, it reads this YAML to determine command routing and UI presentation, then delegates execution to the root [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md).

### Claude Plugin Descriptors (`.claude-plugin/`)

Claude integration relies on two JSON configuration files:

- [`.claude-plugin/plugin.json`](https://github.com/blader/humanizer/blob/main/.claude-plugin/plugin.json) – Defines plugin metadata and the path to [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md)
- [`.claude-plugin/marketplace.json`](https://github.com/blader/humanizer/blob/main/.claude-plugin/marketplace.json) – Powers the marketplace listing and installation flow

Claude Desktop loads the skill by reading [`plugin.json`](https://github.com/blader/humanizer/blob/main/plugin.json), which redirects the runtime to the Markdown prompt. This architecture allows the same rewriting logic to operate across both OpenAI and Claude ecosystems without code duplication.

## Validation and Packaging Pipeline

Before publication, the repository validates package integrity through [`scripts/validate-package.py`](https://github.com/blader/humanizer/blob/main/scripts/validate-package.py). This Python script performs three critical checks:

1. **File existence verification** – Ensures [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md), descriptor files, and documentation are present
2. **Version synchronization** – Confirms that version numbers align 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 metadata
3. **Schema compliance** – Runs `npx skills add . --list` to verify against the Skills format validator

The validation script executes in CI pipelines, preventing publication of inconsistent or malformed packages.

## Runtime Execution Flow

When a user invokes the skill—whether via `/humanizer` in Claude or an equivalent command in OpenAI agents—the following sequence occurs:

1. **Prompt Loading**: The agent reads the complete text of [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) into the context window
2. **Pattern Identification**: The model marks every detected "tell" (AI-typical phrasing) in the input text
3. **Draft Generation**: The model produces a rewritten version eliminating identified patterns
4. **Quality Check**: The draft is validated against the 25 patterns to ensure no "tells" remain
5. **Mode Selection**: Based on command syntax, the skill outputs either inline rewritten text, file diffs, or embedded prose

This entire workflow executes within the prompt itself—no external API calls, no runtime dependencies, and no state management beyond the agent's standard context handling.

## Summary

- **Single-file architecture**: The entire skill logic lives in [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md), making it portable across any LLM platform that supports Markdown prompts
- **Zero-build deployment**: Installation requires only copying the Markdown file, with no compilation or dependency management
- **Agent abstraction layers**:Thin descriptor files in [`agents/openai.yaml`](https://github.com/blader/humanizer/blob/main/agents/openai.yaml) and `.claude-plugin/` adapt the universal prompt to specific runtime environments
- **Built-in validation**: [`scripts/validate-package.py`](https://github.com/blader/humanizer/blob/main/scripts/validate-package.py) ensures version consistency and package integrity before release
- **Prompt-native workflow**: The four-stage rewrite process (mark, draft, check, output) and three operational modes execute entirely within the LLM context

## Frequently Asked Questions

### How does the Humanizer skill architecture achieve cross-platform compatibility?

The architecture treats the prompt as the executable. By storing all logic—including the 25 rewrite patterns and workflow stages—inside [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md), the skill requires no platform-specific code. Agent-specific glue files like [`agents/openai.yaml`](https://github.com/blader/humanizer/blob/main/agents/openai.yaml) and [`.claude-plugin/plugin.json`](https://github.com/blader/humanizer/blob/main/.claude-plugin/plugin.json) merely point to this central Markdown file, allowing Claude, OpenAI agents, and other compatible platforms to execute identical rewriting logic.

### What installation methods are available for the Humanizer skill?

Users can install via the Skills CLI using `npx skills add blader/humanizer`, which copies [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) into the agent's skill directory. Alternatively, Claude Desktop users can install through the marketplace using `/plugin marketplace add blader/humanizer`. Both methods reference the same source files and require no build steps.

### How does the validation script ensure package integrity?

The [`scripts/validate-package.py`](https://github.com/blader/humanizer/blob/main/scripts/validate-package.py) script checks that required files exist, verifies version number consistency 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 descriptors, and runs `npx skills add . --list` to validate against the Skills format schema. This prevents publishing packages with mismatched metadata or missing components.

### Can the Humanizer skill operate in different output modes?

Yes. The skill supports three operational modes defined entirely within the prompt logic: plain-text paste (standard humanization), file-mode (rewriting only the prose within a file), and embedded mode (returning only the final text without commentary). The mode is selected based on the command syntax the user invokes, with no external configuration required.