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

> Learn how Humanizer defines agents using portable YAML descriptors and Markdown skills in the agents/ directory for platform-specific AI.

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

---

**Humanizer defines agents as portable YAML descriptors stored in the `agents/` directory, where each file references a single Markdown skill ([`SKILL.md`](https://github.com/blader/humanizer/blob/main/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`](https://github.com/blader/humanizer/blob/main/agents/openai.yaml) demonstrates this pattern for the OpenAI-compatible agent implementation.

### The Single Skill Source (SKILL.md)

All agents converge on **[`SKILL.md`](https://github.com/blader/humanizer/blob/main/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`](https://github.com/blader/humanizer/blob/main/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`](https://github.com/blader/humanizer/blob/main/agents/openai.yaml))

The primary OpenAI agent definition lives in [`agents/openai.yaml`](https://github.com/blader/humanizer/blob/main/agents/openai.yaml). This file declares the interface that OpenAI's platform consumes when loading the Humanizer skill:

```yaml
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`](https://github.com/blader/humanizer/blob/main/SKILL.md) during initialization.

### Plugin Manifests ([`.claude-plugin/plugin.json`](https://github.com/blader/humanizer/blob/main/.claude-plugin/plugin.json))

For Claude integration, the repository uses [`.claude-plugin/plugin.json`](https://github.com/blader/humanizer/blob/main/.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`](https://github.com/blader/humanizer/blob/main/SKILL.md) file used by OpenAI agents. The consolidation prevents drift between platform implementations.

### Validation and Synchronization ([`scripts/validate-package.py`](https://github.com/blader/humanizer/blob/main/scripts/validate-package.py))

To prevent metadata inconsistencies, the repository includes **[`scripts/validate-package.py`](https://github.com/blader/humanizer/blob/main/scripts/validate-package.py)**. This validation script ensures that version numbers, descriptions, and structural conventions remain synchronized 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 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`](https://github.com/blader/humanizer/blob/main/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`](https://github.com/blader/humanizer/blob/main/agents/azure.yaml):

```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`](https://github.com/blader/humanizer/blob/main/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`](https://github.com/blader/humanizer/blob/main/SKILL.md) for actual behavior, ensuring updates propagate instantly across all platforms.
- **Platform Abstraction**: 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) adapt the core skill to specific LLM interfaces without code duplication.
- **Automated Validation**: [`scripts/validate-package.py`](https://github.com/blader/humanizer/blob/main/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`](https://github.com/blader/humanizer/blob/main/SKILL.md) Markdown file.

### How does Humanizer keep agent definitions synchronized across platforms?

The repository uses **[`scripts/validate-package.py`](https://github.com/blader/humanizer/blob/main/scripts/validate-package.py)** to enforce consistency. This script checks that version numbers, descriptions, and structural elements in [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md), [`README.md`](https://github.com/blader/humanizer/blob/main/README.md), and plugin manifests like [`.claude-plugin/plugin.json`](https://github.com/blader/humanizer/blob/main/.claude-plugin/plugin.json) remain aligned. Since all agents reference the same [`SKILL.md`](https://github.com/blader/humanizer/blob/main/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`](https://github.com/blader/humanizer/blob/main/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`](https://github.com/blader/humanizer/blob/main/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`](https://github.com/blader/humanizer/blob/main/SKILL.md), effectively injecting the core Humanizer instructions into the platform-specific prompt template.