What are agent skills and why do you need them?

A relatively new thing in the world of AI agents is the so-called Skills system.

Recently I started seriously developing skills. I even created a marketplace of Claude plugins for Respawn, where I keep a skill for ksrc and a skill for FlowMVI. I’m increasingly using and creating different skills, and many of you are asking: “What even is this?”. And I also see articles on the internet that incorrectly explain and incorrectly recommend creating and using skills.

So, initially skills were invented by Anthropic as part of their SDK for Claude Code. Essentially, agent skills don’t bring anything revolutionary - they’re still just folders with markdown files. The most important thing is how they work - through so-called progressive disclosure of your agent’s context. I’ve already said that the most important thing when working with agents is context engineering, and this is another way to use context more effectively.

How do skills work?

Skills are defined by one main file (SKILL.md), and it has a specific frontmatter structure. In this frontmatter there’s the skill name (what it teaches) and a description - a (very!) short description that ideally explains when to use this skill and what it can teach the model.

When your agent wrapper notices that you have such a file in your skills folder, it parses its header and includes it immediately in the agent’s context (literally as part of agents.md or claude.md). This way you get a hook for the LLM:

Use this skill when you’re writing code with FlowMVI.

Models have already become so smart that they can understand in what development context they need to read and use this skill, by one line of text. And the skills system takes advantage of this. For me it’s like casting a fishing line - the model sees the bobber on the surface, and then it can pull up a whole huge pile of documentation if needed and search through it for anything it needs.

Skill structure

The header is written in the SKILL.md file. In this file you describe your skill’s structure: what folders exist, what files exist, and the main points about usage.

For example, in my skill for FlowMVI the model is given the ability to view the documentation index, where all the nuances and details of using a specific feature are laid out (state management or creating plugins). But in the skill.md file itself, which the model reads fully if it decides to use the skill, basic things are written: “FlowMVI is an architectural framework, here’s how to quickly make a contract, here’s how to write features, here’s what DSL exists, and here’s where you can look at function signatures”.

So context disclosure happens in stages: the model first sees a super-brief two-line header, then reads the main skill.md file (a few hundred lines), and then can decide: “Aha, I understand, now I need to read the next file, for example, on creating custom plugins”. The model goes to the appropriate folder next to the skill.md file or makes internet requests, as in my case, to get fresh documentation.

This way we achieve minimal context spending on knowledge for the model, unlike, for example, MCP or AGENTS.md, which are just thrown into the model’s context as one huge chunk of text, regardless of whether they’re needed or not.

Why does your model need to know how to deploy your backend to production if it’s currently doing minor fixes after review? That’s the whole point of skills: don’t give the model everything at once to avoid cluttering the context, but gradually reveal only the needed information and let the model use its incredibly cool search capabilities and work with the command line to find specifically what it needs.

Why do you need to create skills?

You need skills to transfer specialized or fresh knowledge to the model in progressive form - knowledge that’s not yet included in the model’s training data.

You can create skills for:

What NOT to include in skills

The most important thing is what you shouldn’t create skills for: things the model likely already knows.

You don’t need to create a skill for:

Models already know this perfectly well based on millions of lines of code and all the documentation that exists on the internet. I’ve seen skills with absolutely useless content. And if the model reads such a skill, it will only work worse, because its context will be clogged with irrelevant or repetitive information that doesn’t help the model but distracts it.

Before creating a skill, think: can the model already know what I’m trying to tell it? And completely cut out everything the model already knows from your skill.

For example, with ksrc the model doesn’t need to know that ksrc is written in Go, how to use escape sequences, how to use sed syntax, how to use ripgrep, and how to make bash command chains. The model does this perfectly, and it doesn’t need to be repeated. But what the model doesn’t know is how and why to work with ksrc. So that’s exactly what I included in the skill.md file for ksrc, and nothing more.

If you need to include something the model already knows, you can just reference it in one or two words. For example, instead of describing in detail how grep search syntax works and what arguments are supported, just write: “Ripgrep arguments are fully supported” or “Add —rg-args at the end to filter results”. That will be enough.

The skill for FlowMVI works the same way. In general, models have long known what MVI frameworks are, but they specifically don’t yet know ideally the syntax of FlowMVI specifically as a framework and might not know what changed in new versions. So my skill contains not a single word about what intents and side effects are, and what should go in the MVI state. Because this is general knowledge that the internet has been covered with for years, decades, and the model knows this perfectly. Instead, the skill consists of function signatures and available configuration parameters in different DSL functions and some common mistakes that the model makes in my experience working with the library. That is, it specifically covers the model’s weak spots, spending a minimum number of tokens.

When should you create skills?

Usually this is needed when your agents.md files are growing, or when you’re releasing some framework that’s expected to be used by models too.

For example, ksrc is intended for use only by models, developers don’t need to use it. FlowMVI is used by both developers and models, so the skill is more of a nice bonus. But in any case, if a model will use this utility, it would be great if you shipped a skill that can be installed right away.

Why? The model will either not use the utility at all (simply because it doesn’t know about its existence), or won’t use it correctly (because without reading documentation it won’t know the syntax). This is a good way to reduce agents.md and reduce tokens spent on manual documentation search by models.

If you see that the model is stumbling on something - for example, writing code that doesn’t compile, or incorrectly using the new Compose API, or can’t make a Glance widget correctly - you can gather the documentation, pack it into a skill, and if you do it right, this can solve your problems with model performance when working with a specific technology.

How to create skills

Skills are repackaged documentation for some framework. So start by creating a good header and skill.md.

Most often in your code (for example, in Codex) there’s already a built-in flow for creating skills. You just use a skill for creating skills (so meta 😅). And Codex, for example, will create the whole skill with everything you need. You just tell it where to get the framework documentation, and then it will work to pack it into a skill.

One thing: after creating a skill you still need to go through all the files it created and clean them up. Or initially prompt the model to specifically describe the moments that, as you already know from practice, are pain points / difficult and complex features to use. Because by default the model will just rewrite the documentation into skill.md and might also miss many points.

For example, in FlowMVI I had to redo a lot because I wanted the model to pull the most updated documentation itself via curl, and in skill.md and in the skill folder there would be only function signatures.

Start with the template that the model will create for you in your wrapper, and then refine it.

Conclusion

My opinion is that skills are a very cool way to save context. And this feature hit the LLM development curve really well, because models have now become so easy to prompt that one line is enough for perfect execution of instructions by the model.

So you just create a skill, write one line in it “Use ksrc to search sources”, and you can count on the model already being so smart that it will understand on its own when to use this skill. This is very easy for you and saves context significantly and increases model performance.

I often hear people complaining: “My model doesn’t write compiling code” or “Can’t work with some niche libraries”, and the answer was always on the surface - as usual it’s just markdown files.