How to Understand the Dependencies of an OpenAI Skill: MCP Configuration and YAML Schema

OpenAI Skills declare external dependencies in an agents/openai.yaml file using a structured dependencies.tools block that specifies MCP servers with type, value, transport, and URL fields.

To understand the dependencies of an OpenAI skill, you must examine the agents/openai.yaml configuration file located in the skill's root directory. This YAML file, part of the openai/skills repository, defines external tool requirements using a standardized schema that the Codex harness parses at runtime to establish MCP connections.

Where OpenAI Skill Dependencies Are Declared

The agents/openai.yaml Configuration File

Every skill in the openai/skills repository stores its metadata and dependency declarations in agents/openai.yaml. This file sits at the skill root and serves as the single source of truth for external tool requirements. The Codex harness reads this file during skill initialization to determine which Managed Cloud Platform (MCP) servers the skill needs to communicate with.

Reference Schema Documentation

The canonical schema for the openai.yaml file is documented in skills/.system/skill-creator/references/openai_yaml.md. This reference file defines the structure of the dependencies block, including valid values for the type, transport, and url fields. Developers should consult this document when adding new dependencies to ensure compliance with the platform's validation rules.

Anatomy of the Dependencies Block

The dependencies section in agents/openai.yaml contains a tools array where each entry represents an external service. The structure follows this pattern:

dependencies:
  tools:
    - type: "mcp"
      value: "render"
      description: "Render MCP server"
      transport: "streamable_http"
      url: "https://mcp.render.com/mcp"

Each field serves a specific purpose:

• type – Currently only "mcp" is supported, indicating a Managed Cloud Platform dependency.
• value – The identifier of the service, such as render or github.
• description – A human-readable summary displayed in UI tooltips.
• transport – The communication protocol; for MCP this is typically "streamable_http".
• url – The fully qualified endpoint where the MCP server accepts connections.

The tools array supports multiple entries, allowing a single skill to depend on several external services simultaneously.

How the Platform Consumes Dependency Metadata

When the Codex harness loads a skill, it parses agents/openai.yaml and extracts the dependencies block. The platform processes this information through several stages:

1. MCP Client Initialization – The harness instantiates an MCP client using the url and transport parameters specified in each tool entry.
2. UI Surfacing – The description field is exposed in the user interface, allowing developers to see which external services a skill will contact before execution.
3. Runtime Validation – Before invoking the skill, the platform verifies that all required MCP servers are reachable, preventing runtime failures due to missing dependencies.

This architecture ensures that dependency declarations in agents/openai.yaml directly control the runtime behavior and connectivity requirements of the skill.

Reading and Validating Dependencies Programmatically

Developers can inspect skill dependencies using standard YAML parsing. The following Python snippet mirrors the internal logic used by the Codex harness to extract tool requirements:

import yaml
from pathlib import Path

def load_dependencies(skill_path: Path) -> list[dict]:
    """Return the list of tool dependencies declared in a skill."""
    yaml_path = skill_path / "agents" / "openai.yaml"
    with yaml_path.open() as f:
        data = yaml.safe_load(f)

    # `dependencies` may be absent; return an empty list in that case

    return data.get("dependencies", {}).get("tools", [])

# Example usage

skill_dir = Path("/home/user/.codex/skills/render-deploy")
for tool in load_dependencies(skill_dir):
    print(f"{tool['value']} ({tool['type']}): {tool['url']}")

To ensure your agents/openai.yaml is valid before committing changes, run the skill-creator validation script:

python -m skills/.system/skill-creator/scripts/quick_validate.py path/to/skill

This script checks YAML syntax and verifies that all required fields in the dependencies block are present and correctly formatted.

Key Files in the Dependency System

Understanding the dependency architecture requires familiarity with these specific files in the openai/skills repository:

• agents/openai.yaml (skill-specific) – Declares UI metadata and external dependencies.tools. Example: skills/.curated/render-deploy/agents/openai.yaml.
• skills/.system/skill-creator/references/openai_yaml.md – Canonical schema and field-level documentation for openai.yaml.
• skills/.system/skill-creator/scripts/quick_validate.py – Helper script that checks YAML syntax and required fields, including dependencies.
• skills/.system/skill-installer/scripts/install-skill-from-github.py – Installer that reads openai.yaml to ensure required MCP services are reachable before copying the skill.

Summary

• OpenAI Skills declare dependencies in agents/openai.yaml using a structured dependencies.tools array.
• Each tool entry requires five fields: type (currently "mcp"), value, description, transport, and url.
• The Codex harness parses this file at runtime to initialize MCP clients, surface descriptions in the UI, and validate connectivity before execution.
• Developers can programmatically inspect dependencies using standard YAML libraries, and validate changes using quick_validate.py.

Frequently Asked Questions

What file contains the dependency declarations for an OpenAI skill?

The agents/openai.yaml file located in the skill's root directory contains all dependency declarations. This file uses a dependencies.tools array to list external MCP servers the skill requires, including their endpoints and transport protocols.

What types of dependencies can an OpenAI skill declare?

Currently, OpenAI skills only support MCP (Managed Cloud Platform) dependencies. The type field in the dependencies.tools array must be set to "mcp", and the transport field typically uses "streamable_http" to establish the connection.

How does the Codex harness validate skill dependencies before execution?

The harness parses agents/openai.yaml during skill loading and performs runtime validation to ensure all declared MCP servers are reachable. It extracts the url and transport fields to initialize MCP clients, and surfaces the description field in the UI so users know which external services will be contacted.

Can I programmatically list the dependencies of a local skill?

Yes. You can read and parse the agents/openai.yaml file using standard YAML libraries like PyYAML. The dependencies.tools array contains dictionaries with value, type, url, and other metadata. You can also use the quick_validate.py script from the skill-creator system to check syntax and required fields.

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