When you work with an agent, some instructions come up repeatedly. You might have a way to discuss a feature, review code, or prepare a release. A skill keeps that procedure available when you need it. We will write one, look at how it loads, and see how using it helps us improve the instructions. The important question is whether the skill makes the work better.
Suppose you want to discuss a feature before the agent implements it. You want the agent to read the relevant project context, raise unresolved decisions, and record what you agree to build. You can explain that procedure in each conversation. Once you find a way of working that you want to repeat, it is useful to keep those instructions in a file.
A skill packages reusable instructions that the agent loads when needed. You can invoke it by name, and the agent can also select it when its description fits the task. Loading the file adds instructions to the model's context. It does not change the model's trained weights. We will come back to improving the procedure once we have used it.
In Claude Code, put a project skill in a folder under dot claude slash skills. Our folder is called spec-discussion, and it contains SKILL.md. Commit these files to share the procedure with people working on the repository. For a personal skill available across your local projects, use the skills directory under dot claude in your home directory. Plugins can package skills too.
The file begins with YAML front matter between two lines of three dashes. Put the opening delimiter on the first line. Give the skill a name matching its folder and a description of its purpose and when to use it. The body is ordinary Markdown containing the procedure. This folder-and-file structure follows the Agent Skills standard, though installation paths and additional settings differ between tools.
The description helps the agent decide whether to load the instructions. Say what the skill does and identify the situation where it helps. For this example, the useful condition is a feature with important unresolved design decisions. The mere absence of a spec is not a reason to interrupt every small change with an interview.
This description includes an explicit design discussion and a feature whose behavior, scope, or integration still needs thought. It also excludes routine changes with clear requirements. An existing spec can still need discussion when the feature changes. These boundaries help the agent choose the procedure for the work where it is useful.
Below the front matter comes the body, and the body is the procedure itself. It is ordinary Markdown, written as instructions to the agent, in the order you want them carried out. This example begins with what to read and what to ask, and goes on to say what to write and when to stop. Each step says what to do, in plain sentences, and a rule you care about goes in as a rule, because the agent follows the text literally. The steps themselves are one way to run a design discussion. What matters for writing a skill is the shape: what to read, what to ask, what to write, and when to stop.
Invoke the skill by typing slash spec-discussion followed by your request. Check that its instructions load. If Claude Code cannot find it, check the folder, the filename, and where you started the session. This direct invocation gives you a straightforward way to try the procedure without first depending on automatic selection.
The agent continues the discussion with you, works through decisions, and updates the draft. As you work, review both the proposed feature and the procedure itself. Are the questions useful? Is the agent using answers you already gave? Is the written result faithful to the agreement? You will learn more about the skill from that work than from seeing that its name appeared in the interface.
Start with a useful first version and try it on actual work. Review what the agent does, identify what helped and what got in the way, and revise the instructions. Writing a skill is an iterative process. Your first description of the procedure will often leave out a decision or include a step that turns out to be unnecessary.
Judge the skill by what it contributes. Does it catch decisions you would otherwise miss? Does it save you from repeating the same correction? Does it produce something easier to review? A skill that adds questions and ceremony without improving the work needs changing or removing. Having more skills is not itself progress.
Compare the same request in two fresh sessions, with and without the skill. Without it, the agent set out to initialize the project and reached an approval prompt. With it, invoked by name, the agent read the empty project first, found no settled decisions, and asked a design question about storage before anything else. This shows a concrete change in how the work begins. Look for important decisions that the discussion brings forward before implementation.
The discussion continues from there. As you work, compare how much explanation and correction you need to provide with similar tasks where you did not use the skill. A longer conversation is worthwhile when it resolves useful questions. Repeated or irrelevant questions are a reason to change the procedure.
Review the resulting spec as well. Check whether it captures the intended behavior, fits the existing project, and preserves the reasons for important decisions. The opening comparison shows that the skill changed the first action. Whether the whole procedure helps is something you judge from the work and its result.
The agent can also select the skill from its description. Briefly check this with a request where it should help and one where it should stay out of the way. Use your normal working setup, because other instructions affect that choice. If it is selected too often or missed when relevant, revise the description.
You can always request this skill directly when you want its procedure. Automatic selection is a convenience, and checking it is separate from judging the quality of the work. Once the skill loads, return your attention to whether following it is useful.
Two front-matter settings control these paths in Claude Code. Disable-model-invocation set to true prevents automatic invocation, so you start the procedure yourself. User-invocable set to false disables the user slash command while leaving the skill available to the model. Hiding a command is not an access-control boundary.
This is also context management in action. For skills available to automatic selection, the agent starts with a listing of names and descriptions, rather than every full procedure. That small amount of information helps it choose what to load. Providing a summary first and details when needed is called progressive disclosure.
When a skill is invoked, its body enters the conversation context. The other skill bodies remain outside the window until they are needed. You can therefore keep a collection of detailed procedures available without loading all of them into every session. Loaded instructions occupy context and can continue to influence later turns.
Supporting material can load dynamically too. If the skill links to a longer reference, the agent reads that file when the procedure calls for it. This leaves more room for the current task than placing every procedure and reference in an always-loaded instruction file. Keep descriptions concise as well, since the listing itself takes space.
Keep the body focused on the steps, decisions, and checks particular to the procedure. Put long explanations in supporting files, link to them, and say when to read them. Shortness is useful because it makes the important instructions easier to find. Keep the detail the agent needs to do the work correctly.
Put a repeatable computation or mechanical check in a script and tell the agent how to run it. The skill explains the procedure, while tools execute the operations, including running that script. You do not need the model to reconstruct a fixed sequence of commands every time.
Keep standing project rules in the project's instruction file, such as CLAUDE.md, and task-specific procedures in skills. These mechanisms work together. The instruction file supplies rules that apply across the work, the skill supplies the relevant procedure, and tools carry out its operations.
The course's build-decks skill is an example. It describes to an agent how to work on slides and narration for the course videos. It points to detailed references, and explains how to build and check the result. The main procedure and the supporting material have different jobs. You can use the same structure for a workflow in your own project.
We started with instructions that came up again and again, explained afresh in every conversation. Now they live in one file, the agent loads them by name or when the description fits, and each use shows you what to fix in the instructions. Choose one procedure you repeat, write it down, and improve it as you work. The question to keep asking is whether the skill makes the work better.