Agent skills: saving a repeatable way of working

‘Milk’ is rarely the whole instruction.

In this example, the agent can already see the shop’s products. What it does not have is my judgment. Tick the notes I would normally leave unsaid and watch the options narrow. Then make the usual brand unavailable.

The price alone does not settle it. The cheaper brand may meet the requirements, but I prefer one I have tried. If that one is unavailable, the next step is to ask about a substitute. That decision process is the useful thing to capture.

There are two pieces here: facts such as ‘we like Oatfield’, and a procedure such as ‘check suitability and price, prefer our usual brand if it fits, then ask before substituting’. A skill can use those facts to guide the procedure. A list of preferences on its own describes less of the job.

‘Write the client update’ leaves things unsaid too.

Imagine I am working with a team on a client’s event page. I ask a colleague to turn our messy notes into a weekly update. An experienced teammate knows the client wants useful progress, not a log of every internal meeting. They also know to be careful about promising dates, and to make any request for the client clear.

A new teammate might need me to explain that approach. So might an agent. Share each part below, then change the notes to a week when the photos have arrived and the launch date is confirmed.

The new facts change the update. The way of working stays useful: choose what matters to this reader, distinguish a target from a promise, and finish with a clear next step. We use processes like this in writing, reviewing work, planning projects, and helping customers.

Write down the process you want it to follow.

We often call the knowledge we use without spelling it out tacit knowledge. I think of creating a skill as making the useful, repeatable part of that know-how explicit. The agent needs instructions it can read, examples it can refer to, and a way to handle the awkward cases.

The analogy has a limit: a saved skill does not give a model human experience or retrain it. It supplies instructions and resources for the task. I still need to check whether it follows them well.

In the Agent Skills format, those instructions live in a folder with a file called SKILL.md. The name and description help a compatible app identify when to use it. The body explains how to do the work. Supporting files can hold examples, reference material, templates, or scripts. Agent Skills format

These hypothetical skill files capture the procedures from our two examples. The braces connect each part of the file to an explanation beside it (below it on a small screen). The block between the --- lines is called frontmatter, or metadata. The >- just lets the description continue across several lines. Everything after the closing --- is the instruction body.

The paths below start at the root of a project. Codex uses .agents/skills/ for these project skill folders. Claude Code uses .claude/skills/: for example, .claude/skills/plan-my-groceries/SKILL.md. The SKILL.md filename and the simple file contents shown here stay the same. Codex locations, Claude Code locations

---
name: plan-my-groceries
description: >-
  Prepare or update my grocery list using my household preferences.
  Use when I ask for shopping-list suggestions or substitutions.
---

Use the shopping list and product information I provide.
Ask for missing quantities, prices, or availability; do not guess.

For milk, choose unsweetened oat milk.
Compare prices per litre and stay within $6/L.
Prefer Oatfield when it is available and within budget.
If it is unavailable or over budget, suggest a suitable alternative
and ask before substituting. If none fits, tell me.

Show the proposed items, quantities, prices, and reasons.
Prepare a list for review. Do not buy anything.

This small grocery skill keeps the household preferences in the same file. If the list grew, I could move those facts into a nearby reference file and tell the skill to read it. The current prices and stock still need to come from the information I supply or a working tool.

---
name: draft-client-update
description: >-
  Turn project notes into a short weekly update for a client.
  Use when I ask for a client progress update or status email.
---

Read the notes for this week. Ask if essential facts are missing.
Select progress and blockers that matter to the client.
Leave out internal meeting logs and routine activity.

Separate confirmed dates from targets.
If a target depends on something, say what it depends on.
Do not invent a promise or a missing deadline.

End with what we need from the client and by when.
If no action is needed, say so.
Keep the draft brief and show it for review. Do not send it.

Notice that Friday and Wednesday are not saved in the skill. They belong to this week’s notes. The skill saves how to reason about dates, so it can be useful next week too. A couple of approved updates could sit beside this file as examples of the tone and detail I want.

3. Supporting files are read when needed. Neither example needs an extra file. If I added references/approved-updates.md inside the client skill’s folder, I would add an instruction in SKILL.md telling the agent when to read it. Its contents would enter the working context when read, rather than every supporting file being loaded up front. Scripts can also live alongside a skill; running one is a separate action, subject to the app’s tools and permissions. How supporting resources work

How does it know when to use the skill?

First, the app needs to find the skill in a location it supports, and the skill must be enabled. A SKILL.md sitting in an arbitrary folder is not automatically available to every agent. Once it is available, there are two broad routes: I ask for it, or the agent selects it for the task.

The top metadata helps with that last route. A compatible app can show the agent a list of skill names and descriptions before loading their full instructions. When a skill is selected, it reads the rest of SKILL.md and uses any referenced files it needs. How Agent Skills load, Codex invocation, Claude Code invocation

For our client example, the path is: my request for an update → a relevant name and description → the full writing procedure → a draft using this week’s notes. The description helps choose the procedure; the body explains how to carry it out.

I would describe the job clearly instead of relying on a magic keyword. ‘Help with work’ could fit almost anything; ‘turn project notes into a client update’ is more useful. Selection can still go wrong, and apps can restrict automatic invocation. If the skill does not get picked, I can name it explicitly and check that the app found and loaded it.

I can explain it each time, or give it a home.

I can put the same procedure straight into a prompt: ‘Draft the client update. Focus on progress and blockers, distinguish targets from confirmed dates, and end with what we need from the client.’ For a one-off task, that may be all I need.

When I start a new conversation, those instructions need to be available again. I could paste them, keep a prompt template, or rely on another supported form of saved context. A skill gives the procedure a named, reusable home that a compatible agent can load when it is relevant.

The skill still becomes part of the instructions the agent works with. Saving it makes the process easier to reuse and maintain; it does not make those same words more powerful. Apps differ in how they discover and invoke skills, so I would check that mine actually loaded. Claude Code skills, Codex skills

For rules that apply across an entire project, project instructions may be a better home. The repo-readiness article explains AGENTS.md and CLAUDE.md. I would use a skill for a particular repeatable job, such as preparing this update.

I do not have to start with an empty file.

There are skill-building helpers too. Codex includes a built-in creator I can invoke with $skill-creator. For Claude Code, Anthropic offers an official skill-creator plugin that can help develop and test skills; it may need installing first. I would not assume every agent app comes with the same helper. Codex skill creator, Anthropic’s skill creator, Claude Code setup and testing

That is a meta-skill: a skill whose job is to help create or improve other skills. It can help turn a rough description into instructions and test cases. I would give it something like this:

Help me create a skill for our weekly client updates. Ask me who reads them, what we include or leave out, how we handle uncertain dates, and what a good next step looks like. I will give you an update I liked and one I had to rewrite. Draft the skill, then try it on a new week’s notes, including a case with a missing deadline.

‘Write updates well’ leaves most of my judgment unstated. Showing what I kept, what I removed, and why gives the helper something concrete to work with. It can ask questions, but it cannot know my team’s unwritten habits unless we supply them.

I need to try the skill on a fresh set of notes before relying on it. Does the draft leave out irrelevant activity? Does it preserve uncertain dates and make the next action clear? A case with missing information also shows whether it asks for what it needs.

Knowing how to work does not supply the inputs.

Our demos supply the product list and project notes. In real work, I could paste those into the conversation. To fetch current stock or read notes from another app, the agent needs an appropriate tool or connection. A skill saying ‘check availability’ does not create that access.

When preferences or team practices change, the saved instructions or reference files need updating. A correction in a conversation does not automatically update the skill.

Once a skill works, I can share its folder and supporting files with someone using a compatible app. If it also needs connections that I want to distribute with it, a plugin can package those pieces together.