Agent Skills Deep Dive: What They Are, What They Aren't, and How to Use Them
Agent Skills are quickly becoming a cornerstone of the AI agent ecosystem. Yet many developers still confuse them with prompts, tools, or agents themselves. This article cuts through the noise — clarifying where skills fit in the stack, how they compare to alternatives, and why they matter for both cloud and local inference.
Table of Contents
- The Problem: Why Agent Skills Exist
- What Agent Skills Actually Are
- What Agent Skills Are NOT
- The Full Comparison: Skills vs. MCP vs. Tool Use vs. Prompts vs. Subagents
- Progressive Disclosure: The Loading Strategy
- Before and After: The Skill Difference in Practice
- Why Skills Shine in Local Inference
- Wrapping Up
1. The Problem: Why Agent Skills Exist
If you've ever built an AI agent that handles more than one task, you've probably run into these headaches:
Your system prompt keeps ballooning. Every new capability adds more instructions, more examples, more edge cases. A prompt that started at 200 tokens is now 5,000. The agent gets slower, pricier, and less reliable because it's juggling everything simultaneously.
Behavior drifts between runs. Ask the same agent to review code on Monday and again on Friday, and you might get entirely different formats, depth levels, and evaluation criteria. Nothing enforces a consistent process.
Prompts are locked inside code. The instructions defining your agent's behavior are buried in C# strings, Python f-strings, or YAML configs. Non-developers can't review or improve them. Version control is clunky. Changing a single word means shipping a code release.
Knowledge doesn't transfer. You build an excellent code review workflow for Project A. Project B needs the same thing. You copy-paste the prompt, it drifts over time, and now you're maintaining two divergent copies.
These aren't edge cases — they're the daily grind of production AI development. Agent Skills were created to solve exactly these problems.
2. What Agent Skills Actually Are
Agent Skills is an open specification for defining modular, reusable AI agent capabilities as self-contained directories. Developed by Anthropic and launched in October 2025, it was published as an open standard in December 2025 for cross-platform portability.
At its core, a skill is a folder with one required file:
explain/
SKILL.md
The SKILL.md has two parts:
- YAML frontmatter — metadata (name, description, version)
- Markdown body — the actual execution instructions
Here's a complete, working skill:
---
name: explain
description: Explains any topic in plain language
metadata:
version: "1.0"
---
# Plain Language Explainer
You explain topics so anyone can understand them.
## Output Format
### <Topic>
**In one sentence:** <simple definition>
**How it works:** <2-3 sentences using an everyday analogy>
**Why it matters:** <1-2 sentences on practical significance>
**Example:** <one concrete, real-world example>
## Rules
1. No jargon. Define technical terms in parentheses if unavoidable.
2. Use analogies. Compare unfamiliar ideas to everyday things.
3. Be concise. The whole explanation fits on one screen.
4. Assume zero background knowledge.
That's a complete Agent Skill. Save it as explain/SKILL.md, point your agent at it, and the agent will follow these instructions precisely each time the skill activates.
Optional Resource Files
For more complex skills, the directory can include additional folders:
code-review/
SKILL.md # Required: instructions + metadata
scripts/ # Optional: executable code
references/ # Optional: documentation
assets/ # Optional: templates, data files
examples/ # Optional: sample inputs/outputs
Resources are lazy-loaded: the agent only reads them when actually needed, never at startup.
YAML Frontmatter Quick Reference
| Field | Required | Constraints |
|---|---|---|
name |
Yes | 1-64 chars. Lowercase, numbers, hyphens. Must match parent directory. |
description |
Yes | 1-1024 chars. What the skill does and when to trigger it. Include keywords. |
license |
No | License name or reference to a bundled license file. |
compatibility |
No | Max 500 chars. Environment requirements. |
metadata |
No | Arbitrary key-value map for version, author, tags, etc. |
allowed-tools |
No | Space-separated list of pre-approved tools. (Experimental.) |
Note: version is not a top-level spec field — place it inside metadata for maximum portability.
3. What Agent Skills Are NOT
Understanding the boundaries is just as important as understanding the concept.
Skills are not tools. A tool (MCP tool, function call, API endpoint) is a deterministic action — pass in inputs, get a structured output. A skill is a set of instructions interpreted by an LLM. Skills describe how to do something. Tools do something. As Block's Goose team put it: skills describe the workflow, while MCP provides the runner.
Skills are not prompts. A prompt is ephemeral, reactive, and embedded in code. A skill is a persistent, portable, version-controlled artifact that loads dynamically based on context.
Skills are not agents. An agent is an execution runtime with its own tools, memory, and decision loop. A skill is a knowledge module that any agent can load. Think of skills as "apps" and agents as the "operating system."
Skills are not deterministic. Because an LLM interprets the instructions, inherent non-determinism exists. If you need guaranteed structure, combine skills with structured output constraints or use tool calls for critical parts.
Skills are not a replacement for MCP. MCP provides secure connectivity to external systems. Skills provide procedural knowledge for using those systems. Different layers, same stack.
4. The Full Comparison: Skills vs. MCP vs. Tool Use vs. Prompts vs. Subagents
Skills vs. MCP
MCP is a communication protocol. It defines how an agent talks to external systems — databases, APIs, file systems, SaaS apps. Agent Skills are knowledge files. They tell the agent how to think about a task.
An MCP server connects to your database and exposes a query tool, but the agent still needs to know how to write safe, efficient SQL for your specific schema — that's what a skill provides.
| Dimension | Agent Skills | MCP |
|---|---|---|
| Layer | Knowledge / procedure | Connectivity / action |
| Format | Markdown + YAML file | JSON-RPC 2.0 protocol |
| Execution | LLM interprets instructions | Deterministic API call |
| Isolation | Shares agent context | Separate process per server |
| Latency | Zero (local file read) | Network round-trip |
| State | Stateless (text) | Stateful (running server) |
| Best for | Workflows, expertise, formats | Data access, external actions |
Skills vs. Tool Use / Function Calling
Tool use is the mechanism where an LLM invokes a structured function. Skills operate at a higher abstraction level — a single skill might orchestrate multiple tool calls as part of a workflow. Skills define the procedure; tool calls handle the actions.
Skills vs. System Prompts
A system prompt is always present, always consuming tokens, typically hardcoded. A skill loads only when needed and releases when done. The deeper difference: skills are portable artifacts living outside your code — shareable, version-controllable, swappable without touching application code.
Skills vs. Subagents
A subagent is a fully independent agent with its own model, tools, and conversation history. Skills are lighter — they augment an existing agent's behavior without creating a new execution context. Subagents are "hiring a specialist contractor"; skills are "reading the specialist's playbook yourself."
Complete Comparison Matrix
| Dimension | Agent Skills | MCP Tools | Function Calling | System Prompts | Subagents |
|---|---|---|---|---|---|
| Nature | Portable knowledge module | External connectivity | Structured action | Static instruction text | Independent execution context |
| Loading | On-demand | Always connected | Always available | Always in context | On-demand |
| Token cost | Only when active | Schema always present | Schema always present | Always present | Separate context |
| Portability | Cross-platform standard | Cross-platform standard | Provider-specific | Vendor-specific | Framework-specific |
| Best for | Workflows, expertise | Data access, APIs | Single actions | Baseline behavior | Complex autonomous work |
In production, mature agents combine all of these. System prompt for baseline behavior, skills for task-specific expertise, MCP for external data, function calling for actions, and subagents for complex orchestration.
5. Progressive Disclosure: The Loading Strategy
The key architectural innovation behind Agent Skills is progressive disclosure — a three-tier loading strategy that keeps context usage efficient.
| Tier | Trigger | What Loads | Token Cost |
|---|---|---|---|
| Discovery | At startup | YAML metadata only (name + description) | ~50 tokens/skill |
| Activation | Skill matched | Full SKILL.md body (instructions, format, rules, examples) | ~500-5,000 tokens |
| Execution | Agent needs them | Files in references/, scripts/, assets/ | ~2,000+ tokens/resource |
With 20 skills installed, that's roughly 1,000 tokens of metadata at startup. The agent knows what it can do, but carries none of the detailed instructions. When a skill activates, only that skill's instructions load. You pay for what you use.
6. Before and After: The Skill Difference in Practice
Same model, same user question — with and without a skill:
Without a skill:
The function looks okay but you might want to add some error handling. Also the variable names could be more descriptive. Overall it seems fine.
Generic, unstructured, inconsistent.
With a code-review skill:
| # | Issue | Severity | Line |
|---|---|---|---|
| 1 | Unchecked null on user.Email |
High | 12 |
| 2 | SQL injection risk | Critical | 18 |
| 3 | Magic number 86400 |
Low | 25 |
Summary: 2 issues require fixing before merge.
Same model, same weights, same temperature. The only difference: 800 tokens of skill instructions.
More Application Scenarios
| Scenario | Skill Name | Effect |
|---|---|---|
| Customer support | support-playbook |
Agent follows a triage checklist |
| Report generation | weekly-report |
Output always has the same structure |
| Compliance review | gdpr-review |
Agent checks against a specific requirement list |
| Email writing | email-writer |
Consistent format every time |
| Multi-mode assistant | Multiple skills | Same chatbot switches between modes |
7. Why Skills Shine in Local Inference
Smaller models need more guidance
Cloud models like GPT-4o or Claude can often figure out a reasonable output format on their own. A 4B or 8B parameter model doesn't have the same capacity. Skills compensate by providing the specific, structured guidance smaller models need.
Context windows are tighter. Local models typically run with 4K to 32K contexts. Progressive disclosure goes from "nice optimization" to "architectural necessity" — you can't afford to load all instructions at once.
Every token costs compute, not dollars. With local inference, extra context tokens mean more latency and memory pressure. Skills keep prompts lean for common cases.
Zero network dependency. Skills are local files. The model is local. The entire pipeline runs in-process with zero network calls. Ship the model and skills folder together.
Privacy and control. When skills run locally, instructions never leave the machine. Proprietary compliance rules, internal procedures, and sensitive domain knowledge stay in process memory.
In short: skills make large cloud models more organized. They make small local models actually capable. The smaller the model, the more it benefits from well-structured skill instructions.
8. Wrapping Up
Agent Skills occupy a distinct, irreplaceable layer in the AI agent tech stack. They're not an upgraded prompt, not a tool substitute, and not a mini-agent. They're the standardized vehicle for procedural knowledge.
Understanding where skills fit is the prerequisite for using them well. When you need an agent to follow a specific workflow, produce a specific output format, or behave with domain expertise — skills are the right choice. When you need external system connectivity, deterministic operations, or baseline behavior — reach for the corresponding other component.
The strongest production agents are never built with a single technique. They're an organic combination of system prompts, skills, MCP, tool calls, and subagents. The role skills play in that mix: standardizing "how to do it right" into something portable, maintainable, and reusable.
Frequently Asked Questions
What's the difference between Agent Skills and MCP?
MCP is a communication protocol — it solves "how does the agent connect to external systems." Agent Skills are knowledge files — they solve "how does the agent use those systems correctly." They're complementary, not competing.
Can skills and system prompts coexist?
Not only can they — they should. System prompts define baseline behavior and safety constraints. Skills provide on-demand, task-specific capabilities. Each handles its own domain.
Are skills useful for small models?
Skills deliver even more value for small models than large ones. Small models have tighter context windows and weaker reasoning abilities. Structured skill instructions significantly improve their output quality and consistency.
How do I decide between skills and tool calls?
If the task requires flexible judgment and contextual understanding — use a skill. If the task is a deterministic operation with fixed input-output relationships — use a tool call. Complex scenarios often combine both.
Which tools support the Agent Skills standard?
Currently supported tools include OpenAI Codex, GitHub Copilot, VS Code, Cursor, and the ecosystem continues to expand.