Codex Custom Prompts skill for Codex

A reusable prompt is done well when it is invoked by a short name, takes its inputs explicitly, states its own definition of done, is versioned where the team can see it, and never fires on requests it was not written for.

Choose the format

Custom prompts (~/.codex/prompts/*.md, invoked as /prompts:<name>) are deprecated in favour of skills. They still load in current releases, but new work should be a skill.

Need	Format
Team-shared command for this repo	Skill in <repo>/.agents/skills/<name>/SKILL.md, explicit-only
Personal command across all repos	Skill in ~/.agents/skills/<name>/SKILL.md
Codex should pick it up automatically from the request	Skill with implicit invocation (the default)
Scripted, non-interactive reuse	Prompt file piped to codex exec -
Existing /prompts: file you rely on today	Keep it working, schedule the conversion below

Skills are invoked with $name in the composer or picked from /skills; they need no restart in most cases (restart Codex if a new skill does not appear).

Workflow

- [ ] 1. Capture the repeated task from two or three real past requests
- [ ] 2. Decide inputs, steps and done-criteria
- [ ] 3. Write it as a skill (or legacy prompt if required)
- [ ] 4. Set invocation policy
- [ ] 5. Test with real inputs and an unrelated request

1. Capture the task

Collect the actual wording of past requests (“open a draft PR for these files”, “write release notes since the last tag”). The common steps become the body; the parts that vary become inputs.

2. Inputs, steps, done

Write down: required inputs, optional inputs with defaults, the commands to run, what must never happen, and the exact output.

3a. Write it as a skill (recommended)

.agents/skills/draft-pr/
├── SKILL.md
└── agents/openai.yaml      # optional: keep it explicit-only

---
name: draft-pr
description: Creates a dev/<feature> branch, commits the staged or named files with a conventional message, and opens a draft pull request with gh. Use only when the user invokes $draft-pr.
---

## Inputs
- FILES (optional): paths to stage. Default: whatever is already staged.
- TITLE (optional): PR title. Default: summarize the diff in under 70 characters.

## Steps
1. Run `git status --short`; stop and ask if nothing is staged and no FILES were given.
2. Create `dev/<short-feature-name>` from the current branch.
3. Stage FILES if given; commit with a conventional commit message.
4. Ask for confirmation, then push and run `gh pr create --draft --title "<TITLE>" --body-file -`.

## Done
Print the branch name, commit SHA and PR URL. Never force-push.

Invocation: $draft-pr FILES="src/api.ts src/api.test.ts" TITLE="Add retry". Skills do not expand placeholders; the agent reads the values from the message, so name inputs in the Inputs section exactly as users will type them.

3b. Legacy custom prompt (only if you must)

---
description: Prep a branch, commit, and open a draft PR
argument-hint: [FILES=<paths>] [PR_TITLE="<title>"]
---
Create a branch named `dev/<feature_name>` for this work.
If files are specified, stage them first: $FILES.
Open a draft PR. Use $PR_TITLE when supplied; otherwise write a concise title.

Placeholder rules:

Syntax	Expands to
$1 … $9	Positional, space-separated arguments
$ARGUMENTS	All arguments
$FILE, $TICKET_ID (uppercase)	Named KEY=value arguments; quote values with spaces
$$	A literal $

Constraints: files live directly in ~/.codex/prompts/ (subdirectories are ignored), only .md files load, edits need a Codex restart or new chat, and they are not shared through the repository.

3c. Prompt file for scripts

codex exec - < .codex-prompts/release-notes.md
printf 'Write release notes for %s..HEAD\n' "$(git describe --tags --abbrev=0)" | codex exec -

4. Invocation policy

To make a skill behave like a slash command that never auto-triggers:

# agents/openai.yaml
policy:
  allow_implicit_invocation: false

Leave implicit invocation on only when the description has precise trigger phrases and clear exclusions.

5. Test

• Invoke it with typical inputs, with no inputs, and with a value containing spaces.
• Send an unrelated request in a fresh chat and confirm the skill does not load.
• For side-effecting commands (push, PR, deploy), confirm the skill asks before acting.

Converting legacy prompts to skills

Prompt file element	Skill equivalent
~/.codex/prompts/name.md	~/.agents/skills/name/SKILL.md or repo .agents/skills/name/
description: front matter	description: (rewrite: what it does + when to use it)
argument-hint:	## Inputs section with defaults
$1, $ARGUMENTS, $NAME	Named inputs the agent reads from the message
/prompts:name	$name or /skills
Restart to reload	Picked up automatically; restart if missing

Add name: equal to the folder name, keep the body steps, and delete the old prompt file once the skill is verified, so two versions do not drift.

Gotchas

• A skill description written like a command (“Run this to…”) without trigger and exclusion phrases can fire on unrelated requests; set allow_implicit_invocation: false for command-style skills.
• Prompt files under subdirectories of ~/.codex/prompts/ are silently ignored.
• Uppercase $WORD tokens in a legacy prompt are parsed as named placeholders, so a shell variable such as $HOME in the text may not survive expansion; write $$HOME to emit it literally.
• Do not put secrets or tokens in prompt files or skills; reference environment variables the commands read at run time.
• Skills with the same name in two locations both appear; they are not merged.

Output

When asked to create a reusable command, deliver: the file path(s), the full file contents, one example invocation, and the result of the trigger test.