# Skill vs Agent in Codex Plugins: Understanding the Architectural Distinction

> Understand the distinction between a skill and an agent in Codex plugins. Learn how skills perform concrete operations while agents interpret and audit their outputs.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: deep-dive
- Published: 2026-06-29

---

**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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/plugins/zoom/agents/zoom-integration-reviewer.md), agents operate with policies specified in [`openai.yaml`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/plugins/zoom/agents/zoom-integration-reviewer.md) demonstrates the standard agent structure, accompanied by [`plugins/zoom/agents/openai.yaml`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/SKILL.md) file.

```markdown

# 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.

```markdown

# 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:

```json
{
  "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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/plugins/zoom/agents/zoom-integration-reviewer.md), accompanied by [`openai.yaml`](https://github.com/openai/plugins/blob/main/openai.yaml) policy files that govern invocation rules and cost budgets.