A skill description helps Codex decide when to use that skill. If an invoice skill says it handles “business, money, customers, and documents,” it could match many requests that have nothing to do with invoices.
Let's build a smaller example: a skill that creates Markdown invoice drafts from supplied billing data. It will have a clear trigger, a short set of rules, and practice data with totals we can check by hand.
This follows the skill advice in OpenAI's GPT-6 Astra guide. The example creates a local draft. It does not need a payment service, a PDF tool, or access to real customer records.
1. Define one job
The skill's job is to create or update a Markdown invoice draft.
It needs supplied billing details. It should preserve those details, calculate line totals, report missing fields, and save the result in a requested local folder.
Compare these descriptions:
description: Help with business, money, customers, and documents.
description: Create or revise Markdown invoice drafts from supplied billing data.
The second description gives Codex a useful reason to choose the skill. A request to summarize a customer meeting is outside that job.
OpenAI's skills documentation explains that Codex starts with skill names and descriptions. It reads the full SKILL.md when it selects a skill. Put the actual job near the start of the description.
2. Create the folder
For a repository skill, create this structure:
.agents/skills/invoice-draft/
SKILL.md
references/
invoice-fields.md
examples/
demo-billing.md
SKILL.md explains the workflow. The reference holds field and calculation rules. The example file provides practice input; ordinary invoice tasks do not need to read it.
The documented local skill locations include .agents/skills/ in a repository and ~/.agents/skills/ for personal skills. This tutorial uses the repository location.
3. Write SKILL.md
Save the following in .agents/skills/invoice-draft/SKILL.md:
---
name: invoice-draft
description: "Create or revise Markdown invoice drafts from supplied billing data."
---
# Prepare an invoice draft
Read references/invoice-fields.md for required fields and
calculation rules.
Use the billing source named by the user. Read files in examples/
only when the user asks for a practice run using those files.
Preserve supplied names, dates, rates, currency, and payment details.
Use decimal arithmetic or integer minor units for money calculations.
If required data is missing, list it under "Missing information"
and keep the output marked as an incomplete draft.
Save a Markdown file in the requested local output folder.
Check the saved file against the input and calculation rules.
Finish by giving the file path, the checks performed, and any
missing information. Do not send or publish the invoice.
“Integer minor units” means doing a calculation in cents for a currency such as USD. For example, USD 45.00 becomes 4,500 cents. This helps avoid small rounding errors from some number formats.
The skill names a result and its checks. It leaves Codex free to choose how to read the source and create the Markdown file.
4. Add the field rules
Save this in references/invoice-fields.md:
# Invoice draft rules
## Required input
- Invoice number.
- Issue date and due date in YYYY-MM-DD form.
- Supplier and customer names.
- Currency.
- At least one item with a description, quantity, and unit price.
- A tax amount supplied by the user, including an explicit zero.
- Payment instructions supplied by the user.
## Checks
- Dates must be valid calendar dates.
- The due date must not be earlier than the issue date.
- Each quantity must be a positive whole number for this workflow.
- Each unit price and tax amount must be zero or greater.
- Use one currency per invoice. Report mixed currencies.
- Line total = quantity multiplied by unit price.
- Subtotal = sum of line totals.
- Invoice total = subtotal plus the supplied tax amount.
- Do not guess a missing tax amount or payment instruction.
## Output
Include an invoice heading, the supplied details, an item table,
the subtotal, tax amount, total, and payment instructions.
Label every output "Draft for review".
List missing fields or invalid values under "Missing information".
Do not report a complete invoice total while a needed value is missing.
These are rules for this small practice workflow. A real business may need more fields or different calculation rules. Add those from the business's approved requirements before using the skill for real work.
The tax amount is an input here. The skill is not being asked to decide which tax rules apply.
5. Add practice data
Save this in examples/demo-billing.md:
Fictional billing data for a practice run
Invoice number: DEMO-001
Issue date: 2026-09-20
Due date: 2026-10-04
Supplier: Example Studio
Customer: Sample Company
Currency: USD
Tax amount: 0.00
Payment instructions: Practice invoice only. Do not make a payment.
| Item | Quantity | Unit price |
|---|---|---|
| Form layout review | 2 | 45.00 |
| Written feedback | 1 | 30.00 |
The expected calculations are:
- Form layout review: 2 × USD 45.00 = USD 90.00.
- Written feedback: 1 × USD 30.00 = USD 30.00.
- Subtotal: USD 120.00.
- Supplied tax amount: USD 0.00.
- Invoice total: USD 120.00.
These numbers are expected results for the example. They let you check the output without asking another model to judge it.
6. Run the skill explicitly
In Codex CLI, use the skill name in your prompt:
$invoice-draft
Use .agents/skills/invoice-draft/examples/demo-billing.md
to create output/invoice-demo-001.md.
Check the saved file and its calculations before finishing.
This is a practice run with fictional data.
OpenAI documents $ mentions and the /skills command for selecting skills in the CLI. If a new skill does not appear, check the file name and metadata, then restart Codex if needed.
Open the result. Confirm that it contains the supplied names and dates, both items, and a total of USD 120.00. The file should remain marked “Draft for review.”
Also check that the final response points to the saved file. A correct invoice shown only in the chat would not meet the request to save it.
7. Check when Codex chooses the skill
Explicit use checks whether the workflow works. You should also try requests without mentioning the skill name.
| Request | Intended match |
|---|---|
| Create a Markdown invoice from this billing file. | Use the skill. |
| Update the quantity on this invoice draft. | Use the skill. |
| Summarize notes from a customer meeting. | Do not choose it just because a customer is mentioned. |
| Build a React app for editing invoices. | Treat this as a software task; this draft-writing skill does not cover the whole job. |
Inspect what Codex selects. If the skill matches unrelated work, improve its description. If it misses a valid request, make the intended use clearer.
Then test missing information. Copy the practice data to a new file and remove the currency or tax amount. The expected output should name the missing field and remain incomplete. It should not silently fill in a value.
Keep the skill small as it grows
This skill has one output format. If you later support PDFs, add the tools and checks that PDF creation needs. Make it clear when that extra guidance should be read.
OpenAI calls this approach progressive disclosure: load detailed instructions when they apply. For example, Markdown work should not require reading a long PDF export guide.
You can also keep a very short skill in one file. The separate reference here shows how to keep reusable field rules in a named place. Create another file only when its contents have a clear purpose.
Before sharing a revised skill, run the normal example, the missing-data example, and a request that should not match. Those three checks cover different ways the skill could fail.
Video and sources
.
My video tutorial covers seven related improvements for prompts, skills, and AGENTS.md. The full website article includes the broader instruction-audit prompt.
Top comments (0)