Agents and Skills: The Worker and the Playbook

An agent and a skill can look similar from a distance: both contain instructions, both can mention tools, and both can shape how work gets done. But they occupy different layers of an AI system.

An agent is the actor. A skill is a reusable way of working.

The distinction matters because it changes what you configure, where permissions belong, and how you make a system easier to maintain.

The shortest useful definition

An agent is a running instance that receives a goal, reasons about it, chooses actions, uses tools, and returns a result. It has a working context and may have its own model, instructions, permissions, and tool connections. In a multi-agent workflow, a primary agent can delegate bounded tasks to specialized subagents and combine their findings.

A skill is a packaged capability: instructions, reference material, templates, and sometimes scripts for completing a repeatable kind of task. A skill does not independently decide to act. An agent selects it, loads its guidance, and applies it.

A useful analogy is a colleague and a playbook. The colleague can interpret the situation, make decisions, and operate within their access. The playbook gives that colleague a tested method for one class of work. A playbook without a colleague is inert; a colleague without playbooks can still work, but may repeat decisions and produce inconsistent results.

What an agent contains

An agent definition answers: Who should do this work, under what operating conditions?

In current Codex custom-agent configuration, each agent is a standalone TOML file. The required fields are:

• name: the identity Codex uses to refer to the agent.
• description: human-facing guidance about when the agent should be used.
• developer_instructions: the agent's core behavior, boundaries, and working method.

A useful agent definition often adds operational settings such as:

• model and model_reasoning_effort for the intelligence and deliberation appropriate to the job.
• sandbox_mode for the filesystem boundary.
• mcp_servers for the external systems the agent can reach.
• skills.config for skill availability or configuration.

The official Codex subagents documentation describes these files as configuration layers for spawned sessions. That is an important clue: an agent is not merely a prompt. It is a runtime role with instructions plus execution settings.

A good definition also states the practical contract in plain language:

• The job to perform.
• The evidence to gather.
• Actions that are in scope and out of scope.
• The expected output.
• The stopping condition.
• When to escalate uncertainty to the parent agent or user.

For example, a documentation researcher might be told to verify version-specific behavior against primary sources, provide links, and never change code. A review agent might be told to prioritize correctness, security, regressions, and test gaps while ignoring purely stylistic preferences.

Agent files do not use skill-style front matter

This is an easy source of confusion. A Codex custom agent is typically defined in TOML, not in a Markdown file with YAML front matter. Its name, description, and developer_instructions are TOML keys, alongside any model, sandbox, MCP, or skill configuration.

There is also AGENTS.md, but that is not the definition of one named agent. It is layered project guidance that Codex reads before work begins. Put repository conventions, build and test commands, security rules, review expectations, and directory-specific overrides there. Codex combines applicable guidance from the project root toward the working directory, with closer instructions taking precedence. The AGENTS.md documentation explains that discovery and override chain.

Think of the three pieces this way:

• A custom agent file defines a specialist.
• AGENTS.md defines the local rules of the workplace.
• A skill defines a reusable procedure.

What a skill contains

A skill answers a different question: How should this repeatable task be done?

A Codex skill is a directory whose required entry point is SKILL.md. That file starts with YAML front matter containing at least:

• name: a stable, concise identifier.
• description: what the skill does and, crucially, when it should or should not activate.

The rest of SKILL.md contains the procedure. Strong skill instructions specify inputs, steps, decision points, required checks, outputs, and failure or escalation behavior. They are written as an executable workflow for an agent, not as general background reading.

A skill directory can also include:

• scripts/ for deterministic operations or external tooling.
• references/ for documentation the agent should consult only when relevant.
• assets/ for templates and reusable resources.
• agents/openai.yaml for optional presentation metadata, invocation policy, and tool dependencies.

The optional agents/openai.yaml can supply interface details such as a display name, icons, brand color, and a default prompt. It can also set allow_implicit_invocation and declare tool dependencies. OpenAI's skill-building guide documents this structure and recommends focused skills with imperative steps and explicit inputs and outputs.

That separation keeps SKILL.md readable. The workflow lives in one place; heavyweight references, scripts, and visual assets are loaded only when needed.

How agents use skills

Skills use progressive disclosure. At the start of a task, an agent usually sees a compact catalog of skill names and descriptions. It does not load every skill in full. When the user explicitly invokes a skill—or the request clearly matches a skill's description—the agent reads the complete SKILL.md and follows the relevant resources it references.

The flow is straightforward:

1. The agent receives a goal within its current instructions and permissions.
2. It compares that goal with the available skill descriptions.
3. It selects a matching skill explicitly or implicitly.
4. It reads the full procedure and only the supporting resources needed for this task.
5. It uses its available tools to carry out the procedure.
6. It validates the result and returns the requested output.

This design saves context. A ten-page procedure does not occupy the working prompt for every request; only its short description does until the procedure becomes relevant.

A primary agent can also delegate work to a subagent that has a more suitable definition. That subagent may use applicable skills of its own. The relationship is compositional: the parent owns the larger outcome, the subagent owns a bounded piece of work, and the skill supplies a method.

Tools, dependencies, and permissions are not the same thing

“Allowed tools” is often used loosely, but three concepts should remain separate.

A tool dependency says a workflow expects a capability, such as an MCP server that can query documentation. A tool configuration makes a capability available to an agent. A permission boundary determines whether a particular action is actually allowed at runtime.

A skill can declare that it depends on a tool. That declaration does not automatically grant credentials, bypass a sandbox, or approve a consequential action. Likewise, an agent can be configured with an MCP server while still being constrained by the parent session's permissions and the server's own authorization.

In Codex, an agent's effective tool surface is shaped by the runtime, inherited settings, enabled MCP servers, sandbox mode, and host permissions. Skills describe how to use capabilities and can declare dependencies; they should not be treated as a security boundary.

Some agent frameworks expose a literal allowed_tools field. If you use one, treat it as an allowlist enforced by the runtime. Do not rely on prose such as “only use read tools” when the platform can enforce that restriction structurally. The exact key varies by host, so document the concept without assuming every system uses the same schema.

What belongs where

Put guidance in AGENTS.md when it should apply broadly to work in a repository or directory: commands, conventions, review criteria, architecture notes, and local safety rules.

Create a custom agent when a job benefits from a distinct worker: a different model, reasoning level, sandbox, MCP connection, or strongly bounded role. Good examples include a read-only code explorer, a security reviewer, or a documentation researcher.

Create a skill when the value lies in a repeatable method that more than one agent—or the same agent across many tasks—should reuse. Good examples include repairing CI failures, preparing a launch brief, triaging an incident, or converting raw research into a cited report.

If the instructions describe identity and operating conditions, they probably belong to an agent. If they describe a procedure and its resources, they probably belong to a skill. If they describe the rules of the environment, they probably belong in AGENTS.md.

A concrete example

Imagine a team investigating a production incident.

The repository's AGENTS.md supplies shared facts: service ownership, approved diagnostic commands, data-handling rules, and the tests required before a fix.

A custom incident_investigator agent supplies the role: remain read-only, inspect logs and traces, build a timestamped timeline, and return evidence with confidence levels. Its configuration can select a suitable model and expose only the relevant observability MCP server.

An incident-triage skill supplies the workflow: confirm impact, identify the first bad event, compare recent changes, test competing hypotheses, capture evidence, and produce a standard incident summary.

The agent is the investigator. The skill is the playbook. AGENTS.md is the operating environment. The observability connection is a tool. Runtime policy decides what the investigator may actually do.

Design for composition, not accumulation

The most reliable systems keep these layers small and legible.

Give each agent one clear role. Give each skill one coherent job. Put stable, shared rules in AGENTS.md instead of copying them into every definition. Prefer instructions to scripts until deterministic behavior or external tooling is genuinely necessary. Declare required tools explicitly, but enforce access through the runtime.

Most importantly, write descriptions as routing logic. An agent description should tell the parent when delegation will help. A skill description should make activation predictable, including important exclusions. Vague descriptions create accidental matches; sprawling definitions create conflicts.

The goal is not to encode every possible decision. It is to create a clean handoff between judgment and procedure: agents decide and act, while skills make proven ways of working portable.