What Is the Purpose of the SKILL.md File in Humanizer?

The SKILL.md file serves as the single source of truth that defines the Humanizer agent skill, containing YAML metadata, 35 rewrite patterns for detecting AI prose, and the LLM prompt body that agents use to humanize text.

In the blader/humanizer repository, the SKILL.md file functions as the core configuration and instruction set that powers the entire humanization workflow. Unlike traditional configuration files, SKILL.md is pure Markdown, making it instantly compatible with any LLM agent—such as Claude Code, Claude Desktop, or OpenAI plugins—that supports Markdown-based skills.

Structure of the SKILL.md File

YAML Metadata Header

The top of SKILL.md contains YAML frontmatter declaring the skill’s version, name, description, and compatibility flags. Agents read this metadata to load the skill correctly without requiring compilation or build steps.

The 35 Rewrite Patterns

Lines 55-99 of SKILL.md define 35 specific patterns derived from Wikipedia’s Signs of AI writing. Each pattern includes a description, a "before" example of AI-sounding prose, and an "after" transformation showing the humanized version. These patterns standardize how the agent detects and replaces robotic language.

LLM Prompt Body

The bulk of the file after the pattern tables contains the actual Markdown prompt that agents feed to the language model. This body explains how Humanizer works, how to invoke the /humanizer command, and provides usage examples. When you run /humanizer, the agent injects this prompt body into the LLM's context.

How SKILL.md Drives Agent Behavior

The SKILL.md file encapsulates the entire behavior of the Humanizer package. When an agent loads the skill via the .claude-plugin/plugin.json descriptor, it points directly to SKILL.md, reads the metadata, and uses the prompt body to process requests.

The humanization flow works as follows:

1. The user invokes /humanizer or a plain-language request.
2. The agent loads the prompt from SKILL.md.
3. The LLM applies the 35 patterns defined in the file.
4. The rewritten text is returned to the user.

Practical Usage Examples

Direct Skill Invocation

/humanizer

[Paste the AI-generated text you want to humanize here]

Plain-Language Request (Claude Code/Desktop)

Please humanize this text: 
"The new feature dramatically improves performance..."

The agent maps this request to the /humanizer command internally using the logic defined in SKILL.md.

Voice-Matching with Writing Samples

/humanizer

Here's a sample of my writing for voice matching:
> I love hiking in the mountains; the silence there is a kind of meditation.

Now humanize this text:
> The AI-generated description of the product is too generic...

Ecosystem and Validation

While SKILL.md contains the core logic, other files in the blader/humanizer repository reference or validate it:

• README.md provides human-readable overview and installation instructions
• .claude-plugin/plugin.json tells Claude-based agents where to find the skill (SKILL.md)
• scripts/validate-package.py ensures the skill files stay in sync and follow the required format

All other files merely expose this core file; they do not contain independent humanization logic.

Summary

• SKILL.md is the single source of truth for the Humanizer agent skill, defining metadata, patterns, and prompts in one file.
• The file contains 35 rewrite patterns (lines 55-99) that detect AI-sounding prose based on Wikipedia’s Signs of AI writing.
• It is a pure Markdown file, enabling instant compatibility with Claude Code, Claude Desktop, and other LLM agents without compilation.
• The prompt body within SKILL.md is what agents send to the LLM when processing /humanizer commands.
• scripts/validate-package.py ensures version consistency between SKILL.md, README.md, and plugin descriptors.

Frequently Asked Questions

What agents are compatible with the SKILL.md file?

Any agent that supports Markdown-based skills can use SKILL.md directly, including Claude Code, Claude Desktop, and OpenAI plugins. The file is pure Markdown, requiring no build step or compilation to function.

How do the 35 patterns in SKILL.md work?

The patterns are defined between lines 55-99 and follow Wikipedia’s Signs of AI writing. Each pattern includes a description, an AI-sounding "before" example, and a humanized "after" transformation. The LLM uses these examples as few-shot learning to guide its rewriting process.

Where is the version information stored in Humanizer?

Version metadata lives in the YAML frontmatter at the top of SKILL.md. This version is synchronized with README.md and the Claude plugin file via scripts/validate-package.py to ensure consistency across the package.

Can I modify SKILL.md to customize the humanization behavior?

Yes, you can edit SKILL.md directly to adjust the rewrite patterns or prompt body since it is pure Markdown. However, running scripts/validate-package.py afterward ensures your changes remain compatible with the plugin structure and version requirements.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}