# Agent skills: saving a repeatable way of working Author: Rajat Published: 2026-09-23 Canonical URL: https://www.thebuildercourse.com/blog/what-is-an-agent-skill Publisher: The Builder Course The judgment behind a shopping list or a client update often goes unsaid. Make it explicit, try it out, and save the repeatable process as an agent skill. If I write ‘milk’ on a shopping list, I usually do not add a paragraph about which kind, which brand, or how much I am willing to spend. I know those things already. Someone who shops with me regularly might know them too. That short request rests on a lot of experience. We tried one brand and liked it. Another was too sweet. I will pay a little more for the familiar one, but there is a limit. When the usual one is missing, I have a way of deciding what to do next. An AI agent needs access to that knowledge before it can use it. An **agent skill** is one way to give it a reusable set of instructions for doing the work. I find it easier to understand the idea by starting with the decisions I am already making. ## ‘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. An interactive illustration with sample data and written responses. No account is connected and no AI model is running. ### Add milk to my shopping list. Fictional brands and prices in SGD. Every carton below is 1 litre. What we like: We use unsweetened oat milk at home. The instruction: Choose unsweetened oat milk. What I will spend: I am comfortable paying up to $6 for a litre. The instruction: Compare prices per litre; stay within $6/L. What has worked before: We like Oatfield. I would want to be asked before trying another brand. The instruction: Prefer Oatfield when it meets the requirements. Ask before substituting. Daily Dairy: Dairy milk; $3.20. Sweet Oat: Sweetened oat milk; $4.50. Oatfield: Unsweetened oat milk; $5.80. Plain Oat: Unsweetened oat milk; $4.90. Oat Reserve: Unsweetened oat milk; $7.20. Before sharing the knowledge: I can see the options, but I do not yet know your preferences. What kind of milk do you usually buy, what is your budget, and can I substitute? Sharing each requirement visibly rules out unsuitable options. Missing preferences prompt a question; they are not guessed. With the full procedure: Put Oatfield, 1 litre, on the list at $5.80. Plain Oat is cheaper, but you prefer the brand you already know. When the familiar choice is unavailable: Oatfield is unavailable. Plain Oat meets the type and price requirements at $4.90. Would you like to try it, or leave milk off the list? Each change starts a fresh illustration. No order is placed. 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. An interactive illustration with sample data and written responses. No account is connected and no AI model is running. ### Turn project notes into a client update Request: Draft this week’s client update. A fictional project; no message is sent. Know the reader: Our client needs progress and problems that affect them. They do not need our internal meeting log. Reusable instruction: Select outcomes and blockers that matter to the client. Leave out internal activity. Be careful with promises: We say when a date depends on something. A target date is not a commitment. Reusable instruction: Separate confirmed facts from targets. Explain what an uncertain date depends on. Make the next step clear: We end with what we need from the client and by when. If nothing is needed, we say so. Reusable instruction: End with the client’s next action and deadline, using only the supplied notes. This week: Friday is a target, dependent on photos. The event page draft is complete. → Progress the client cares about The internal team meeting lasted 45 minutes. → Internal activity; leave out Friday is the target launch date; it depends on receiving the final photos. → A target with a dependency We compared six font combinations internally. → Internal activity; leave out The client needs to send the final photos by Wednesday to keep Friday possible. → A clear request and deadline Progress: The event page draft is complete. Timing: We are aiming to launch on Friday, provided we receive the final photos by Wednesday. What we need from you: Please send the final photos by Wednesday so we can keep Friday’s launch on track. A new week: photos received and Friday confirmed by the team. The event page draft is complete. → Progress the client cares about The internal team meeting lasted 45 minutes. → Internal activity; leave out The team has confirmed Friday’s launch. → A confirmed date We compared six font combinations internally. → Internal activity; leave out The client sent the final photos. No action is needed from them this week. → No client action needed Progress: The event page draft is complete. Timing: The team has confirmed the launch for Friday. What we need from you: Thanks for sending the final photos. We do not need anything else from you this week. Each checkbox reveals what that part of the process contributes. Changing the notes keeps the process and changes the draft; it does not teach the model by itself. 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](https://agentskills.io/home) 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](https://learn.chatgpt.com/docs/build-skills), [Claude Code locations](https://code.claude.com/docs/en/skills) ### Codex project file: .agents/skills/plan-my-groceries/SKILL.md ```markdown --- 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. ``` 1. **Before choosing a skill:** the app makes the name and description available to the agent. The name identifies the skill; the description says what it does and when to use it. The --- lines enclose the metadata (frontmatter); >- lets the description span several lines. 2. **Once the skill is chosen:** the agent reads the full SKILL.md into its working context. The Markdown body explains the inputs, decisions, and expected output. This applies whether I request the skill or the agent selects it. 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. ### Codex project file: .agents/skills/draft-client-update/SKILL.md ```markdown --- 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. ``` 1. **Before choosing a skill:** the app makes the name and description available to the agent. The name identifies the skill; the description says what it does and when to use it. The --- lines enclose the metadata (frontmatter); >- lets the description span several lines. 2. **Once the skill is chosen:** the agent reads the full SKILL.md into its working context. The Markdown body explains the inputs, decisions, and expected output. This applies whether I request the skill or the agent selects 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](https://agentskills.io/home) ## 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. | How it starts | What that can look like | | --- | --- | | I name it in my request | ‘Use the plan-my-groceries skill to help with this week’s list.’ This is an explicit request in ordinary language. | | I use the app’s skill control | In Codex CLI or its IDE extension, mention `$plan-my-groceries` or use `/skills`. In Claude Code, invoke `/plan-my-groceries`. These assume that skill is installed and available. | | The agent selects it | I ask, ‘Turn these notes into a client update.’ The agent sees that the draft-client-update description fits and may load it, if automatic invocation is allowed. | 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](https://agentskills.io/home), [Codex invocation](https://learn.chatgpt.com/docs/build-skills), [Claude Code invocation](https://code.claude.com/docs/en/skills) 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. | What I supply | For the client update | | --- | --- | | Each time | This week’s notes, changed facts, and any special request. | | In the saved skill | How to select relevant details, handle uncertainty, and ask for the next action. | | My next request | ‘Use the draft-client-update skill to draft an update from these notes.’ | 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](https://code.claude.com/docs/en/skills), [Codex skills](https://learn.chatgpt.com/docs/build-skills) For rules that apply across an entire project, project instructions may be a better home. [The repo-readiness article](https://www.thebuildercourse.com/blog/repo-readiness) 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](https://developers.openai.com/plugins/build/skills), [Anthropic’s skill creator](https://github.com/anthropics/skills/tree/main/skills/skill-creator), [Claude Code setup and testing](https://code.claude.com/docs/en/skills#run-evals-with-skill-creator) 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: ### What I would ask the skill-building helper ```text 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](https://www.thebuildercourse.com/blog/what-is-an-agent-plugin). Tool details checked against linked documentation on 23 September 2026. Product conventions can change; check the source for your application. ## Read next - [Your repo is your AI’s memory. Give it a decent one.](https://www.thebuildercourse.com/blog/repo-readiness): Where skills fit alongside project instructions and context. - [I installed a plugin. What did I actually install?](https://www.thebuildercourse.com/blog/what-is-an-agent-plugin): How to share a skill and its connections as an installable package.