# How the `agents/openai.yaml` Configuration Exposes Humanizer to OpenAI‑Compatible Agents > Learn how the agents/openai.yaml config file registers Humanizer with OpenAI agents using discovery metadata and a runtime prompt template. Integrate Humanizer easily. - Repository: [Siqi Chen/humanizer](https://github.com/blader/humanizer) - Tags: internals - Published: 2026-09-12 --- **The [`agents/openai.yaml`](https://github.com/blader/humanizer/blob/main/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`](https://github.com/blader/humanizer/blob/main/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`](https://github.com/blader/humanizer/blob/main/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`](https://github.com/blader/humanizer/blob/main/agents/openai.yaml) The YAML file located at **[`agents/openai.yaml`](https://github.com/blader/humanizer/blob/main/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`](https://github.com/blader/humanizer/blob/main/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`](https://github.com/blader/humanizer/blob/main/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`](https://github.com/blader/humanizer/blob/main/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`](https://github.com/blader/humanizer/blob/main/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`](https://github.com/blader/humanizer/blob/main/SKILL.md). This architecture allows the same [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) file to serve multiple agent types while [`openai.yaml`](https://github.com/blader/humanizer/blob/main/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: ```text /humanizer [paste your text here] ``` Alternatively, you can reference the skill programmatically using the default prompt template defined in [`agents/openai.yaml`](https://github.com/blader/humanizer/blob/main/agents/openai.yaml): ```text 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`](https://github.com/blader/humanizer/blob/main/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`](https://github.com/blader/humanizer/blob/main/agents/openai.yaml)** – Defines the discovery metadata and prompt template for OpenAI agents. - **[`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md)** – Contains the actual Humanizer prompt logic that rewrites text. - **[`README.md`](https://github.com/blader/humanizer/blob/main/README.md)** – Provides installation instructions and explains the skill architecture. - **[`AGENTS.md`](https://github.com/blader/humanizer/blob/main/AGENTS.md)** – Documents the agent‑specific configuration format used across different platforms. ## Summary - The **[`agents/openai.yaml`](https://github.com/blader/humanizer/blob/main/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`](https://github.com/blader/humanizer/blob/main/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`](https://github.com/blader/humanizer/blob/main/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`](https://github.com/blader/humanizer/blob/main/.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`](https://github.com/blader/humanizer/blob/main/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`](https://github.com/blader/humanizer/blob/main/SKILL.md), which is a standard Markdown file containing the prompt instructions. You can manually copy the contents of [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) into any agent interface, or reference it via API calls, regardless of whether the agent runtime supports the [`agents/openai.yaml`](https://github.com/blader/humanizer/blob/main/agents/openai.yaml) discovery protocol. ### Where is the skill logic actually implemented? The rewriting logic and prompt engineering are contained entirely within **[`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md)** at the repository root. The [`agents/openai.yaml`](https://github.com/blader/humanizer/blob/main/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`](https://github.com/blader/humanizer/blob/main/SKILL.md) into their conversation context.