# What Is the Purpose of SKILL.md in the Humanizer Project?

> Discover the purpose of SKILL.md in the Humanizer project. This file holds YAML metadata, instructions, and rewrite patterns to transform AI text into natural prose.

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

---

**SKILL.md serves as the single source of truth for the Humanizer agent, containing the complete YAML metadata, natural-language instructions, and 35 numbered rewrite patterns that transform AI-generated text into natural-sounding prose.**

In the `blader/humanizer` repository, [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) functions as the core skill definition that agents read and execute when humanizing content. This file encodes the specific behaviors, voice-matching guidelines, and output conventions that distinguish robotic text from authentic human writing.

## Core Components of SKILL.md

### Metadata and Version Control

The file opens with structured metadata that tooling uses to identify the skill's current iteration. According to the source at lines 9-11, the `metadata.version` field is set to `"2.11.2"`, allowing agents to verify compatibility before processing text.

### Skill Description and Goals

Lines 13-15 contain the foundational description explaining the skill's primary objective: rewriting AI-sounding prose so it sounds natural without altering the underlying meaning. This section establishes the constraints and philosophical approach that guide all subsequent pattern applications.

### Rewrite Patterns and Agent Instructions

Beginning at line 48, [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) encodes the complete set of **35 numbered rewrite patterns** that drive agent behavior. These rules cover voice-matching guidance, output-format conventions, and specific linguistic transformations. Any agent loading this file—whether Claude, OpenAI, or custom implementations—follows these concrete patterns when processing input text.

## How Agents Load and Use SKILL.md

Agents consume [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) as a configuration and instruction set, typically reading the file at runtime to initialize their behavior.

For OpenAI-based agents, registration occurs through a YAML configuration file:

```yaml

# agents/openai.yaml – registering the Humanizer skill

name: humanizer
description: Rewrite AI‑sounding text to sound natural.
skillFile: SKILL.md

```

For Claude integrations, the skill is exposed via a JSON manifest:

```json
{
  "metadata": {
    "name": "humanizer",
    "version": "2.11.2"
  },
  "skill": {
    "path": "SKILL.md"
  }
}

```

When invoking the skill programmatically, developers can load [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) directly into the system prompt:

```python

# Example: invoking Humanizer from Python (using the OpenAI API)

import openai

prompt = """Please humanize the following paragraph:\n
AI‑generated text goes here..."""

response = openai.ChatCompletion.create(
    model="gpt-4o",
    messages=[{"role": "system", "content": open("SKILL.md").read()},
              {"role": "user", "content": prompt}]
)

print(response.choices[0].message.content)

```

## Relationship to Other Project Files

While [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) contains the authoritative skill definition, it operates within an ecosystem of supporting files:

- **[`README.md`](https://github.com/blader/humanizer/blob/main/README.md)**: Provides installation and usage guides while keeping version and pattern tables synchronized with [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md)
- **[`scripts/validate-package.py`](https://github.com/blader/humanizer/blob/main/scripts/validate-package.py)**: Validates consistency between the skill definition and related files before publication
- **[`.claude-plugin/plugin.json`](https://github.com/blader/humanizer/blob/main/.claude-plugin/plugin.json)**: Declares the skill path for Claude agents, pointing specifically to [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md)
- **[`agents/openai.yaml`](https://github.com/blader/humanizer/blob/main/agents/openai.yaml)**: Demonstrates registration patterns for OpenAI-based implementations

## Summary

- [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) acts as the **single source of truth** for the Humanizer agent's behavior
- The file contains **YAML metadata** including version `2.11.2` for tooling compatibility
- **35 numbered rewrite patterns** starting at line 48 define the concrete transformations applied to AI-generated text
- Agents load this file at runtime to initialize their system prompts and processing rules
- Helper scripts like [`validate-package.py`](https://github.com/blader/humanizer/blob/main/validate-package.py) ensure the skill definition remains consistent across the project

## Frequently Asked Questions

### What format does SKILL.md use?

[`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) uses a hybrid format beginning with YAML frontmatter for metadata (lines 9-11), followed by natural-language descriptions (lines 13-15), and concluding with structured numbered patterns for rewrite rules (starting at line 48).

### Can I use SKILL.md with any AI agent?

Yes. The file is designed as a portable skill definition that any agent capable of reading system instructions can consume, including Claude, OpenAI models, and custom implementations. The [`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) files demonstrate platform-specific registration methods.

### How many rewrite patterns are defined in SKILL.md?

The file contains **35 numbered rewrite patterns** that cover voice-matching guidelines, output-format conventions, and specific linguistic transformations to humanize text.

### Does modifying SKILL.md affect the entire project?

Yes. Because [`scripts/validate-package.py`](https://github.com/blader/humanizer/blob/main/scripts/validate-package.py) validates the skill against other project files, and because agents load this file directly at runtime, changes to [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) immediately impact how all integrated agents process text. The [`README.md`](https://github.com/blader/humanizer/blob/main/README.md) should be updated in parallel to maintain synchronization.