How Codex Plugins Implement the Skills Framework for Agentic Workflows

Codex plugins implement the skills framework for agentic workflows through a declarative, convention-driven architecture that enables LLM agents to discover, classify, and execute modular capabilities defined in Markdown files, YAML policies, and optional implementation scripts.

The OpenAI Plugins repository demonstrates how Codex plugins implement the skills framework for agentic workflows using a purely declarative approach. Instead of hardcoded logic, the system relies on human-readable Markdown definitions and YAML configuration files that the LLM interprets at runtime. This architecture allows developers to add new capabilities by creating directories under the skills/ folder without modifying the core Codex runtime.

Core Components of the Skills Framework

The framework consists of four distinct layers that work together to enable agentic behavior.

Plugin Manifest (.codex-plugin/plugin.json)

Every Codex plugin begins with a manifest file located at .codex-plugin/plugin.json that registers the plugin and points to the skills directory. In plugins/zoom/.codex-plugin/plugin.json, this JSON file tells Codex that the repository contains a valid plugin and where to locate its skill definitions.

Skill Definitions (SKILL.md)

Each skill is defined by a SKILL.md file that serves as the primary interface between the LLM and the capability. Located at paths like plugins/zoom/skills/start/SKILL.md, these Markdown files contain:

• Intent descriptions that help the LLM understand when to invoke the skill
• Routing tables (typically lines 19-25) that map high-level user intents to specific implementation skills
• Operating rules (lines 41-45) that guide the agent to keep responses concise and ask clarifying questions only when necessary

Agent Policies (agents/openai.yaml)

Policy files control how skills can be invoked. Stored at skills/<skill>/agents/<platform>.yaml (e.g., plugins/zoom/skills/start/agents/openai.yaml), these YAML files specify invocation constraints. The allow_implicit_invocation: false setting forces users to explicitly reference skills by name (e.g., $start or $build-zoom-bot) rather than relying on vague phrasing, preventing accidental misuse of low-level APIs.

Implementation Scripts (Optional)

Concrete execution logic lives in language-specific scripts referenced by the skill definition. For example, plugins/zotero/skills/zotero/scripts/zotero.py contains Python code that performs actual API calls when the skill is invoked. These scripts run in an isolated sandbox environment identical to the one used by codex exec.

How the Skills Framework Powers Agentic Workflows

The framework operates through a six-stage pipeline that transforms natural language requests into executed actions.

Discovery and Classification

When a user makes a request like "Create a Zoom meeting bot," Codex loads the plugin manifest and scans the skills/ directory, reading each SKILL.md file. The top-level start skill classifies requests by job-to-be-done rather than product name, using its routing table to determine the appropriate downstream skill.

Intent Routing

If the request matches an entry in the routing table (as defined in lines 19-25 of the start SKILL.md), Codex forwards the request to the target skill (e.g., build-zoom-bot). Skills can chain together, with each level potentially having its own routing logic, references, or associated scripts.

Policy Enforcement

Before execution, Codex checks the skill's agent policy YAML. Skills marked with allow_implicit_invocation: false require explicit user references, ensuring dangerous or specialized operations cannot be triggered accidentally through ambiguous language.

Sandboxed Execution

If the skill includes an implementation script, Codex invokes it in an isolated sandbox. The script can call third-party services (such as Zoom REST APIs) and return structured results that the LLM incorporates into its response.

Iterative Guidance

Throughout the interaction, the Operating Rules section of each SKILL.md guides the agent to maintain focus. These rules instruct the LLM to keep responses concise, only ask clarifying questions when necessary, and only pull in deeper references when they directly help the current decision.

Creating a Custom Skill: A Minimal Example

Adding new capabilities requires no code changes to the Codex runtime. Create a directory under skills/ with the required files:

---  
name: hello-world  
description: A simple example skill that greets the user.  
---  

# Hello World  

## What This Skill Does  

- Recognises a request to say hello.  
- Returns a friendly greeting.  

## Routing Table  

| If the user wants to… | Route to |
|-----------------------|----------|
| Hear a greeting | [say-hello](../say-hello/SKILL.md) |

# plugins/example/skills/hello-world/agents/openai.yaml

policy:
  allow_implicit_invocation: false   # User must explicitly request `$hello-world`

# plugins/example/skills/say-hello/scripts/hello.py

def main():
    print("👋 Hello from the Codex plugin!")

This structure demonstrates how Codex plugins implement the skills framework using pure declarations—the LLM interprets the Markdown and follows the policy YAML automatically.

Summary

• Codex plugins use a convention-driven architecture where skills are defined by Markdown files (SKILL.md), YAML policies (agents/openai.yaml), and optional scripts.
• Discovery occurs by scanning the skills/ directory referenced in .codex-plugin/plugin.json, with the LLM parsing human-readable skill definitions.
• Routing tables in SKILL.md files (such as lines 19-25 in plugins/zoom/skills/start/SKILL.md) map high-level intents to specific implementation skills.
• Policy enforcement through YAML configurations controls whether skills can be invoked implicitly or require explicit references (e.g., $start).
• Execution happens in isolated sandboxes, with scripts like plugins/zotero/skills/zotero/scripts/zotero.py performing concrete API operations.
• Extensibility requires only adding new directories—no changes to the core Codex runtime are needed.

Frequently Asked Questions

How does the Codex skills framework determine which skill to invoke?

The framework uses routing tables defined in each SKILL.md file. When a user makes a request, Codex reads the top-level skill (typically start) and checks its routing table to match the intent. For example, lines 19-25 of plugins/zoom/skills/start/SKILL.md map specific jobs-to-be-done to downstream skills like build-zoom-bot.

What is the difference between implicit and explicit skill invocation?

Implicit invocation allows the LLM to automatically select skills based on request classification, while explicit invocation requires users to name the skill directly (e.g., $build-zoom-bot). The agents/openai.yaml file controls this via allow_implicit_invocation: false, which prevents accidental triggering of sensitive operations.

Where do I place the code that actually executes when a skill is called?

Concrete implementation logic belongs in scripts within skills/<skill>/scripts/. For example, plugins/zotero/skills/zotero/scripts/zotero.py contains Python code that executes when the Zotero skill is invoked. These scripts run in isolated sandboxes and can call external APIs.

Can I add new skills without modifying the Codex runtime?

Yes. The framework is entirely declarative. You add capabilities by creating a new directory under skills/ containing a SKILL.md file, optional agents/ YAML policies, and any implementation scripts. Codex automatically discovers these additions by reading the plugin manifest at .codex-plugin/plugin.json and scanning the skills directory.

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