Write your first Codex skill: $skill-creator and by hand

What we are building

This tutorial builds pr-description: a skill that writes a pull request description from the current branch. It is small enough to finish in twenty minutes and realistic enough to show the parts that matter: a description that triggers, steps with clear outputs, a helper script, and a test loop.

You need the Codex CLI or IDE extension and a git repository with a feature branch. If you have not installed Codex yet, see the Codex CLI guide.

Step 1: write the test prompts first

Before writing any instructions, decide when the skill should load. Write two short lists:

Should load the skill	Should not load it
“write the PR description”	“review this PR”
“open a pull request for this branch”	“fix the failing test”
“summarize my changes for reviewers”	“write release notes for v2.4”
“draft the PR body, we use the template in .github”	“what does this function do”

These become your acceptance test. They also tell you which words belong in the description.

Step 2a: draft it with $skill-creator

Codex ships a system skill for writing skills. Start Codex in your repository and mention it:

$skill-creator I want a skill called pr-description. It writes a pull request
description for the current branch: summary, why, what changed, how it was
tested, risks. It should read .github/pull_request_template.md if it exists.
It should trigger when I ask to write a PR description, open a PR, or summarize
my branch for reviewers, but not for code review or release notes.
Save it in ~/.agents/skills.

The creator asks follow-up questions about purpose, triggers and whether the skill should stay instruction-only or include scripts. Instruction-only is the default. Answer them, then read the draft it produces before accepting it. Check three things:

1. The description includes your trigger phrases and the “not for” boundary.
2. The steps name real commands rather than general advice.
3. Nothing in the body applies to every task; that belongs in AGENTS.md.

If the draft is good, skip to step 3. Writing it by hand once is still worth doing, because you will edit skills by hand far more often than you create them.

Step 2b: write it by hand

Create the folder. The folder name must match the skill name:

mkdir -p ~/.agents/skills/pr-description/scripts

Write ~/.agents/skills/pr-description/SKILL.md:

---
name: pr-description
description: Writes a pull request title and description for the current git branch - summary, motivation, changes, test evidence and risks - following the repository's PR template when one exists. Use when the user asks to write or update a PR description, open a pull request, or summarize a branch for reviewers. Not for reviewing someone else's PR or writing release notes.
---

# PR description

Done means: a title under 72 characters and a description a reviewer can read in
two minutes, saved to `.git/PR_DESCRIPTION.md`, with every claim about testing
backed by a command you ran.

## Steps

1. Find the base branch: use the one the user named, else `main`, else `master`.
2. Run `scripts/branch_context.sh <base>` and read its output.
3. If `.github/pull_request_template.md` exists, use its headings in order.
   Otherwise use: Summary, Why, Changes, Testing, Risks.
4. Summary: one or two sentences on the user-visible effect.
5. Why: the problem or ticket. Ask the user if you cannot tell from commits.
6. Changes: group by area, not by file. Skip formatting-only changes.
7. Testing: list the commands you ran and their result. If you did not run
   tests, say so plainly.
8. Risks: migrations, config changes, feature flags, anything hard to roll back.

## Rules

- Do not invent test results, ticket numbers or screenshots.
- Do not push or open the PR unless the user asks; print the `gh pr create`
  command instead.

## Output

Print the title, then the description, then the path you saved it to.

Add the helper script at ~/.agents/skills/pr-description/scripts/branch_context.sh:

#!/usr/bin/env bash
# Prints the commits and changed files between a base branch and HEAD.
set -euo pipefail
base="${1:-main}"
if ! git rev-parse --verify --quiet "$base" >/dev/null; then
  echo "error: base branch '$base' not found" >&2
  exit 1
fi
echo "## Commits"
git log --no-merges --format='- %s' "$base"..HEAD
echo
echo "## Files changed"
git diff --stat "$base"...HEAD

chmod +x ~/.agents/skills/pr-description/scripts/branch_context.sh

Why a script here? Collecting branch context is the same three commands every time, and a script makes the output format predictable. The judgment calls (grouping changes, describing risk) stay in the instructions, where Codex can adapt them.

Optionally, add agents/openai.yaml for nicer presentation in the ChatGPT desktop app:

interface:
  display_name: "PR description"
  short_description: "Write a PR description for this branch"
  default_prompt: "Write the PR description for my current branch"

Step 3: confirm Codex sees it

Codex detects new skills automatically. In a Codex session, run:

/skills

pr-description should be in the list. If it is not:

• Check the path: ls ~/.agents/skills/pr-description/SKILL.md.
• Make sure the file starts with --- on line 1 and the YAML parses (a colon inside an unquoted description can break it; wrap the value in quotes if needed).
• Restart Codex.

Step 4: test explicit invocation

On a feature branch, run:

$pr-description base is develop

This forces the skill to load, so it tests the instructions rather than the description. Check the output against the definition of done at the top of SKILL.md. Did it run the script? Did it claim tests passed without running them? Fix the instructions, not the output.

Step 5: test implicit triggering

Start a fresh session for each prompt so earlier turns do not influence the result, and type the prompts from step 1 without any $ mention. For each, note whether the skill loaded. You can ask Codex directly afterwards: “Which skills did you use for that?”

Typical results on a first draft:

• It loads for “write the PR description” but not for “summarize my changes for reviewers”. Add “summarize a branch” and “for reviewers” to the description.
• It loads for “write release notes”. Strengthen the boundary sentence and make sure a release notes skill, if you have one, says what it covers.

Keep the description’s first clause about the job, because Codex shortens descriptions when many skills are installed and the start is what survives.

If a skill should never load on its own, for example because it pushes code, set this in agents/openai.yaml and use it only via $name:

policy:
  allow_implicit_invocation: false

Step 6: share it

To give the skill to your team, move it into the repository and commit it:

mkdir -p .agents/skills
mv ~/.agents/skills/pr-description .agents/skills/
git add .agents/skills/pr-description
git commit -m "Add pr-description Codex skill"

Repository skills are also available in Codex cloud tasks; personal skills are not synced there. The team sharing guide covers review and versioning, and plugins are the route when you want to distribute skills beyond one repository.

What to read next

• The SKILL.md format reference for every field and folder.
• Annotated skill examples for patterns worth copying.
• The skill-authoring, skill-scripts-packaging and skill-evals skills, which let Codex help you write, package and test the next one.