How Are Agents Defined in the Humanizer Project: A Complete Guide to Portable YAML Descriptors

Humanizer defines agents as portable YAML descriptors stored in the agents/ directory, where each file references a single Markdown skill (SKILL.md) to create platform-specific AI agents.

The Humanizer project by blader implements a declarative agent architecture that separates interface configuration from skill logic. Instead of maintaining separate codebases for each LLM platform, the repository uses YAML files to describe agent capabilities while pointing to a unified Markdown skill. This approach enables rapid extension across OpenAI, Claude, and other platforms without duplicating core logic.

Core Architecture of Humanizer Agents

Humanizer agents follow a descriptor-based pattern where metadata and behavior references live in structured configuration files rather than executable code. This architecture centers on two critical concepts: the YAML interface definition and the singular skill source.

The YAML Descriptor Pattern

Each agent definition resides in a separate YAML file under the agents/ directory. According to the source code, these descriptors contain an interface object with three required fields:

• display_name – The human-readable name shown in UI selectors and agent marketplaces
• short_description – A concise tagline describing the agent's purpose
• default_prompt – The initial prompt text sent to the LLM, typically containing a variable like $humanizer that the runtime replaces with actual skill content

The file agents/openai.yaml demonstrates this pattern for the OpenAI-compatible agent implementation.

The Single Skill Source (SKILL.md)

All agents converge on SKILL.md at the repository root. This Markdown file contains the actual prompt patterns, metadata, and behavioral instructions that define the Humanizer capability. Rather than embedding this logic directly in agent definitions, YAML descriptors reference SKILL.md externally. This creates a single source of truth where updating the skill automatically propagates changes to every agent implementation.

Key Configuration Files

The Humanizer repository organizes agent definitions across several specialized files that handle platform registration, validation, and documentation.

Platform-Specific Definitions (agents/openai.yaml)

The primary OpenAI agent definition lives in agents/openai.yaml. This file declares the interface that OpenAI's platform consumes when loading the Humanizer skill:

interface:
  display_name: "Humanizer"
  short_description: "Make AI-written text sound like the writer"
  default_prompt: "Use $humanizer to rewrite this text in my voice without changing its facts."

The default_prompt field includes the variable $humanizer, which the plugin runtime expands to the full content of SKILL.md during initialization.

Plugin Manifests (.claude-plugin/plugin.json)

For Claude integration, the repository uses .claude-plugin/plugin.json to register the skill with Anthropic's plugin system. This manifest tells the plugin loader that the skill resides at the repository root ("./"), allowing Claude's runtime to locate and consume the same SKILL.md file used by OpenAI agents. The consolidation prevents drift between platform implementations.

Validation and Synchronization (scripts/validate-package.py)

To prevent metadata inconsistencies, the repository includes scripts/validate-package.py. This validation script ensures that version numbers, descriptions, and structural conventions remain synchronized across SKILL.md, README.md, and the various plugin manifests. Running this script verifies that adding a new agent descriptor does not break existing platform contracts.

How the Agent Loading Process Works

The runtime consumption of these YAML descriptors follows a predictable injection pattern:

1. Descriptor Parsing – The plugin runtime loads the appropriate YAML file from agents/ based on the target platform (e.g., OpenAI).

2. Skill Injection – The runtime reads SKILL.md from the repository root and substitutes its content for the $humanizer variable found in the default_prompt field.

3. Agent Instantiation – The combined prompt (descriptor template + skill content) is passed to the LLM interface along with the display_name and short_description metadata.

This process means all agents share identical core logic while maintaining platform-specific wrapper prompts and metadata.

Extending the System with New Agents

Adding support for additional LLM providers requires no code changes—only a new YAML descriptor. To create an Azure OpenAI agent, for example, create agents/azure.yaml:

interface:
  display_name: "Humanizer (Azure)"
  short_description: "Azure-compatible Humanizer skill"
  default_prompt: "Apply $humanizer to the supplied text."

After placing this file in agents/, the validation script (scripts/validate-package.py) automatically checks that the YAML format matches the expected schema. The system immediately recognizes the new agent without modifying existing logic, demonstrating the portability of the descriptor pattern.

Summary

• Portable YAML Descriptors: Humanizer agents are defined as YAML files in agents/, each containing an interface object with display_name, short_description, and default_prompt.
• Single Source of Truth: All agents reference SKILL.md for actual behavior, ensuring updates propagate instantly across all platforms.
• Platform Abstraction: Files like agents/openai.yaml and .claude-plugin/plugin.json adapt the core skill to specific LLM interfaces without code duplication.
• Automated Validation: scripts/validate-package.py maintains consistency across descriptors, documentation, and the master skill file.
• Zero-Code Extensibility: New agents require only a new YAML descriptor following the established schema.

Frequently Asked Questions

What file format does Humanizer use to define agents?

Humanizer uses YAML descriptors stored in the agents/ directory. Each YAML file contains an interface object that specifies metadata and a reference prompt, while the actual AI behavior lives in the separate SKILL.md Markdown file.

How does Humanizer keep agent definitions synchronized across platforms?

The repository uses scripts/validate-package.py to enforce consistency. This script checks that version numbers, descriptions, and structural elements in SKILL.md, README.md, and plugin manifests like .claude-plugin/plugin.json remain aligned. Since all agents reference the same SKILL.md, skill updates automatically apply to every platform.

Can I add a custom agent for a different LLM provider?

Yes. Adding a new agent requires only creating a new YAML file in agents/ (for example, agents/azure.yaml) that follows the established schema with display_name, short_description, and default_prompt fields. The validation script will verify the format, and no other code changes are necessary because all agents consume the shared SKILL.md resource.

What is the role of the $humanizer variable in agent definitions?

The $humanizer variable acts as a placeholder in the default_prompt field of YAML descriptors. When the plugin runtime loads an agent, it replaces this variable with the complete content of SKILL.md, effectively injecting the core Humanizer instructions into the platform-specific prompt template.

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