Skills are the latest buzzword in the agent world. Every platform ships them. Every framework renames them. Every post repeats the same one-liner without saying what’s actually going on under the hood.
So let’s clear things up.
In this article, I’ll walk through what a skill actually is, how it loads, what lives inside a SKILL.md file, and how it differs from a tool or an MCP server. No marketing fluff, just the mental model that makes the rest of the noise click.
From Prompts to Skills
To understand skills, you have to understand what they replace.
A prompt is a one-shot instruction. You type it, the model reacts, and the moment the conversation moves on, that instruction is gone. If you want the same behavior tomorrow, you paste it again.
A system prompt is a little better. It hangs around for the whole conversation, but it applies to everything, whether the task needs it or not. Stuff enough procedure in there and you’re paying context tokens for instructions that are irrelevant 90% of the time.
A skill goes one step further. It’s a self-contained unit of instructions the model pulls in only when the task calls for it, and ignores the rest of the time.
That’s the jump. A prompt tells the model what to do right now. A skill teaches it how to do something, and waits until that something comes up.
What Actually Is a Skill
A skill is a folder of instructions, and optionally scripts and resources, that an AI model loads on demand to perform a specialized task in a repeatable way.
The key word is repeatable. Instead of re-explaining your team’s report format, your brand’s tone, or your commit conventions every single time, you write it down once and the model applies it consistently.
And here’s the part that matters for anyone who’s ever fought with a model’s behavior: you specialize behavior without retraining anything. No fine-tune, no new weights, no pipeline. You write a file, drop it in the skills folder, and the agent now knows how to handle that task. It’s the difference between teaching a behavior and baking it in, and it makes the whole system extensible the way good software should be.
The SKILL.md File
In practice, especially in tools like Claude Code, a skill is just a folder with a SKILL.md file at its root. Think of it as the runbook the agent reads before it starts working.
A well-built skill usually contains four things:
- Name and description. This is what tells the agent when to fire the skill. Get this vague and the skill either never triggers or triggers on everything.
- Activation criteria. The concrete signals, keywords, file types, user intent, that should pull the skill into context.
- Rules and constraints. The actual procedure: formatting rules, output shape, dos and don’ts.
- Examples or templates. Concrete references that anchor the model instead of leaving it to guess.
Skills also respect priority levels, organization, user, project, plugin, so a project-specific skill can override a generic one when it makes sense. If you’ve ever layered configuration in a real app, this will feel familiar.
Example:
---
name: commit
description: >-
Write commit messages following the Conventional Commits spec.
Use when the user asks to write, review, or fix a commit message.
---
# Conventional Commits
## Instructions
Format every commit as `<type>(<scope>): <subject>`.
- **type** — one of: feat, fix, docs, refactor, test, chore
- **scope** — optional, names the area touched (e.g. auth, api)
- **subject** — imperative, lowercase, no trailing period, under 50 chars
- Add a body only when the "why" isn't obvious from the subject
## Examples
- `feat(auth): add refresh token rotation`
- `fix(api): return 404 when order id is missing`
- `docs: update README with setup steps`
How Skills Load: Progressive Disclosure
This is the mechanism that makes skills more than just saved prompts.
Models don’t load every skill they have. They use progressive disclosure: the agent scans the available skills, reads their names and descriptions, decides which ones are relevant to the current task, and only then pulls in the full instructions for those.
The flow is simple:
- You make a request.
- The agent reviews available skills and their triggers.
- It picks the ones that match.
- It loads only those instructions and applies them.
Why does this matter? Context is finite and expensive. Dumping fifty procedures into the window would blow your budget and dilute the model’s attention. Loading two of them, exactly when needed, keeps the agent fast and focused. Skills can fire automatically when the model recognizes the trigger, or you can invoke them manually.
Skill vs. Tool vs. MCP
These three get mixed up constantly, so let’s draw the lines.
A tool is a function the agent can call to act on the world, hit an API, query a database, read a file. The tool does the thing.
MCP (Model Context Protocol) is the plumbing that connects the model to external data and services. It carries information to the model and exposes tools in a standard way.
A skill is procedural knowledge. It doesn’t act and it doesn’t fetch, it tells the agent how to think about a task and what to produce.
Here’s the clean version: MCP brings the data, the tool performs the action, and the skill decides how to use both. They aren’t competitors. A skill can teach the agent how to use an MCP-exposed tool correctly. That’s the combination that actually moves work forward.
Skills in the .NET World
If you’ve written agents in .NET, none of this is new, you’ve just seen it under different names.
The concept got formalized in Semantic Kernel, which split an agent’s capabilities into plugins, functions, and skills. There, a skill groups related functions, each one doing a single, well-defined job. The Microsoft Agent Framework takes it further: skills can be composed and chained, with an orchestrator selecting and combining them to solve tasks that need different kinds of reasoning.
Whether you’re in Claude Code or wiring up an agent in C#, the underlying idea is the same: stop burying long, brittle instructions inside your application code, and start treating them as versioned, testable, reusable units. That’s just engineering discipline applied to prompts.
One more thing worth knowing for architecture decisions: the Agent Skills format is published as an open standard at agentskills.io, with a reference SDK. So the skills you write aren’t locked to a single vendor, the same format runs anywhere that adopts the spec.
When to Use a Skill
Skills are great, but they’re not the answer to everything. Reach for one when the behavior is worth standardizing.
Use a skill when:
- A task shows up repeatedly and needs to come out the same way every time.
- You’re encoding domain knowledge, brand rules, or team conventions.
- The instructions are long enough that pasting them into every prompt is painful.
- You want the procedure versioned and testable, separate from your app code.
Skip the skill when:
- It’s a one-off request. Just prompt it.
- The behavior should apply to every conversation, that’s what custom instructions are for.
- What you actually need is an action or external data, that’s a tool or an MCP connector, not a skill.
The trap is treating skills as a place to dump everything. A skill that triggers on everything is just a bloated system prompt with extra steps.
Writing Skills That Actually Work
A few hard-won notes once you start building them.
Your name and description carry the whole activation logic, so write them like trigger conditions, not marketing copy. Keep each skill focused on one job; a skill that tries to do five things will fire at the wrong time and produce mush. Lead with examples, models follow concrete references far better than abstract rules. And start small: take one task you already do every week, a weekly report, a PR checklist, a standard email, and write the procedure as if you were onboarding a new hire who’s sharp but knows nothing about your conventions.
Final Thoughts
A skill is a folder of instructions an agent loads on demand to do a specialized task the same way every time. That’s the whole idea.
What makes skills interesting isn’t the file format, it’s the shift in how we build with models. We’re moving from cramming everything into one giant prompt toward modular, reusable capabilities the agent picks up only when it needs them, the same move software made decades ago when it stopped being one big script.
If you’re building anything past simple request-and-response, you’ll end up writing skills whether you call them that or not. Knowing what they are, and where they end and tools and MCP begin, is what keeps your agent maintainable instead of a tangle of pasted prompts.
