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

The Humanizer skill architecture is a minimalist, pure-Markdown design where a single 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, 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 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 source.

Skills CLI Installation:

npx skills add blader/humanizer --global

The CLI copies 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 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 contains universal logic, thin descriptor files adapt the skill to specific agent runtimes.

OpenAI Compatibility (agents/openai.yaml)

The file 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.

Claude Plugin Descriptors (.claude-plugin/)

Claude integration relies on two JSON configuration files:

• .claude-plugin/plugin.json – Defines plugin metadata and the path to SKILL.md
• .claude-plugin/marketplace.json – Powers the marketplace listing and installation flow

Claude Desktop loads the skill by reading 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. This Python script performs three critical checks:

1. File existence verification – Ensures SKILL.md, descriptor files, and documentation are present
2. Version synchronization – Confirms that version numbers align across SKILL.md, 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 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, 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 and .claude-plugin/ adapt the universal prompt to specific runtime environments
• Built-in validation: 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, the skill requires no platform-specific code. Agent-specific glue files like agents/openai.yaml and .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 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 script checks that required files exist, verifies version number consistency across SKILL.md, 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.

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