Claude Code Skills, Explained Simply.

Video authored by the channel shown, not by IANIA; all rights belong to the creator. Transcript and summary generated automatically; the original-language content is preserved.

Original language: English

Original video: Claude Code Skills, Explained Simply. · Channel: Agentic Lab · 15:21 · Watch on YouTube

Topics: AI agents, Task and workflow automation, Claude Code, Prompt and context engineering, Software engineering with AI

Summary

Claude Code skills are markdown-based instructions that can be invoked by a user command or loaded by the model when needed. Their real value comes from packaging team- or user-specific knowledge, scripts, hooks, and supporting files—not merely storing prompts. The speaker recommends making skills as deterministic as possible by moving mechanical tasks into scripts and using the agent to connect steps that require judgment. He also demonstrates a skill-auditing workflow and recommends keeping model invocation off by default and skill files short.

Key points

A skill is a folder-based unit whose markdown instructions can be loaded through user invocation or model invocation.
Model invocation uses an always-loaded description to let the model decide when to load the skill body; this progressive disclosure can add distraction when many skills are enabled.
Skills are most useful when they encode knowledge specific to a person, team, client, or codebase.
Bundled scripts and files can make skills portable across teammates’ machines.
Scripts are deterministic, while agent behavior is probabilistic; use scripts for mechanical tasks and the agent as glue between them.
Skill front matter can configure hooks, tool permissions, context forking, model and effort settings, and model invocation.
The exclamation mark can run bash commands at skill load time, while the at symbol can inject files into the skill.
Hooks registered by a skill remain active for the rest of the session, so their effects should be considered carefully.
The auditing example checks front matter, descriptions, size, script and file paths, permissions, and other potential issues.
The speaker’s defaults are to disable model invocation unless it is genuinely needed and to keep skill files short.

Chapters

Start	Chapter	Summary
00:00	What a skill is and how it loads	The speaker defines skills as markdown instructions and explains user invocation, model invocation, and progressive disclosure.
02:05	Where skills get their value	Skills are valuable for encoding local knowledge and can bundle scripts and files for portable team workflows.
03:43	Making skills more deterministic	The speaker recommends putting tasks that can be scripted into scripts and using the agent to decide what comes next.
04:13	Hooks, tools, and dynamic skill inputs	The video covers skill-specific hooks, tool restrictions, load-time bash execution, file injection, and arguments.
06:51	Skill auditing example and configuration	The speaker introduces an auditing skill and explains its invocation settings, context forking, model choice, and tool restrictions.
09:01	Deterministic checks and LLM review	The audit script checks skill structure, size, paths, and other mechanical issues before asking the agent to assess instructions and bloat.
14:17	Recommendations for building skills	The speaker emphasizes separating scriptable checks from model judgment, keeping skills short, and auditing existing skills.

Quotes

It’s a markdown file that gets pasted into context — 00:00

This is what we call progressive disclosure. — 01:34

The agent is treated like glue in between scripts. — 04:13

Could this instead be a script? Could this be a hook? — 14:48

Concepts and entities

Claude Code, skill, progressive disclosure, hook, script, context fork, skill audit, Roman, Matt Pocock, Anthropic, Opus, NeurIPS

Full transcript (original language)

00:00 Since their inception, skills have been everyone’s favorite feature in Claude Code, and everybody talks about them like some kind of magic trick. But a skill is the simplest part of Claude Code, bar none. It’s a markdown file that gets pasted into context, and that’s exactly why almost everyone under uses them. They stop at the first thing a skill can do, which is store a prompt, and they never touch the levers that turn it into something more versatile. In this video, I’ll define exactly what a skill is from first principles, show you the architecture underneath, and how to build effective skills. By the end,

00:33 you’ll be able to understand and create cheaper, faster, and more consistent skills that do any knowledge work of your choosing. I’m Roman. I published a top 3% paper at NeurIPS, the largest AI conference in the world. Now, I’m on a mission to push coding agents to their absolute limits. So, let’s start by reiterating what a skill is. A skill is a markdown file that the user or agent can paste into the agent’s context. Skills are triggered in two fashions: model invocation and user invocation.

01:03 The simplest way to use skills is with user invocation. So, imagine that you wanted to save a prompt and inject it into an LLM whenever you type a certain command, such as {slash} analyze. And as soon as you type that, it pastes the stored prompt directly into your Claude Code’s context window, alongside any prompt additions you made after the {slash} command. Okay, so very simple. So, then we have model invocation, which is the second type. So, imagine that we want the model to decide whenever it

01:34 should load a skill into its own context. Well, the model has to know that it can even do that, that that’s even a possibility. So, at the very start of every session, we paste a little headline about what the skill is and when to actually call upon it to get injected. We tell that to the LLM so it can then choose to do it. So, this headline is always loaded into context, and the body only loads when the model actually reaches for it. This is what we call progressive disclosure. But this is a double-edged sword because

02:05 the more model invocable skills that you stack in your setup, the more distracting these always-on headlines become. That’s why in most of my skills, I disable model invocation so that it doesn’t load the headline into context at all. And there it is. Skills are quite literally as simple as that. You store a prompt in a markdown file, and either you inject it by a slash command, or you hint at its existence and let the model decide when to inject it into itself. And if it’s that simple, then the mechanism isn’t where the value is. The value is what you put in the skill

02:37 itself. Skills shine when they carry knowledge that only exists in your head or on your team. How your codebase deploys, what your client needs, the way you personally like to work. And nobody’s one-size-fits-all skill off GitHub has that. So the whole game is knowing how to build your own skills for yourself and your team. A little bit of nuance about what a skill actually is. A skill isn’t actually necessarily just one file. It’s a folder, and that folder is the whole unit you share. So you can drop scripts next to the markdown, reference them with the skill through a

03:09 variable, and Claude code swaps it for the folder’s real location before the model reads the line. And this allows us to port and reference scripts regardless of whose machine the skill is running on. That’s what makes these so powerful for internal teams. Because without that, sharing a skill would mean sharing a folder plus a paragraph of setup instructions, and every script call would be a pop-up. With it, you commit the folder to the repo’s .cloud/skills, and every teammate has the whole workflow on clone. Now, really quick, I want to talk about determinism. At their core, skills are probabilistic,

03:43 meaning there is no guarantee that they work since they’re based on relying on an agent to do the right behaviors. This is problematic because they are more expensive, less reliable, and they take longer. On the other hand, scripts are fully deterministic. The solution to skills being probabilistic is that we can make them as deterministic as possible by incorporating scripts any place that they can be, or any place that they fit within a skill. So, one rule to consider when making or looking at skills,

04:13 is there functionality in this skill that can be done fully deterministically in a script, or is there not? And here’s how I actually use a skill. Anything that can be scripted will be a script, and the markdown will teach the agent to run them and decide what comes next. The agent is treated like glue in between scripts. Now, that’s the core of skills. Past that, there are a couple of front matter levers most people genuinely never touch, and some are actually quite great. First up, you can put hooks inside of a skill, and they only register in sessions where that skill ran. For example, a skill called {slash}

04:47 grill me record, you would take Matt Pocock’s original grill me skill, where the model asks you questions about your specifications until it’s satisfied, and you install a user prompt submit hook. So, every time you prompt the agent, a script fires. Then, before any code execution occurs, that hook would use a regex to record every question the model asked, and every response the user gave, adding it deterministically and instantly to documentation in the code base called grill responses.md.

05:18 So, this would solve the pain point of a lot of people having their questions and the answers lost in the session of an agent, and it can be solved with this simple pattern of putting a hook inside of a skill. Now, one thing to note, once a skill registers a hook, it stays on for the rest of the session, not just that skill’s task. Now, you can also allow or disallow tools for the agent’s first turn when a skill is active. This serves as a safety precaution when you want to enforce behavior. For example, you can disallow edit write inside of a

05:49 skill where the agent’s only job is to do read-only analysis. So, this guarantees that the agent will be well-behaved. Next up, in Claude code, the exclamation mark symbol turns the command into bash execution. And this works in skills, too. Meaning that you can run scripts at load time in a skill. The model never receives the command you typed. It instead receives the output of that command deterministically injected. This allows you to make a lot more dynamic logic inside of skills for a lot cheaper. And it enforces determinism

06:20 inside of your skills. And another tip is that the at symbol injects any file of your choosing into your skill. This is powerful because it allows you to change what gets put into the model without changing the skill every time something changes. For example, if you run a {slash} analyze codebase skill, you can inject your codebase user story by adding at doc {slash} user story.md. And as that user story changes, you don’t have to change the skill. Number three is that you can add in arguments to skills that

06:51 allow a user to inject variables into certain scripts or context into the model. Another pro tip is when using a skill, you can actually also prompt on top of it and it will just inject your prompt into the agent after the skill. Okay, so what does a skill actually look like in terms of the skill itself? So, let’s start with a skill audit skill that I created that’s kind of a meta example here of a skill that I created that follows all of the good conventions of skills and can teach you a thing or two. And then you can download it as well and have it better serve your skill building

07:25 process. You can audit your skills. So, the first thing I’d like to highlight is that disable model invocation is on. This once again means that the front matter of this skill, which is this description, will not go into the model’s context at all times. If you have have set to false, then it will. Next little tip is that I made the context forked here. So, as soon as you run this skill, it will actually fork the exact context of your agent, put the skill in there, and have it run in a forked sub-agent, and then merge back into the main agent. This can be a very powerful pattern for

07:58 context efficiency where you don’t actually need the skill running in the main context of your agent. You just need the output of the skill. In this case, we’re leaving it in the foreground, which just means that we won’t have our normal session while the skill is running. If you wanted to set background to true, this would mean that the forked agent would run in the background while you continue your session. In this case, we’re fine waiting. You can also assign a model to your skills. So, the second I run this skill, it will fork context, change the model to Opus, change the effort to

08:30 medium, and keep it in the foreground. Now, you can also see I’ve disallowed as many tools as possible so that we make it fully deterministic because this is a read-only skill. We don’t want it actually changing our skill, so we enforce that guaranteed. Now, let’s move on to the skill itself. So, the first thing to note here is that we have the exclamation point pattern for running bash scripts within the skill itself before it even goes to the agent. So, the first thing the skill is going to do is it’s going to run the skill enter

09:01 bash script on the skill of your choosing, which by the way, the skill of your choosing is chosen by the user under target, so they can add it as an argument. Then it will run this on that skill. And real quick, what is skill enter? Well, skill enter is a bunch of logic that first finds the skill from a path or a name in an argument. Then it’s going to see if no argument was given, usage will be printed instead into the context. Then it’s going to see if the verbatim skill that the user provided is

09:32 actually a skill in your .cloud/skills or plugins, and it has to pick exactly one. So, once the script finds it, every check below runs against this folder. So, let’s go through the deterministic checks. First, it’s going to read the front matter and check each key. If there’s no front matter, that means that the skill will load with no description. Cuz in front matter, we have to have three dashes as the first part of a skill. Basically, this is a way to guarantee that the skill is actually written correctly. You can see up here

10:02 that my description, the first line, is those three dashes. And this may be up for changes if Anthropic decides to change what they’re doing. So, if there’s a key Cloud Code does not know, it’s going to be silently ignored. So, we’re going to note that to our agent in the linter note. If there’s no description, we’re going to flag that to the model and let it know as well. And another thing to consider here is that if the description and the when to use is over 1,536 characters, then it will get truncated when given to the model, which can be

10:34 confusing. So, in our auditing of skills, we want to deterministically make sure that it’s under 1,536 so that it isn’t truncating without our knowledge. Now, this is another very important one. For me and my skills, I like to by default have disable model invocation true. This is to protect the attention of our models. So, if disable model invocation is false, we want it flagged to our agent during the skill audit so we can make the decision. So, up next would be cases where we take arguments in, but we don’t give the user

11:08 any hints on these arguments. All right, and other things that are important for you and your model to know about are that hooks from a skill stay armed for the whole session. So, sometimes that can cause danger. Also, if we switch model, it will break the prompt cache for that turn, causing an extra expensive skill load. And actually, same for effort. Up next in the linter is the size of a skill. So, in some cases, skills that are over 500 lines can be very dangerous. The reason is that you’re injecting a lot of

11:39 context into your agents. You can make this flag a thousand. Under 500 is what Anthropic officially recommends. Another thing to note is that if it’s over 5,000 tokens total for the skill, the first 5,000 tokens will survive auto compaction, but the rest will silently drop. These are very important to at least know about. Now, other things, we’re going to deterministically check every script path and bundled file. So, if it’s referenced by a bare name, it may break on another machine. So, that’s very important to look into. Same thing

12:11 with a relative script path, it’s going to break on another machine. Or if the bundled files do not actually exist. Uh another thing to flag is that if the model is running scripts in a skill, but nothing is pre-approving them, then permission pop-ups are going to occur every time, making the skill borderline unusable. One thing I like to flag is too many absolute rules within a skill. So, if it’s greater than 15, for example, we may want to flag this to our agent. Rule stacking is very, very dangerous when working with agents

12:42 because they cannot adhere to every rule very well. And then next in the script, it’s just going to print this out to our agent. So, back into the agent, first it’s going to get that printout. And now it gets this prompt. So, the prompt is basically looking at everything the linter did, looking at the skill itself, and tracing certain behaviors that couldn’t deterministically be detected. So, the skill’s going to ask, “What is the skill for in one sentence?” Then we’re going to ask the agent to look for pros that should be a script. And note that all of these things I’m about to mention are

13:13 things that only an LLM could detect that we couldn’t put in a script. So, another is do nots that should be enforced. So, somewhere where we could install a hook instead of a do not rule. Another is asking an agent to create a script instead of fill in a template. This can be very cost and time inefficient. We also may want to ask to reduce bloat. Should this be run under context forked or stop forking if that’s incorrect? There can also be contradictions or unclear instructions within skills, so we’re going to ask our

13:43 agent to look into that. And bloat. So a lot of times when agents write skills, they bloat it with a ton of rules, a ton of instructions, a very dense line. So we just want to see if we can make it a little less bloated. And then so it gives a verdict based on all of this. Then down here it’s going to inject the template for the model’s response so that it can see it properly. I believe you could also use the at symbol here. It actually doesn’t really matter. And so this is the little template in case of you’re interested. This is the shape that every skill should end up. Then finally, we have the template that

14:17 the model’s going to fill in and we’re going to inject it into there. So the template looks like this if you’re interested. We’re just going to move very fast through this. And there you have it. There’s my skill for auditing skills. So hopefully you learn how to build good effective skills by looking into the skill. It will also be available in my free school community linked down below where you can audit your own skills using this and you can also look into how I built this skill. Now, if you look into what I actually gave it there cuz this is actually the whole skill. I told it what to flag,

14:48 which of those checks are mechanical and belong in a script, and this split is actually the biggest thing in skills is where you can make things as deterministic and guaranteed as possible. For example, counting lines and grepping a path is actually not a job for a language model. You should just install that into a script and have it run instantly. And once again, my two defaults, my non-negotiables are model invocation off unless I genuinely want Claude to reach for it on its own, and keep the files short. So here’s what to do today. Go into my free school community linked below and

15:21 get the skill auditing skill and run it on every skill you have. Also, what you can do is read every line and ask two questions. Could this instead be a script? Could this be a hook? So, go find the skill linked below. It’s an amazing community, and there’s tons of value in there for free as well.