Skills for Claude Code and Codex CLI: The Complete Guide to Creating Reusable Workflows

When you use Claude Code or Codex CLI every day, a problem appears very quickly: you end up repeating the same instructions again and again. You ask the agent to analyze an API according to a precise method, to always check the same points before changing the backend, to follow a particular procedure for security audits, or to run a checklist before a production release. Of course, you can keep those instructions in a text file and copy them into the prompt each time, but that is neither practical nor elegant.

Agent Skills address this problem directly. They let you turn a working method into a reusable workflow that the agent can discover, load, and apply when needed. The idea is simple: instead of constantly explaining how to work, you give the agent a structured procedure stored in a SKILL.md file.

What makes the system especially interesting today is that it is not limited to a single environment. Claude Code and Codex CLI both use the concept of Skills, with a format based on SKILL.md and the open Agent Skills standard. This means that much of a Skill can be written once and then used with both Claude Code and Codex CLI.

The goal of this guide is to understand how the system works, how to create a genuinely portable Skill, how to install it in both environments, and how to avoid the common mistakes that appear when you start building a library of workflows.

What is an Agent Skill?

An Agent Skill is simply a directory containing specialized instructions for an AI agent. In its simplest form, it contains only a SKILL.md file, but it can also include scripts, references, or other resources when the workflow becomes more complex.

A typical structure looks like this:

my-skill/
├── SKILL.md
├── scripts/
├── references/
└── assets/

The SKILL.md file remains the central element. It describes what the Skill does, when it should be used, and which instructions the agent must follow. The other directories are optional and are useful when the Skill needs to run scripts, consult detailed documentation, or use specific resources.

In practice, you can create Skills for many different tasks. A team might have a security-review Skill for security audits, an api-review Skill for examining endpoints, a release-check Skill for checking an application before production, or a database-migration Skill for formalizing its internal migration procedure.

The value is not simply that you “save a prompt”. A Skill lets you capture a working method and make it reusable.

Why use a Skill instead of a long prompt?

The first reason is obvious: it saves time. If you regularly repeat the same instructions, there is no need to rewrite them in every conversation. But the other advantage, often more important, is consistency.

Imagine that one day a developer asks “Analyze this API”, the next day “Perform a complete review of this route”, and a week later “Check whether this endpoint is implemented correctly”. The three requests are very similar, but they do not necessarily communicate the same expectations. Depending on the wording, the agent may check some aspects and overlook others.

With a Skill, the procedure becomes consistent. You can systematically ask the agent to identify the route, input parameters, authentication, error handling, database access, security risks, and response structure. The developer can then make a much simpler request because the agent already knows the procedure it must follow.

That is precisely what makes Skills useful in a professional context. They turn team habits, internal rules, and working methods into workflows that agents can apply more consistently.

Claude Code and Codex CLI share the same basic principle

Claude Code and Codex CLI are not identical, of course, but the core of their Skill systems follows the same principle. In both environments, a Skill can be described with a SKILL.md file containing YAML frontmatter, including a name and description, followed by Markdown instructions.

Here is a minimal example:

---
name: api-review
description: Review an API endpoint for correctness, validation, authentication, error handling and security. Use when the user asks to review, audit or explain an API endpoint.
---

# API Review

Inspect the endpoint implementation.

Check:

1. Route and HTTP method
2. Input parameters
3. Request validation
4. Authentication and authorization
5. Database operations
6. Error handling
7. Response format
8. Security risks

Report problems before suggesting changes.

Do not modify the code unless the user explicitly asks for it.

This file is intentionally simple. It does not use any Claude Code- or Codex-specific feature, which makes it portable between the two environments.

The Agent Skills standard requires at least name and description. The name should match the Skill directory, for example:

api-review/
└── SKILL.md

The name should remain simple, usually lowercase with numbers or hyphens. The description, however, needs much more attention.

The description is probably the most important part

It is easy to think of the description property as a simple piece of information, but it plays an essential role. It helps the agent understand when a Skill should be used.

A description like this is far too vague:

description: Helps with APIs.

It does not explain what the Skill actually does or in which situations it should be triggered. A much more useful version would be:

description: Review REST API endpoints for request validation, authentication, authorization, error handling and security issues. Use when the user asks to audit, review or inspect an API endpoint.

This description gives the agent two essential pieces of information: what the Skill does and when to use it. That is a good rule to remember when creating your own Skills: the description should always answer both questions.

It can also be useful to state what should not trigger the Skill. A security Skill could specify that it should only be used for an explicit security audit or review, and not for a simple request to explain code. The clearer the boundaries between Skills, the more reliable selection becomes.

Building a portable Skill for both environments

Let us take a more realistic example with an api-review Skill. The goal is to create a single file that can be used with both Claude Code and Codex CLI.

---
name: api-review
description: Review and explain API endpoints. Use when the user asks to audit, review, inspect, document or understand an API route or endpoint. Check validation, authentication, authorization, database operations, error handling, response structure and security.
---

# API Review

Review the API endpoint requested by the user.

## Locate the endpoint

Find the file containing the relevant route or handler.

Identify the HTTP method, route path, handler function and framework.

Do not assume the implementation before reading the relevant code.

## Explain the endpoint

Describe the route, its purpose, inputs, authentication requirements and outputs.

For inputs, include path parameters, query parameters, request body fields and relevant headers.

For outputs, describe the success status code, response structure and important returned fields.

## Review the implementation

Check input validation, authentication, authorization, database access, external API calls, error handling, status codes, response validation, logging and hardcoded configuration.

## Security review

Look for missing authorization checks, injection vulnerabilities, unsafe user input, exposed secrets, sensitive data leakage, insecure direct object references and excessive error information.

Do not invent vulnerabilities. Only report issues supported by the code.

## Report findings

Order findings by severity: Critical, High, Medium, Low and Improvements.

For every issue, provide its location, the problem, its impact and a recommended correction.

If no significant issue is found, say so explicitly.

## Modification policy

Do not modify files automatically.

Explain the findings first and only make changes if the user explicitly asks for them.

The content remains deliberately independent of the product being used. That is the key point if you want to maintain a shared workflow library.

Installing the Skill in Claude Code

In Claude Code, a project-specific Skill is generally placed under .claude/skills/.

Our example becomes:

my-project/
└── .claude/
    └── skills/
        └── api-review/
            └── SKILL.md

The full path is:

.claude/skills/api-review/SKILL.md

If you want the Skill to be available in all your projects, place it in your user directory:

~/.claude/skills/api-review/SKILL.md

For a team, it is often more useful to keep Skills directly in the repository. That allows them to be versioned with Git and ensures that every developer follows the same procedures.

You can explicitly invoke a Skill in Claude Code by typing its name as a command:

/api-review

It can also be triggered automatically when the user request matches its description closely enough.

Installing the same Skill in Codex CLI

With Codex CLI, the logic is almost identical, but the location changes. Project Skills are placed under .agents/skills/.

my-project/
└── .agents/
    └── skills/
        └── api-review/
            └── SKILL.md

For a personal Skill available in every project, use:

$HOME/.agents/skills/api-review/SKILL.md

Codex can also scan .agents/skills directories in different parts of a repository, which is particularly useful in monorepos. You can have a general Skill at the project root, a frontend-specific Skill, and another one used only by the backend.

For example:

project/
├── .agents/
│   └── skills/
│       └── project-review/
│
├── frontend/
│   └── .agents/
│       └── skills/
│           └── frontend-review/
│
└── backend/
    └── .agents/
        └── skills/
            └── api-review/

In Codex, explicit invocation uses the $ prefix:

$api-review review the login endpoint

You can also use /skills to see or select available Skills. Like Claude Code, Codex can choose a Skill automatically when a request matches its description.

What really changes between Claude Code and Codex CLI

In practice, the main differences concern file locations and some advanced features.

The core system remains very similar. That is what makes the format interesting for teams using several agents.

How Skills use context

An important point is that a Skill is not necessarily loaded in full on every message. The system uses progressive loading.

At first, the agent mainly needs to know the name and description of the available Skills. That lets it understand which ones exist and choose the one that matches the request. Only after a Skill is selected is the full content of SKILL.md loaded. Additional files in references/, scripts/, or assets/ can then be read when they are needed.

This is important because it prevents a Skill library from injecting all its documentation into every request. A Skill can therefore be fairly rich without consuming its entire content on every exchange.

That does not mean Skills are completely free.

To select a Skill, the agent must know at least that it exists and what its description says. With five or ten well-defined Skills, that cost is generally negligible. With dozens or hundreds of Skills that each have long descriptions, the situation changes. The agent must process more metadata, which can consume context and make selection less precise.

The best strategy is to keep descriptions short, precise, and sufficiently distinct from one another.

Claude Code and Skill cost management

Claude Code loads the information needed to discover Skills, then loads their full content only when they are actually used. It also applies a budget to the amount of information devoted to descriptions so that a very large library does not monopolize the context.

Claude Code also provides a useful tool for monitoring this aspect: /skill-doctor.

This tool identifies the Skills present in the session, how often they are used, and how much context they consume. The idea is simple: if a Skill has been installed for weeks but is never used, it may be better to disable it, make it manual-only, or remove it.

In recent versions of Claude Code, this information is available in the plugin manager’s statistics. That is useful once you start accumulating Skills because it helps distinguish workflows that are genuinely used from those that are needlessly present.

Codex protects its context too

Codex applies its own limit to the information used to discover Skills. The initial list is limited to roughly 2% of the model context window, or 8,000 characters when the context window is unknown.

If the library becomes too large, Codex first shortens descriptions. If that is not enough, some Skills may no longer appear in the initial list.

This protection is useful, but it does not replace good organization. Even if the system automatically limits the context impact, a library that is too large or poorly structured is harder to maintain and makes incorrect triggering more likely.

A large SKILL.md is not necessarily a bad Skill

The fact that a SKILL.md file is long is not necessarily a problem because its full content is generally loaded only when the Skill is used. That does not mean everything should be placed in a single file.

A good practice is to keep SKILL.md focused on the main workflow and move long documentation into a references/ directory.

Take a PostgreSQL Skill:

postgres-review/
├── SKILL.md
└── references/
    ├── indexing.md
    ├── migrations.md
    └── security.md

The main file can simply tell the agent to consult references/indexing.md when analyzing indexes, references/migrations.md when working on a migration, and references/security.md for security checks.

The agent then reads only the documentation it actually needs. This organization also makes Skills much easier to maintain.

Using scripts in a Skill

Skills can also contain scripts. This is useful when an operation needs to be deterministic or reproducible.

For example:

dependency-audit/
├── SKILL.md
└── scripts/
    └── scan.py

The Skill can ask the agent to run the script and analyze its result. This is particularly useful for parsing logs, validating JSON data, extracting a database schema, checking dependency versions, or generating a report.

The simplest rule is to let the agent perform operations it can reasonably handle with its own tools, and to use scripts when a precise or repetitive procedure benefits from automation.

A Skill is not a subagent

Skills and subagents are sometimes confused, but they address different needs.

A Skill mainly provides a procedure, knowledge, and possibly additional resources to the main agent. It is essentially saying: “this is how we perform this task”.

A subagent, by contrast, is closer to delegating work to a separate context or specialized agent. It is used to isolate a task or assign it to a specialized entity.

A Skill does not necessarily create a new agent. It mainly enriches the behavior of the existing agent.

What should become a Skill?

The best candidates are procedures that you repeat regularly. Code review, security audits, release preparation, database migrations, interface analysis, and bug investigations are all good examples.

However, not every project fact should become a Skill.

Rules such as “we use TypeScript”, “the backend is under /backend”, or “always use pnpm” are permanent project information. In Claude Code, they generally belong in CLAUDE.md. In Codex, they can be stored in AGENTS.md.

The distinction is simple: if information should always be known, it belongs in the project’s permanent instructions. If it is a procedure used only for certain tasks, it is probably a good candidate for a Skill.

Avoid mega-Skills

One of the most common mistakes is to create a huge Skill named developer that contains frontend, backend, security, database, testing, deployment, documentation, and CI/CD rules all at once.

On paper, that may seem convenient. In practice, it makes the Skill difficult to select, difficult to maintain, and much less reusable.

It is better to separate responsibilities with Skills such as:

frontend-review
api-review
security-review
database-review
release-check

Each Skill then has a clearly identifiable role.

You should also avoid Skills that overlap too much. If you have api-review, backend-review, code-review, security-review, and quality-review, and all their descriptions say they should be used whenever someone “reviews code”, the agent must choose among several almost identical candidates.

Descriptions should therefore be precise enough for every Skill to have clear territory.

Claude Code-specific features

Although the core format is portable, Claude Code adds some useful extensions.

For example, you can prevent a Skill from being triggered automatically with:

disable-model-invocation: true

This is useful for sensitive workflows such as production deployments, destructive migrations, or operations that should never run without an explicit user decision.

Claude Code also provides several visibility levels to control whether a Skill should be fully active, visible only by name, manual-only, or completely disabled.

These options are useful, but they are specific to Claude Code. If portability is your priority, keep the main workflow in the common standard and use product-specific extensions only when they provide real value.

Codex-specific features

Codex has its own extensions as well.

For example, you can control automatic Skill invocation through agents/openai.yaml:

policy:
  allow_implicit_invocation: false

The Skill remains available, but Codex will no longer invoke it automatically based on a simple prompt match. The user must call it explicitly with:

$skill-name

Codex can also use this file for additional metadata and dependencies.

As with Claude Code, the best strategy is to keep the core workflow portable and use product-specific extensions only when necessary.

A shared library for multiple agents

For a company, the most interesting scenario is probably to maintain an internal library of Skills that is independent of the agents being used.

You might imagine a structure like this:

skills/
├── api-review/
├── security-review/
├── frontend-review/
├── database-review/
├── release-check/
└── documentation/

Each directory contains a SKILL.md based on the common standard. The same Skills can then be exposed through .claude/skills/ for Claude Code and .agents/skills/ for Codex.

This avoids maintaining two completely different libraries for two agents that often perform the same tasks.

Over time, a team can build a kind of “executable operations manual”, where development procedures, checklists, conventions, and audit methods become directly usable by AI agents.

That is probably where their value becomes most significant.

Testing a Skill before trusting it

Creating a Skill is easy. Making sure it works correctly requires more effort.

Two things should be tested separately. The first is triggering: the Skill should be selected when the request genuinely matches its role, but should not appear for unrelated tasks.

For example:

Audit this endpoint.

should logically trigger api-review.

In contrast:

Rename this variable.

should not.

The second thing to test is the result itself. A Skill can trigger at the right time and still provide poor instructions. Compare the responses obtained with and without the Skill, ideally across several realistic requests.

Claude Code and Codex provide tools to create and organize Skills, but final quality still depends heavily on the quality of the instructions and the tests you run.

Be careful with Skills downloaded from the Internet

A Skill should not be treated as a harmless text file. It may contain instructions asking the agent to run commands, execute scripts, access files, or use external resources.

Before installing a Skill found on GitHub or in an unknown repository, read its SKILL.md, inspect its associated scripts, check the commands it asks the agent to run, and understand which files it wants to access.

The safest approach is to treat a third-party Skill like code that you are adding to your development environment, not like a prompt that you are copying into a conversation.

What might a real enterprise library look like?

A team working on a SaaS application could organize its Skills like this:

skills/
├── architecture-review/
│   └── SKILL.md
│
├── api-review/
│   └── SKILL.md
│
├── database-migration/
│   ├── SKILL.md
│   └── references/
│       └── migration-policy.md
│
├── security-review/
│   ├── SKILL.md
│   └── references/
│       ├── auth.md
│       └── secrets.md
│
├── frontend-audit/
│   └── SKILL.md
│
└── release-check/
    ├── SKILL.md
    └── scripts/
        └── validate-release.sh

At this point, Skills are no longer simple shortcuts. They become a way to formalize team know-how and make it directly usable by AI agents.

That is probably where their value becomes truly important.

Skills, prompts, and models are not the same thing

A Skill does not replace the model, and it does not completely replace the user’s prompt.

You can think of the system as a chain:

User
    ↓
Prompt
    ↓
Agent
    ↓
Relevant Skill
    ↓
AI model
    ↓
Tools, terminal and files

The prompt describes the current request. The Skill provides a procedure or working method. The model provides reasoning and generation capabilities, while the agent orchestrates access to the terminal, files, and other tools.

This distinction becomes particularly interesting when the same agent can use several different models behind one interface.

A few simple rules for keeping a library healthy

You do not need fifty Skills to benefit from the system. Five good, well-defined Skills that are genuinely used are usually better than a huge library filled with redundant workflows.

To start, Skills such as api-review, security-review, frontend-review, bug-investigation, and release-check already cover a large portion of common needs.

Then simply observe your daily work. Whenever you catch yourself writing something like “always do A, then B, then C, and check D before finishing”, you have probably found an excellent candidate for a new Skill.

Conversely, if a Skill remains installed for months without ever being used, it probably no longer serves much purpose. That is precisely the kind of situation that tools such as /skill-doctor in Claude Code can help identify.

The real value of Skills

Skills are sometimes presented as a new way to write prompts, but that definition is too narrow.

Their real value is that they allow a team to capture its working methods. Development procedures, checklists, conventions, validation processes, audit methods, and certain internal areas of knowledge can become workflows that agents can use directly.

The model gradually shifts from one where every developer must explain to the AI how they want to work to one where the organization already owns a library of methods that its agents can apply.

For companies using Claude Code, Codex CLI, or other coding agents more and more, this change is probably much more important than it appears today.

Conclusion

Claude Code and Codex CLI now share the same fundamental concept: Agent Skills based on SKILL.md.

Their paths differ:

Claude Code
.claude/skills/

and:

Codex CLI
.agents/skills/

Their explicit invocation methods also differ:

Claude Code
/api-review

versus:

Codex CLI
$api-review

Each environment also adds a few product-specific features.

But the essential point remains the same: a Skill built properly around the common standard can keep the same SKILL.md, the same logic, and much of the same workflow in both environments.

For a team using several coding agents, this is probably the best approach: build a provider-independent workflow library, then use Claude Code or Codex-specific features only when they provide real value.

The goal is not to have as many Skills as possible. The goal is to have a few precise, useful, tested workflows that prevent you from repeatedly explaining to agents how to work.

Sources

Agent Skills — SKILL.md format specification: https://agentskills.io/specification

Anthropic — Claude Code Skills documentation: https://code.claude.com/docs/en/skills

Anthropic — context, Skills, Hooks and Subagents: https://claude.com/blog/steering-claude-code-skills-hooks-rules-subagents-and-more

OpenAI — Codex Skills documentation: https://developers.openai.com/codex/skills

Information checked in September 2026. Claude Code and Codex evolve quickly, so some commands or advanced features may change in future versions.