AI Without the Hype.
Chapter 5 of 17
Part Two · Build Your Own Tools · Chapter 05

Build a real Skill,
end to end

By the end of this chapter you can turn one recurring job you keep explaining into a working Skill that does it your way every time, and you know the few structural rules that make a Skill trigger and behave.
AVATAR OPENER · ~90s
Watch: turning a job you keep re-explaining into a Skill built by conversation
HeyGen avatar · generated, consistent presenter

Here is the signal that a Skill is waiting to be written: you find yourself explaining the same thing to Claude over and over. The way you like a weekly update structured. The exact steps you follow to prep a client call. The shape of a good invoice. Every time you re-type those instructions, you are doing by hand what a Skill would do for you automatically.

A Skill captures a repeatable job once, so it runs your way every time without you re-explaining it. You used official ones last chapter. Now you build one of your own, and the good news is you mostly build it by talking, not by coding. Claude has a skill for making skills, and it will interview you and assemble the thing. Your job is to know what you are asking for and to understand the few rules that decide whether it works.

A Skill is a job you do often, written down once, so it runs the same way every time. If you are explaining the same thing to Claude a third time, stop explaining and start building. The third time is the tell.
WHAT A SKILL IS MADE OF

A Skill is a small folder. At its heart is one file that tells Claude what the skill does, when to use it, and how to do it. Around that, optionally, sit supporting files: reference documents, templates, and scripts. You do not need to memorise a format, because the skill maker writes the file for you. But four fields at the top of that file matter enough to understand, because they are what make the skill work or fail.

The name
Short, lowercase, hyphenated. It labels the skill and matches its folder. The least interesting field, and the only one you rarely get wrong.
The description
The most important field by far. It is how Claude decides WHEN to reach for the skill. Vague description, skill never triggers. This is where the work goes.
The allowed tools
Optional. Limits what the skill can do while active. Set it to read-only and the skill can look but not change. This is your safety catch.
The model
Optional. Which model runs the skill. Pin a cheap one for a simple job, a stronger one for a job that needs real reasoning. The ladder, applied per skill.

The description is the one to get right, so it is worth saying twice. It is not a label for humans; it is the trigger for Claude. It answers two questions: what does this skill do, and when should it be used? Write it the way you actually phrase the request, with the real words you use, and the skill fires when you need it. Write it vaguely and the skill sits there, enabled and useless, because Claude never realises the moment has come to use it. When a skill will not trigger, the description is almost always the reason.

THE ONE RULE THAT KEEPS SKILLS FAST: PROGRESSIVE DISCLOSURE

There is one design idea worth understanding, because it is what separates a skill that stays sharp from one that bloats and slows everything down. A skill shares the same limited working memory as your conversation. If you stuff everything into the main file, every use of the skill drags all of it into memory, whether it is needed or not.

The fix is to keep the main file short and lean, and put the heavy material in supporting files that load only when they are actually needed. Keep the core instructions tight. Link out to a long reference document, and Claude reads it only when the job calls for it. Best of all, a script attached to a skill runs without its contents ever being loaded into memory; only its output costs anything. So the pattern is: short core, references pulled in on demand, and scripts that run rather than read.

Keep the core short
The main instructions stay lean, so they load fast every time the skill runs.
Link references
Long guides and examples live in separate files that Claude reads only when the job needs them.
Run scripts, do not read them
An attached script executes without its code entering memory. Only its output costs anything.
BUILD ONE BY TALKING

Now the actual build, and it is mostly a conversation. You start the skill maker, it interviews you the same way the grill-me move works, and it assembles the skill from your answers. Here is how to kick it off well, with a real recurring job of yours.

Start building a Skill
I want to build a Skill for a job I keep re-explaining to you. The job: [describe the recurring task in your own words, e.g. "turn my rough weekly notes into the structured update I send my team every Friday"]. Interview me before you build anything. Ask what the job is, what a good result looks like, when exactly it should trigger, and what it must never do. Then draft the skill, and pay special attention to the description, because I want it to fire on the way I actually phrase this request, which is usually: [the real words you use]. Keep the core short. If there is a long template or reference, put it in a separate file rather than stuffing it into the main one.
Try it in Claude

Answer its questions honestly, especially the one about when the skill should trigger, because that becomes the all-important description. When it is done, test it the way you will actually use it: phrase the request the way you normally would and see if the skill fires on its own. If it does not, you do not rewrite the whole thing. You fix the description, because that is nearly always the problem.

How you know it worked
You type your usual Friday line, "here are my notes, make the team update," without mentioning the skill by name. Claude reaches for your skill on its own, follows your structure, and hands back the update in exactly the shape you defined. You changed nothing about how you ask. The skill recognised the moment. That is a working description.

One more thing to know, because it saves confusion later: when several skills or rule-sets could apply, there is a fixed order of precedence. Rules set at the organisation level win over your personal ones, which win over a single project's, which win over those bundled inside a plugin. You rarely have to think about it, but when two skills seem to fight, that pecking order is usually why.

The version of this you build entirely by conversation lives in your account and is perfect for most jobs. The version built as real files on disk, which you can version, share, and check into a project, needs a terminal and a repo. That waits for the terminal and architecture chapters, and the companion repo under skills/ has a worked multi-file example to clone when you get there. For now, one working skill built by talking is the win.

NOW YOU TRY · CREATE
Build a skill for a job you keep re-explaining

Pick one job you have explained to Claude more than twice, the same way each time. Use the build prompt above. Let it interview you. Be precise about when it should trigger and word the description in your real phrasing. When it is built, test it by asking the way you normally would, without naming the skill. If it does not fire, fix the description and try again.

Right if you have a skill that fires when you ask in your natural words, without naming it, and it does the job in the shape you defined.
Show the worked solution
The drill works when the skill fires without you summoning it. Say the recurring job is "turn a call I just had into a short follow-up email with the agreed next steps." You have typed some version of that instruction a dozen times. Build it as a skill, and the make-or-break is the description. A weak one says "helps with emails," and it never triggers because that could mean anything. A strong one says something like "use when the user has just finished a call or meeting and wants a short follow-up email capturing decisions and next steps," worded to match how you actually ask. Test it by typing your natural line, "just got off with the supplier, draft the follow-up," and the skill recognises the moment and produces the email in your structure, with the next steps pulled out, without you ever mentioning the skill by name. If instead you had to say "use my follow-up skill" to make it fire, the description was too vague, and the fix is one edit to that field, not a rebuild. That is the whole craft of a skill in miniature: the doing is easy, the triggering is where the thought goes, and the trigger lives entirely in the description.
WATCH FOR
✗The skill never triggers on its own. The description is too vague. Rewrite it to say plainly what the job is and when to use it, in the words you actually type.
✗You stuff everything into the main file. That bloats every run. Keep the core short and move long references and templates into separate files that load on demand.
✗You give a simple skill your most expensive model. Pin the model to the job. A cheap one is fine for a formatting task; save the strong one for skills that actually reason.
✗You let a skill edit things when it only needs to read. Set allowed tools to read-only for anything that just inspects or reports. Give write access only when the job truly changes files.
WHAT YOU LEARNED
The takeaways
  • The signal to build a skill is explaining the same job more than twice. A skill captures it once so it runs your way every time.
  • You build most skills by conversation: the skill maker interviews you and assembles the folder. You do not need to hand-write the format.
  • The description is the field that matters most, because it is how Claude decides when to use the skill. Word it the way you actually phrase the request.
  • Progressive disclosure keeps skills fast: short core instructions, long material in linked files loaded on demand, and scripts that run without loading their code.
  • Optional fields give you control: restrict tools to read-only for safety, and pin the model to fit the job on the cost ladder.
Your project · build your first skill

Turn one job you keep re-explaining into a working skill this week, and test that it triggers on your natural phrasing. You are now a maker of tools, not just a user of them. Next chapter adds the other kind of helper you can build: subagents, focused workers you can hand a slice of a job to, and the honest traps that make most of them useless.

The third time you explain the same job to Claude, you are not prompting, you are repeating yourself. Write it down once as a skill and it becomes something the tool simply knows how to do for you. That is the moment you stop being a user and start being a builder.

← Chapter 4: The starter skills Next → Chapter 6: Subagents that help