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

> Learn to understand OpenAI skill dependencies by exploring the MCP configuration and YAML schema. Discover how dependencies are declared in the openai.yaml file.

- Repository: [OpenAI/skills](https://github.com/openai/skills)
- Tags: deep-dive
- Published: 2026-02-16

---

**OpenAI Skills declare external dependencies in an [`agents/openai.yaml`](https://github.com/openai/skills/blob/main/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`](https://github.com/openai/skills/blob/main/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`](https://github.com/openai/skills/blob/main/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`](https://github.com/openai/skills/blob/main/openai.yaml) file is documented in [`skills/.system/skill-creator/references/openai_yaml.md`](https://github.com/openai/skills/blob/main/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`](https://github.com/openai/skills/blob/main/agents/openai.yaml) contains a `tools` array where each entry represents an external service. The structure follows this pattern:

```yaml
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`](https://github.com/openai/skills/blob/main/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`](https://github.com/openai/skills/blob/main/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:

```python
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`](https://github.com/openai/skills/blob/main/agents/openai.yaml) is valid before committing changes, run the skill-creator validation script:

```bash
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`](https://github.com/openai/skills/blob/main/agents/openai.yaml)** (skill-specific) – Declares UI metadata and external `dependencies.tools`. Example: [`skills/.curated/render-deploy/agents/openai.yaml`](https://github.com/openai/skills/blob/main/skills/.curated/render-deploy/agents/openai.yaml).
- **[`skills/.system/skill-creator/references/openai_yaml.md`](https://github.com/openai/skills/blob/main/skills/.system/skill-creator/references/openai_yaml.md)** – Canonical schema and field-level documentation for [`openai.yaml`](https://github.com/openai/skills/blob/main/openai.yaml).
- **[`skills/.system/skill-creator/scripts/quick_validate.py`](https://github.com/openai/skills/blob/main/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`](https://github.com/openai/skills/blob/main/skills/.system/skill-installer/scripts/install-skill-from-github.py)** – Installer that reads [`openai.yaml`](https://github.com/openai/skills/blob/main/openai.yaml) to ensure required MCP services are reachable before copying the skill.

## Summary

- **OpenAI Skills declare dependencies in [`agents/openai.yaml`](https://github.com/openai/skills/blob/main/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`](https://github.com/openai/skills/blob/main/quick_validate.py).

## Frequently Asked Questions

### What file contains the dependency declarations for an OpenAI skill?

The [`agents/openai.yaml`](https://github.com/openai/skills/blob/main/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`](https://github.com/openai/skills/blob/main/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`](https://github.com/openai/skills/blob/main/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`](https://github.com/openai/skills/blob/main/quick_validate.py) script from the skill-creator system to check syntax and required fields.