Skills in Agentic AI: A Beginner's Guide for Codex Users

This note is for a reader who has never used Codex skills, or who has heard the word “skill” but does not yet know where it fits.

The goal is not to memorize every installation detail. The goal is to understand what a skill is, how it differs from nearby concepts, and how to recognize the first repeated workflow that deserves to become a skill.

The Short Definition

A skill is a reusable workflow package that tells Codex how to perform a specific kind of task.

A skill can contain saved instructions, optional reference material, optional assets, and optional scripts. The required core is a SKILL.md file that names the skill, describes when it should be used, and gives Codex the workflow to follow.

The important beginner distinction is this:

Concept	Beginner meaning
Prompt	Something you tell Codex once.
Skill	A saved way of doing a repeated task.

That definition matters because a skill is not just a longer prompt. A prompt lives in the current task. A skill stays available so Codex can reuse it when the task matches.

Why Skills Exist

When someone first uses Codex, they often type task instructions directly:

Review this PR. Check for bugs, missing tests, bad naming, and risky migrations.

Follow our team’s style. Do not rewrite everything. Give actionable comments.

That works once.

After a few days, the repeated pattern becomes visible:

• Use our release checklist.
• Follow our PR review style.
• Use the right test command.
• Check the migration policy.
• Write changelog entries in our format.
• Do not use git add ..

If the same kind of instruction keeps returning, the user is no longer just asking one task-specific question. They are describing a workflow.

A skill exists to preserve that workflow.

Easily said: a skill is a saved way of doing a task.

More precisely: a skill is a discoverable workflow package that gives Codex task-specific instructions, references, examples, and optional executable helpers so Codex can perform repeated work more consistently.

What A Skill Contains

A basic skill can be as small as this:

my-skill/
  SKILL.md

A larger skill can include helper material:

my-skill/
  SKILL.md
  scripts/
  references/
  assets/
  agents/
    openai.yaml

Only SKILL.md is required. The other folders are optional.

OpenAI’s Codex documentation describes a skill as a directory with a SKILL.md file plus optional scripts and references. The SKILL.md file must include name and description. It may also include the instructions Codex should follow. (OpenAI Codex Skills documentation)

The name

The name identifies the skill.

Example:

name: pr-review

The name should be short, stable, and specific enough that the user can invoke it directly.

The description

The description tells Codex when the skill should be used.

Example:

description: Review pull requests and code diffs for correctness, missing tests, risky changes, security issues, and maintainability. Use when the user asks for PR review, code review, or review comments.

This field matters more than beginners usually expect.

Codex can use skills explicitly or implicitly. In explicit use, the user names the skill. In implicit use, Codex chooses a skill because the current task matches the skill description. That means the description is part of discovery, not merely documentation for humans.

A weak description says:

description: Helps with code.

That does not tell Codex when the skill should trigger.

A stronger description says:

description: Review API endpoint changes for request validation, auth checks, error handling, response compatibility, and missing tests. Use when reviewing backend API changes.

The trigger words are visible. The scope is narrow. The boundary is easier to understand.

The Instructions

The instructions are the workflow Codex should follow. For example, a PR review skill might tell Codex to:

1. Inspect the changed files before commenting.
2. Identify correctness issues first.
3. Check whether tests cover the changed behavior.
4. Avoid style-only comments unless they affect maintainability.
5. Return findings grouped by severity.

Instructions are where the user’s repeated judgment becomes reusable. They do not need to describe the whole project. They need to describe the task-specific way Codex should work.

How Codex Uses Skills

Codex does not need to load the full text of every installed skill into every task.

Codex uses progressive disclosure. It starts with each skill’s name, description, and file path. When it decides a skill is relevant, it reads the full SKILL.md instructions for that skill. (OpenAI Codex Skills documentation)

The beginner mental model is:

First, Codex sees the skill name, description, and location.

Then, only if the skill is needed, Codex loads the full SKILL.md, relevant references, and relevant scripts.

This is why a skill can stay available without forcing the user to paste long instructions into every prompt.

Skill Vs Prompt

A prompt is a one-time instruction.

A skill is a reusable workflow Codex can use again later.

Use a prompt when the instruction is temporary:

Review this one file carefully.

Use a skill when the instruction describes repeatable work:

Whenever I ask for a PR review, follow this review process, severity format, and test policy.

The boundary is duration and reuse:

• Prompt: this task only.
• Skill: this kind of task whenever it appears.

Skill Vs AGENTS.md

AGENTS.md is durable project guidance. Codex reads it before work starts so repository or user-level expectations are available broadly. OpenAI’s Codex documentation describes AGENTS.md as custom instructions that can layer global guidance with project-specific overrides. (OpenAI AGENTS.md documentation)

A skill is narrower. It is for one repeatable workflow.

Use AGENTS.md for broad repository or user rules:

• This repo uses pnpm.
• Run pnpm test before submitting changes.
• Do not edit generated files.
• Follow this directory structure.

Use a skill for a task workflow:

• Review a PR.
• Write release notes.
• Triage a bug.
• Create a migration plan.
• Convert a design note into implementation tasks.

A simple boundary:

• AGENTS.md: general rules for this repo or developer.
• Skill: repeatable task-specific workflow.

If every Codex task in the repository should follow the rule, it probably belongs in AGENTS.md. If only one kind of task needs the rule, it may belong in a skill.

Skill Vs Plugin

A skill is the authoring format for a reusable workflow.

A plugin is an installable distribution unit. Plugins can bundle skills, app integrations, and MCP servers into reusable workflows for Codex. (OpenAI Codex Plugins documentation)

Use a direct skill folder while designing or using a local workflow.

Use a plugin when the workflow should be distributed, installed, shared, or bundled with other capabilities.

A useful boundary:

• Skill: the reusable workflow.
• Plugin: a package that can distribute workflows and integrations.

For example, a team might first create a local pr-review skill. Later, if the team wants to distribute several review skills together with GitHub or Linear integration setup, it might package them as a plugin.

Skill Vs MCP

MCP, or Model Context Protocol, connects models and agents to external tools and context. OpenAI’s Codex documentation describes MCP as a way to give Codex access to third-party documentation or developer tools such as browsers and Figma. (OpenAI Codex MCP documentation)

A skill tells Codex what workflow to follow.

MCP gives Codex access to external capabilities.

Example:

• Skill: when handling a production bug, follow this incident-debugging workflow.
• MCP: connect to the logging system, issue tracker, browser, or internal docs.

The skill can say, “Check the issue before coding.” MCP or another connector may be how Codex actually gets access to the issue tracker.

This boundary prevents a common confusion: a skill can describe what Codex should do, but it does not automatically grant new permissions or private data access.

Where Skills Live

Codex can read skills from several scopes, including repository, user, admin, and system locations. The two beginner locations that matter most are:

Scope	Beginner location
One project	repo-root/.agents/skills/
Yourself across projects	$HOME/.agents/skills/

Use a repository skill when the workflow belongs to that project or team.

Use a personal skill when the workflow belongs to the user’s own way of working across projects.

The exact discovery rules can be more detailed, especially in nested repositories and configured environments. For a beginner, the durable principle is enough:

• Put project workflows near the project.
• Put personal workflows near the user.

How To Start Using A Skill

There are two ways to use a skill.

Explicit Use

The user directly mentions the skill.

Example:

$pr-review

Review the current branch against main.

Focus on correctness, missing tests, and risky database changes.

Explicit use is best while learning because it makes the selected workflow visible.

Implicit Use

The user asks naturally:

Review this PR before I merge it.

If the skill description is clear, Codex may choose the matching skill automatically.

This is why trigger words belong in the description. For a PR review skill, words such as PR review, code review, diff review, pull request, and review comments help Codex recognize the match.

A Good First Skill

The best first skill is not ambitious.

Do not start with:

A skill that understands our entire engineering process.

Start with one repeated job:

• review a PR
• write release notes
• create a test plan
• check migration safety
• turn a design note into implementation tasks

A practical first skill is a test-plan skill:

---
name: test-plan
description: Create a focused test plan for a code change. Use when the user asks how to test a feature, bug fix, pull request, or implementation plan.
---
 
Create a test plan for the given change.
 
Follow this structure:
 
1. Behavior under test
   - Identify the user-visible or system-visible behavior being changed.
 
2. Unit tests
   - List the smallest useful tests.
   - Include edge cases.
 
3. Integration tests
   - Identify flows involving multiple modules, APIs, database writes, or external services.
 
4. Regression risks
   - Name existing behavior that might break.
 
5. Manual verification
   - Give concrete steps a developer can perform locally.
 
6. Not covered
   - Explicitly say what this test plan does not verify.

Then the user can ask:

$test-plan

Create a test plan for the changes in this branch.

Or:

I changed the login retry logic. What should I test?

When To Add Scripts

Most beginner skills should be instruction-only.

Add scripts only when deterministic mechanics are useful.

Good reasons to add scripts:

• run the same validation command every time
• parse a changelog
• generate a report
• check file names
• collect test results
• format output in a strict structure

Weak reasons to add scripts:

• the instructions feel long
• the skill should seem more powerful
• the workflow is still unclear

A useful mental model:

• Instructions are for judgment.
• Scripts are for repeatable mechanics.

For example, the instruction might say:

Review whether the migration is risky.

A script might do the mechanical part:

List all migration files changed in this branch.

The script gathers facts. Codex still uses judgment to interpret them.

Common Beginner Mistakes

The first mistake is making the skill too broad.

Bad:

name: backend-helper
description: Helps with backend work.

Better:

name: api-review
description: Review API endpoint changes for request validation, auth checks, error handling, response compatibility, and missing tests. Use when reviewing backend API changes.

A skill should have one job.

The second mistake is putting permanent repository rules into a skill. If every Codex task in the repo should follow a rule, put it in AGENTS.md, not a skill.

The third mistake is hiding the trigger words. Codex’s implicit matching depends on the description, so the important task names should appear early.

The fourth mistake is expecting skills to grant access. A skill can tell Codex what to do, but it cannot by itself authorize private systems, install integrations, or bypass workspace permissions.

The Workflow For Creating Skills

A good skill often grows from repeated real work.

Use this loop:

1. Do the task manually with Codex once.
2. Notice what instructions you had to repeat.
3. Turn the repeated workflow into a skill.
4. Use the skill on a real task.
5. When Codex makes a predictable mistake, update the skill.
6. Keep the skill narrow and practical.

This is better than trying to design the perfect skill from scratch.

The best beginner question is:

What do I keep re-explaining to Codex?

If the answer is a repeated workflow with stable steps and boundaries, it is probably a skill candidate.

Core Mental Model

Use this map:

Surface	Use it for
Prompt	One-time instruction.
AGENTS.md	Broad durable repo or user guidance.
Skill	Reusable workflow for one kind of task.
Plugin	Installable package for skills and integrations.
MCP	Connection layer for external tools and context.

A skill is useful when Codex needs to perform the same kind of work more than once.

Do not try to make Codex smarter in general. Make it better at one repeated job. Then make another skill for the next repeated job.

Connected Reading

Builds on

• Agents, Tools, and Context: When AI Starts Acting in a Workspace. This note explains the broader shift from conversation to agentic work that makes reusable workflows valuable.

Distinctions

• The Relationship Between AI Agents, Codex, and MCP. This note separates Codex from MCP, while the current note separates skills from prompts, AGENTS.md, plugins, and MCP.