Codex skills: create a reusable handoff with SKILL.md

Codex skills are reusable workflows stored in a folder containing SKILL.md. That file defines the skill’s name, when to use it, and the steps to follow. Optional scripts, references and templates can accompany it. A skill can work entirely with local instructions; it does not require AMS or an MCP server. See OpenAI’s skills overview. This guide builds a small skill that prepares a useful handoff for another coding agent or human reviewer. It drafts the evidence and next action before you decide how to share them. Official documentation checked 5 November 2026. The sample skill is an instruction-only example; the output below is a checklist, not a recorded Codex execution.

Skills, AGENTS.md and MCP solve different problems

Mechanism	What it supplies	Example in a review workflow
Skill	A reusable procedure selected for a task	Gather evidence and format a review handoff
`AGENTS.md`	Project instructions Codex reads at startup	Preserve unrelated edits and run the repository’s required checks
MCP connection	Tools and information from another system	Read or send a message in an authorized AMS channel

Keep repository rules in AGENTS.md and the repeatable handoff procedure in a skill. A skill cannot supply a missing tool connection or its authorization. OpenAI documents project instruction discovery, MCP connections, and how skills complement MCP tools separately. A skill also does not create another agent task. For delegation or independent Codex chats, see running multiple Codex agents.

Prerequisites and location

Use an installed Codex CLI or IDE extension with access to a Git repository and a readable README.md. No new package, API key or external account is needed for this exercise. Current OpenAI skill locations include:

Scope	Location	Use it for
Repository	`.agents/skills/` between the working directory and repository root	A workflow shared with the project
Personal	`~/.agents/skills/`	Your workflows across repositories
Administrator	`/etc/codex/skills/`	Machine-wide skills
System	Bundled with Codex	OpenAI’s built-in skills

The example uses repository scope. Open Codex in that repository; a skill in an unrelated checkout is outside this scope. Skills in separate worktrees need to be present in the checkout being used.

1. Create SKILL.md

From the repository root, create the directory:

mkdir -p .agents/skills/review-handoff

Create .agents/skills/review-handoff/SKILL.md with this content. Preserve any existing skill at that path instead of overwriting it.

---
name: review-handoff
description: Prepare a review handoff for a named file or change and a teammate. Use when asked to summarize evidence and next steps for review; do not use for implementation or sending messages.
---

# Prepare a review handoff

1. Identify the recipient, goal and allowed file scope from the request.
   If scope is missing, ask for it before inspecting unrelated work.
2. Follow the applicable project instructions. Read the named files.
   In a Git repository, inspect their status and diff without changing them.
3. Separate observed file contents, local changes and proposed follow-up.
   If there is no diff, say so. Include new untracked files only when in scope.
4. Report checks actually run and their results. Mark everything else
   "not run". Never turn an assumption into a passing test result.
5. Return a short handoff with these fields:
   - Goal and recipient
   - Files and revision or working-tree state reviewed
   - Findings and supporting evidence
   - Checks and remaining uncertainty
   - One concrete next action for the recipient
6. Draft in the conversation. Do not edit files, send messages, change
   ownership, commit or publish as part of this skill.

The YAML name and description are required. Codex initially sees skill metadata and reads the full instructions when it selects the skill. Keep detailed steps in the body. See OpenAI’s skill format and discovery rules.

2. Invoke the skill explicitly

In Codex CLI or the IDE extension, use /skills or mention the skill with $. Try this prompt:

$review-handoff Prepare a handoff for a teammate to review README.md.
Read README.md and inspect changes to that file. Do not edit files,
run project tests, or send messages. The next action should be a
specific documentation check the teammate can perform.

Codex can also select skills when a request matches their description. For example: “Prepare a review handoff for README.md for my teammate.” See OpenAI’s invocation rules.

3. Check the result

The handoff should identify what was read, explain a concrete review question, and give the recipient enough evidence to continue. Check that:

The findings refer to actual README.md content or its diff.
The working-tree state is stated accurately, including “no changes” when appropriate.
Checks say “not run” because the prompt prohibited project tests.
The next action names a specific section, command or claim to verify.
The skill has left files and external channels untouched.

A short handoff can still be incomplete. If a command in the README depends on a service the author did not start, the next reviewer needs that limitation, rather than an unsupported “ready” label. Then try an ordinary question such as “Explain the purpose of README.md.” It should not need this handoff procedure. Explicit, implicit and unrelated prompts help reveal a description that triggers too broadly; OpenAI describes this approach in testing skills with evals. AMS is useful when independent tasks need a common message history, including a Claude Code and Codex workflow. The skill above produces the content; AMS supplies a place to share it. With the AMS CLI already installed and connected, preview its managed Codex integration:

ams integrate codex --user --dry-run

After reviewing the proposed changes, install it and check its state:

ams integrate codex --user
ams integrate check --user

The user integration installs the managed use-ams skill under ~/.agents/skills/use-ams/ and a marked block in Codex’s active global instruction file. It does not set up MCP or enable a working folder. Follow workspace activation to choose the intended workspace and scope deliberately. For an authorized handoff, ask Codex to use the installed use-ams workflow to post the reviewed draft to your agreed channel. It must first check activation from its actual working folder:

ams workspace current --json

Only after a successful enabled: true result, verify the destination and read current context:

ams --require-workspace status
ams --require-workspace messages --resume

Keep reading if the footer says (more available). Before sending, confirm the workspace, channel and task identity, and reconcile any conflicting file claim. Check the returned message ID and link after the send. Do not put tokens or private data in the handoff. AMS stores the handoff; it does not itself wake an inactive Codex chat, transfer uncommitted files, or prove the recipient accepted the work. Continue the recipient through its host and have it read the channel. Require acknowledgement before depending on an ownership change. See sharing context between coding agents.

Troubleshooting

Symptom	What to check
The local skill is missing	Confirm the path, required YAML fields and working directory. Restart Codex if automatic detection has not picked it up.
Two entries have the same name	Inspect their paths and give your custom skill a distinct name. Codex does not merge same-name skills.
Explicit invocation works, but automatic selection does not	Tighten the description around the request you tested. Check whether `agents/openai.yaml` disables implicit invocation.
The handoff claims unrun checks passed	Correct the output, then make the evidence rule explicit and retest the same prompt.
A teammate cannot inspect the cited file	Share an accessible revision or artifact; a local path alone does not transfer a file.
AMS stays off	Check folder activation and the actual error. An installed skill alone does not enable coordination.
A message is stored, but work does not resume	Continue the receiving task in its host and request a channel read and acknowledgement.

For local discovery, invocation policy and configuration details, use the current OpenAI Build skills reference. For the optional messaging connection, use the Codex MCP setup guide.

Get started

Build with AMS

MCP

Compare and connect coding agents

Skills and hooks

Agent workflows

Codex skills: create a reusable handoff with SKILL.md

Skills, AGENTS.md and MCP solve different problems

Prerequisites and location

1. Create SKILL.md

2. Invoke the skill explicitly

3. Check the result

Troubleshooting

Skills, AGENTS.md and MCP solve different problems

Prerequisites and location

1. Create SKILL.md

2. Invoke the skill explicitly

3. Check the result

Optional: share the reviewed handoff through AMS

Troubleshooting