Replace old custom commands with reusable skills

Understand the approach

Repeated requests often begin as saved text: a release-note checklist, a repository orientation prompt, or a review routine. Codex previously supported custom Markdown prompts in the user prompts directory, invoked through a prompts namespace. The current official documentation marks custom prompts as deprecated and recommends skills. Existing prompts are useful migration inputs; their presence does not make them the preferred format for new work.

A skill gives a workflow a name, a description of when it applies, and instructions in SKILL.md. Repository skills live under .agents/skills so a team can version them with the project. Personal skills can live in the user .agents/skills directory. Unlike a saved prompt that must be inserted manually, a skill can support explicit invocation and description-based selection. An accurate trigger matters as much as the instructions.

Migration is a behavioral redesign, not a filename substitution. Remove assumptions about Claude paths, slash namespaces or implicit permissions. Identify the input, permitted actions and concrete output. A skill that drafts release notes should not also create a commit, open a pull request or publish a release unless those actions are part of the current authorization. Review and run the workflow in a scratch project before treating it as reusable.

A migration changes the workflow contract

The legacy input says review, then asks for npm test, a rewrite and a commit. The starter has no package.json, and a read-only audit should produce findings. The replacement names source files, defines a four-column output and leaves edits for a separately scoped task.

Do not carry Claude-specific argument substitutions, tool front matter or dynamic shell blocks across by analogy. For this instruction-only skill, the target README is ordinary request text. The optional Codex metadata file is a separate documented format; it is unnecessary for this first migration.

A small migration is easier to trust

Start with a read-only workflow that returns a document. Add scripts only when deterministic processing is useful. Record which legacy behavior remains and what changes, so reviewers can compare the migration without modifying global configuration.

Try it step by step

1. Choose one saved request that you repeat and describe a successful outcome without relying on its old command name.
2. List the files or information it consumes, the output it creates, and actions it is not authorized to take.
3. Draft a skill description that distinguishes a positive trigger from a nearby task that should not activate it.
4. Test the draft manually with two contrasting requests, then move to the complete skill-creation exercise in the next lessons.

A useful starting example

Illustration · adapt before use.

---
name: readme-check
description: Audit README setup claims against source files. Use for read-only README checks, not implementation.
---
Read README.md, notes.cjs and checks.cjs. Check whether package.json exists.
Return Claim, Evidence, Finding and Suggested correction.
Label unrun commands; do not edit, install, commit or publish.

Check your result

• The plan uses the current SKILL.md format rather than creating a new deprecated custom-prompt setup.
• Its trigger clearly distinguishes orientation from implementation or release publication.
• The proposed output can be checked against specific project files without relying on a confident summary.

Common mistakes

• Mechanically renaming .claude/commands to a Codex directory while retaining incompatible front matter and invocation syntax.
• Packaging broad execution authority into a convenience shortcut for what was originally a drafting task.