Creating Claude Code and Codex skills

A skill is a folder holding one SKILL.md file. Claude Code discovers them in ~/.claude/skills/, Codex in ~/.codex/skills/ — same format in both tools. There are two ways to make one: write it by hand, or derive it from your own history. This page covers both honestly.

How a skill works

~/.claude/skills/watch-ci-after-merge/SKILL.md

The file opens with frontmatter — a name and a description — and the description is the whole trigger mechanism. At session start, your assistant loads every installed skill’s description into context (never the body). When the conversation matches what a description says, the assistant loads that skill’s full body and follows it. Nothing else wires a skill up: no registry, no config, no memory-file entry. The description is an index card the assistant always holds; the body arrives only at its moment.

That has one consequence worth designing around: a skill fires as well as its description is written. “Use when a merge just completed, or the user says ‘merged. watch the ci’” fires reliably, because the trigger carries the user’s literal phrases. “Helps with CI workflows” sits idle.

Writing one by hand

Make the folder, write the file:

---
name: watch-ci-after-merge
description: Check CI status after a merge lands, without being asked twice.
  Use when a merge just completed, or the user says "merged. watch the ci".
  Do not use for pre-merge checks.
---

# watch-ci-after-merge

A completed merge is followed by an actual CI status check before the turn
is called finished.

## The moves

- Identify the merge commit or PR just merged
- Check the CI/workflow run status for that commit
- Report pass, fail, or still-running plainly

Both tools pick it up at the next session, with no approval step. Keep the description in the third person, state what it does and when to use it, include the exact phrases that should trigger it, and say what it must not be used for. Keep the moves short and imperative — the body is instructions to the assistant, not documentation for a human.

The hard part isn’t the format. It’s knowing which skills are worth writing — what you actually do repeatedly, what your assistant actually keeps getting wrong, in your own working vocabulary. Most hand-written skills encode a guess about that.

Deriving them from your history

Your answer to “which skills?” already exists, measured: the session history your assistant keeps on disk. stratless reads it and holds a sitting:

$ stratless tune

  Your tune — Claude Code pair

  Measured from this record: 8 rituals · 8 lessons · 9 rules · 1 win · 8 arrivals

  The sitting asks your own Claude Code once — about $0.08 of your plan. Proceed? [y/N] y

  2 skills proposed from the evidence

  THE PACK — every entry is a skill file
    ⚙ watch-ci-after-merge  (occurrences 283 · sessions 88)  new
      A completed merge is followed by an actual CI status check before the turn is called finished.
    ⚙ name-the-mechanism-plainly  (count 4 · sessions 4)  new
      Every direct meaning-question gets a concrete, jargon-free answer naming the actual mechanism.

  writes to ~/.claude/skills · nothing else touched

  Install? [y/N]

It measures what recurs — your command rituals, the lessons that cost you, the demands you keep repeating, what you approve fast, what vocabulary newly arrived — then your own assistant proposes skills from that evidence, and code disposes of every claim: a proposal citing no evidence dies, a quote that isn’t verbatim from your own words dies, every count is stamped from the receipts rather than written by the model. One typed yes installs. The descriptions come out carrying your literal phrases as triggers, because the evidence recorded what you actually say.

Each derived skill is a plain SKILL.md like any other — readable, editable after the fact if you want, deletable as one folder — with a receipts section citing the measured evidence that earned it. Skills you wrote yourself are never touched or duplicated: the sitting reads what’s installed first, by name and by substance, and marks anything your own skills already cover as kept.

Everything runs on your machine. Try the free read first:

npx stratless

See Commands for the full reference, and How it works for the pipeline underneath.