Skill vs Agent in Codex Plugins: Understanding the Architectural Distinction

A skill is a deterministic, step-by-step workflow that performs concrete operations like API calls or file generation, while an agent is a specialized AI that interprets, audits, or enriches skill outputs according to policy constraints.

In the openai/plugins repository, the architecture distinguishes between skills and agents to separate deterministic execution from intelligent analysis. Understanding the difference between a skill and an agent in Codex plugins is essential for building predictable, extensible workflows that balance concrete automation with AI-powered review capabilities. According to plugins/zoom/README.md, plugins organize capabilities into distinct skills for workflow execution and agents for reviewer-oriented analysis.

Core Definitions

What Is a Skill?

A skill is a deterministic, step-by-step workflow that teaches the model how to perform a concrete operation. As implemented in plugins/zoom/skills/video-sdk/SKILL.md, skills are designed to be stable, repeatable instructions that the model follows without speculation.

Skills handle specific tasks such as:

• Creating a Zoom meeting via REST API
• Uploading a file to a storage service
• Generating design tokens or configuration files

Each skill resides in plugins/*/skills/…/SKILL.md and contains front-matter defining the name, description, and policy settings. The implementation consists of prompts, bash scripts, or API calls that the model executes verbatim to produce concrete artifacts.

What Is an Agent?

An agent is a specialized, often reviewer-oriented AI that can interpret, audit, or enrich the output of skills. As defined in plugins/zoom/agents/zoom-integration-reviewer.md, agents operate with policies specified in openai.yaml that control invocation rules and cost budgets.

Agents function as higher-level reviewers that:

• Run security scans on newly generated code
• Summarize the outcome of skill runs
• Provide human-like feedback or architectural suggestions

Agent definitions live under plugins/*/agents/…/*.md or .agents/…, and each includes policy files governing whether they may be selected implicitly or only through explicit mentions.

Repository Structure and File Locations

Skills are located in plugins/*/skills/…/SKILL.md. For example, the Zoom plugin defines its video SDK skill in plugins/zoom/skills/video-sdk/SKILL.md, which contains the workflow definition and explicit-only policy front-matter.

Agents are located in plugins/*/agents/…/*.md or .agents/…. The zoom plugin example at plugins/zoom/agents/zoom-integration-reviewer.md demonstrates the standard agent structure, accompanied by plugins/zoom/agents/openai.yaml which governs invocation rules.

Invocation Syntax and Runtime Behavior

Explicit Skill Invocation: Skills use the $ prefix followed by the skill name. When you type $setup-zoom-oauth, the model invokes the deterministic OAuth flow defined in the corresponding SKILL.md file.

# Invoke a skill directly (creates a Zoom OAuth flow)

$setup-zoom-oauth

Explicit Agent Invocation: Agents use the @ prefix followed by the agent name. The command @zoom-integration-reviewer calls the reviewer agent to audit integration results.

# Ask an agent to review the integration

@zoom-integration-reviewer

Runtime Data Flow: Skills produce concrete outputs, typically returning structured JSON at the end of their response:

{
  "status": "success",
  "oauth": {
    "client_id": "xxxx",
    "redirect_uri": "https://example.com/callback"
  }
}

Agents consume this JSON output to perform analysis. The agent reads the skill's result, checks for missing scopes or security issues, and generates a higher-level audit report without modifying the original skill execution.

Policy Control and Implicit Invocation

Both skills and agents use policy files to control invocation, but their default behaviors differ based on architectural roles.

Skills are typically configured as explicit-only with policy.allow_implicit_invocation: false in their front-matter. This ensures skills are only invoked when the user directly mentions them with the $ prefix, preventing accidental execution of concrete operations.

Agents can be either implicit or explicit depending on their openai.yaml configuration. Many reviewer agents are explicit-only to avoid accidental selection during general conversations, but specialized agents may allow implicit invocation when the model detects a need for review.

Cost Accounting: Skills and agents maintain separate token budgets. The openai.yaml policy file lets plugin authors control when each component incurs costs, ensuring that expensive reviewer agents only run when explicitly requested.

Practical Workflow Example

Consider a Zoom integration workflow demonstrating how skills and agents interact:

1. Skill Execution: The user invokes $setup-zoom-oauth, which runs the deterministic workflow from plugins/zoom/skills/video-sdk/SKILL.md. The skill executes the OAuth flow and returns the JSON block shown above.

2. Agent Review: The user then invokes @zoom-integration-reviewer, which accesses the policy from plugins/zoom/agents/openai.yaml. The agent consumes the skill's JSON output, validates security configurations, and produces a concise audit report.

This separation ensures that the OAuth setup follows a predictable, testable path while the security review provides flexible, AI-driven analysis without destabilizing the core workflow.

Summary

• Skills are deterministic workflows located in plugins/*/skills/…/SKILL.md that perform concrete operations using the $ prefix and explicit-only policies.
• Agents are reviewer-oriented AI systems located in plugins/*/agents/…/*.md that interpret skill outputs using the @ prefix and configurable invocation policies.
• Policy Control: Skills minimize accidental execution through policy.allow_implicit_invocation: false, while agents offer flexible implicit or explicit invocation via openai.yaml.
• Extensibility: Agents layer on top of skills without modifying the underlying deterministic workflows, enabling richer analysis while maintaining predictable automation.

Frequently Asked Questions

How do I invoke a skill versus an agent in Codex plugins?

Invoke a skill using the $ prefix followed by the skill name, such as $setup-zoom-oauth. This calls the deterministic workflow defined in the corresponding SKILL.md file. Invoke an agent using the @ prefix followed by the agent name, such as @zoom-integration-reviewer, which triggers the AI reviewer defined in the agent's markdown file located under plugins/*/agents/.

What is the difference between skill and agent policies in the openai/plugins repository?

Skill policies, defined in the front-matter of SKILL.md files, typically set policy.allow_implicit_invocation: false to ensure explicit user consent before executing concrete operations. Agent policies, defined in openai.yaml files within the agents directory, can allow either implicit or explicit invocation depending on whether the agent serves as a background reviewer or requires direct user engagement.

Why should I separate functionality into a skill and an agent instead of combining them?

Separating deterministic execution (skills) from AI analysis (agents) provides predictability and extensibility. Skills offer tightly scoped, testable contracts for concrete operations, while agents can be layered independently to audit different aspects—such as security or architecture—without destabilizing the core workflow. This separation also enables distinct cost accounting and version control for operational code versus review logic.

Where are skills and agents defined in the repository structure?

Skills are defined in plugins/*/skills/…/SKILL.md files, such as plugins/zoom/skills/video-sdk/SKILL.md, which contain the workflow definition and policy front-matter. Agents are defined in plugins/*/agents/…/*.md files (or under .agents/…), such as plugins/zoom/agents/zoom-integration-reviewer.md, accompanied by openai.yaml policy files that govern invocation rules and cost budgets.

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