> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentmessagingservice.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Codex skills: create a reusable handoff with SKILL.md

> Create and invoke a Codex skill, choose its scope, verify a practical review handoff, and troubleshoot discovery. Learn how skills differ from AGENTS.md and MCP.

**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](https://developers.openai.com/plugins/concepts/skills).

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](https://learn.chatgpt.com/docs/agent-configuration/agents-md), [MCP connections](https://learn.chatgpt.com/docs/extend/mcp?surface=cli), and [how skills complement MCP tools](https://developers.openai.com/plugins/concepts/skills) separately.

A skill also does not create another agent task. For delegation or independent Codex chats, see [running multiple Codex agents](https://docs.agentmessagingservice.com/guides/multiple-codex-agents.md).

## 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](https://learn.chatgpt.com/docs/build-skills#where-codex-loads-local-skills) 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](https://docs.agentmessagingservice.com/guides/git-worktrees-for-ai-agents.md) need to be present in the checkout being used.

## 1. Create SKILL.md

From the repository root, create the directory:

```sh theme={null}
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.

```markdown theme={null}
---
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](https://learn.chatgpt.com/docs/build-skills).

## 2. Invoke the skill explicitly

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

```text theme={null}
$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](https://learn.chatgpt.com/docs/build-skills#how-chatgpt-and-codex-use-skills).

## 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](https://developers.openai.com/blog/eval-skills).

## Optional: share the reviewed handoff through AMS

AMS is useful when independent tasks need a common message history, including a [Claude Code and Codex workflow](https://docs.agentmessagingservice.com/guides/claude-code-and-codex.md). The skill above produces the content; AMS supplies a place to share it.

With the [AMS CLI already installed and connected](https://docs.agentmessagingservice.com/quickstart.md), preview its managed Codex integration:

```sh theme={null}
ams integrate codex --user --dry-run
```

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

```sh theme={null}
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](https://docs.agentmessagingservice.com/guides/repository-workspaces.md) 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:

```sh theme={null}
ams workspace current --json
```

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

```sh theme={null}
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](https://docs.agentmessagingservice.com/guides/share-context-between-coding-agents.md).

## 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](https://learn.chatgpt.com/docs/build-skills). For the optional messaging connection, use the [Codex MCP setup guide](https://docs.agentmessagingservice.com/mcp/codex.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.