How the `agents/openai.yaml` Configuration Exposes Humanizer to OpenAI‑Compatible Agents

The agents/openai.yaml file acts as a bridge that registers the Humanizer skill with OpenAI‑compatible agents by defining discovery metadata and a prompt template that injects the full SKILL.md content at runtime.

The blader/humanizer repository provides a Markdown‑based prompt designed to rewrite AI‑generated text in a human voice. For OpenAI‑compatible agent runtimes, the agents/openai.yaml configuration file transforms this raw skill into a discoverable, executable tool that agents can load and invoke without manual prompt engineering.

Configuration Structure in agents/openai.yaml

The YAML file located at agents/openai.yaml contains three critical fields that control how OpenAI agents discover, display, and execute the Humanizer skill.

display_name: Skill Discovery

The display_name field supplies the human‑readable label "Humanizer" that appears in the agent’s skill picker UI.

This value enables users to identify the skill among available tools without inspecting repository internals. According to the repository structure defined in AGENTS.md, agents scan the agents/ directory for YAML configurations and use this field to populate their interface menus.

short_description: Contextual Tagline

The short_description provides the concise explanation "Make AI‑written text sound like the writer" that appears alongside the skill name.

This field gives users immediate context about the skill’s purpose, allowing them to decide whether to invoke it based on a single sentence rather than reviewing the full SKILL.md documentation.

default_prompt: Runtime Prompt Injection

The default_prompt field defines the template that the agent sends to the language model when the skill is called.

This template contains the placeholder $humanizer, which the agent runtime expands at execution time to the complete contents of SKILL.md. This mechanism ensures the model receives the full Humanizer instruction set—including all rewriting patterns and constraints—without requiring users to manually copy Markdown content into their chat interface.

Runtime Integration Flow

When an OpenAI‑compatible agent loads the blader/humanizer repository, it executes a standardized ingestion process:

1. Directory Scanning: The agent scans the agents/ directory for configuration files.
2. YAML Parsing: It parses openai.yaml and registers the three fields as a unified skill entry.
3. Prompt Expansion: Upon invocation, it substitutes the $humanizer token with the literal text from SKILL.md.

This architecture allows the same SKILL.md file to serve multiple agent types while openai.yaml provides the OpenAI‑specific binding logic.

Practical Usage Examples

You can invoke the Humanizer skill through the agent’s interface using the registered command:

/humanizer
[paste your text here]

Alternatively, you can reference the skill programmatically using the default prompt template defined in agents/openai.yaml:

Use $humanizer to rewrite this text in my voice without changing its facts.

In this second example, the agent replaces $humanizer with the full content of SKILL.md before sending the request to the model, ensuring the rewriting logic executes with complete context.

Key Files in the Integration

• agents/openai.yaml – Defines the discovery metadata and prompt template for OpenAI agents.
• SKILL.md – Contains the actual Humanizer prompt logic that rewrites text.
• README.md – Provides installation instructions and explains the skill architecture.
• AGENTS.md – Documents the agent‑specific configuration format used across different platforms.

Summary

• The agents/openai.yaml configuration registers Humanizer as a discoverable skill in OpenAI‑compatible agents by defining display_name, short_description, and default_prompt fields.
• The $humanizer placeholder in default_prompt automatically expands to the full contents of SKILL.md at runtime, eliminating manual prompt copying.
• Agents scan the agents/ directory during initialization to locate and parse this YAML file, making the skill available through the UI and API without code changes to the core repository.

Frequently Asked Questions

What format must the agents/openai.yaml file follow?

The file follows standard YAML syntax with three required top‑level keys: display_name (string), short_description (string), and default_prompt (string). The repository includes analogous configurations for other agent types, such as the Claude plugin defined in .claude-plugin/plugin.json, demonstrating a consistent pattern of agent‑specific bridge files.

How does the $humanizer placeholder work?

The $humanizer token serves as a runtime variable that the agent replaces with the literal text content of SKILL.md. When the agent constructs the final prompt for the language model, it performs string substitution, injecting the complete Humanizer instructions where the placeholder appears in the default_prompt template.

Can I use Humanizer with agents that do not support YAML skill configurations?

Yes. The core functionality resides in SKILL.md, which is a standard Markdown file containing the prompt instructions. You can manually copy the contents of SKILL.md into any agent interface, or reference it via API calls, regardless of whether the agent runtime supports the agents/openai.yaml discovery protocol.

Where is the skill logic actually implemented?

The rewriting logic and prompt engineering are contained entirely within SKILL.md at the repository root. The agents/openai.yaml file does not contain the logic itself; it only provides the binding mechanism that tells OpenAI‑compatible agents how to locate and inject SKILL.md into their conversation context.

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