Skills

The last chapter taught Codex to scale work — fan a recategorisation job across parallel subagents and worktrees so years of history get reprocessed without crowding your main thread. This chapter teaches it something closer to a habit: a procedure you do over and over, written down once so Codex runs it itself the moment the situation calls for it. It’s the natural next step after rules. Rules are the standing facts about budgetcli — money is integer cents, the category list. A Skill is a routine — a named, multi-step thing Codex does, not just knows.

A Skill is a directory with a SKILL.md file in it. The frontmatter says when to use it; the body says what to do. Codex keeps every Skill’s description in view, and when your request matches one, it pulls in the full instructions and follows them — no procedure re-pasted, no shape re-explained. You can still name a Skill explicitly when you want to; the new thing is that it can fire on recognition. Skills are documented on the Codex Skills page; this chapter walks the whole arc on one concrete procedure.

The procedure we’ll package

You’re still living in budgetcli. The import path works for the two banks your friend wired up before handing the project over — but you have accounts at others, and every one of them exports its transaction history in a slightly different shape. Different column headers. Dates as MM/DD/YYYY in one file, YYYY-MM-DD in another. One bank splits debits and credits into two columns; another uses a single signed amount. One quotes the merchant name; another doesn’t. And the money — always the trap — arrives as a decimal string like 42.50 that has to become the integer 4250 cents budgetcli stores internally, never a float.

Onboarding a new bank is the same job every time, even though every file is different:

• read a sample of the export and work out which column is the date, the amount, the description
• map those columns onto budgetcli’s transaction fields
• normalise the date to the project’s format
• convert the decimal amount to integer cents, getting the rounding right
• write a small importer for that bank’s shape and run it against the sample

The steps never change; only the file does. So far you’ve re-narrated all five to Codex for each new bank — “okay, this one puts the date in column 3, and the amount is signed, and remember it’s cents not float…” — as if it were the first time. That re-explaining is the waste. We’ll write the procedure down once, as a Skill, and let Codex recognize “this is a new bank export to import” and run the whole thing itself.

Across the next three lessons:

• Author the Skill — the directory, the SKILL.md, the frontmatter and body — and build the bank-import procedure end to end in .agents/skills/.
• Make it fire at the right time — the description is the trigger surface; you’ll tune it so the Skill activates on a new import and stays quiet otherwise, and meet the per-Skill config that controls invocation.
• Know when a Skill is the wrong tool — Skill vs AGENTS.md rule vs a plain prompt, and which one a given job actually wants.

By the end, importing a new bank is something Codex owns. You stop narrating the column-mapping, and the cents-not-float rule stops being a thing you can forget to mention.

Start by authoring the Skill.