What are AI agent skills and how to use them - complete breakdown with examples

Source: Dev.to

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?”

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 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), which has a specific front‑matter structure. In this front‑matter you provide:

• Skill name – what the skill teaches.
• Description – a (very) short description that ideally explains when to use the skill and what it can teach the model.

When your agent wrapper notices a SKILL.md file in your skills folder, it parses the header and includes it immediately in the agent’s context (literally as part of agents.md or claude.md). This gives the LLM a hook:

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

Modern models are already smart enough to understand, from a single line of text, in which development context they need to read and use the skill. The skills system takes advantage of this. For me it’s like casting a fishing line – the model sees the bobber on the surface, then pulls up a whole huge pile of documentation if needed and searches through it for anything it requires.

Skill structure

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

Example – FlowMVI skill

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, creating plugins, etc.). 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, how to write features, what DSL exists, and where to look at function signatures.”

Progressive context disclosure

1. Brief header – a super‑short two‑line description.
2. Full skill.md – a few hundred lines that the model can read if the header is relevant.
3. Additional files – the model may then decide to read a deeper file (e.g., creating custom plugins) or make internet requests to fetch fresh documentation.

This staged approach minimizes context usage, unlike dumping a massive MCP or AGENTS.md into the model’s context regardless of relevance.

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; gradually reveal only the needed information and let the model use its search capabilities and command‑line tools to find exactly what it needs.

Why do you need to create skills?

You need skills to transfer specialized or fresh knowledge to the model in a progressive form – knowledge that isn’t yet included in the model’s training data.

You can create skills for:

• Proprietary SDKs and how to work with them (store them in your repository).
• New APIs that were released only a few months ago, which the model still can’t handle.
• Niche frameworks that aren’t yet in the training data.

What NOT to include in skills

The most important guideline is what you should avoid putting into skills: things the model likely already knows.

You don’t need a skill for:

• “How to compile Kotlin code”
• “How to write SwiftUI”
• “How to work with the OpenAI API”

Models already know these topics perfectly well from millions of lines of code and abundant documentation on the internet. Including such content only clutters the context and can make the model perform worse.

Before creating a skill, ask yourself: Can the model already know what I’m trying to tell it? If the answer is yes, cut that information out of the skill.

Example – ksrc

The model doesn’t need to know that ksrc is written in Go, how to use escape sequences, sed syntax, ripgrep, or how to chain bash commands – it already handles those perfectly. What the model doesn’t know is how and why to work with ksrc. That’s exactly what I included in the skill.md file for ksrc, and nothing more.

If you must reference something the model already knows, do it in one or two words. For instance, instead of describing grep’s syntax in detail, simply write:

“Ripgrep arguments are fully supported”
“Add --rg-args at the end to filter”

When should you create skills?

Usually this is needed when your agents.md files are growing, or when you’re releasing a framework that models are expected to use.

• Example: ksrc is intended for use only by models; developers don’t need it.
• Example: FlowMVI is used by both developers and models, so the skill is a nice bonus.

Why create a skill?
If a model doesn’t know a utility exists, it won’t use it at all. If it does know about it but lacks the correct syntax, it will use it incorrectly. Supplying a skill reduces the size of agents.md and saves tokens that would otherwise be spent on manual documentation lookup.

Tip: When you notice the model stumbling—e.g., generating code that doesn’t compile, mis‑using the new Compose API, or failing to build a Glance widget—gather the relevant documentation, pack it into a skill, and you’ll often see a noticeable boost in model performance for that technology.

How to create skills

Skills are repackaged snippets of framework documentation. Follow these steps:

1. Create a header and skill.md.
2. Use your existing tooling (e.g., Codex) to generate a skeleton skill.
   • Tell the tool where to fetch the framework docs.
   • It will produce a skill folder with a skill.md containing the raw material.
3. Refine the output.
   • The generated files will usually contain only function signatures or a verbatim copy of the docs.
   • Manually edit them to highlight pain points, common pitfalls, and the most‑used configuration parameters.
   • Add concise explanations and examples where the model typically struggles.

Important: After the skill is generated, always review and clean up the files. By default the model may miss nuanced details that are crucial for correct usage.

Example (FlowMVI)

The initial output contained only function signatures pulled via curl. I edited the skill to include:

• Key DSL functions and their parameters.
• Typical mistakes (e.g., forgetting to handle side‑effects).
• Minimal, token‑efficient explanations of intents, side‑effects, and state composition.

Start with the template the model creates, then iterate until the skill is both compact and comprehensive.

Conclusion

Skills are a powerful way to save context and improve model performance. Because modern LLMs can follow concise instructions, a single line like:

Use ksrc to search sources

is enough for the model to know when to invoke the skill. This dramatically reduces token usage and leads to more reliable, compile‑ready code.

Common complaints such as “my model doesn’t write compiling code” or “it can’t work with niche libraries” often boil down to missing or poorly organized markdown documentation. Providing well‑crafted skills solves those issues.