Early AI coding assistants wrote code without context. They didn’t know your conventions, patterns, or domain knowledge, so you repeated the same explanations every session, and the agent forgot them by the next.

Agent Skills address this by packaging procedural knowledge, instructions, and resources into reusable folders that agents discover and load. You write your conventions into a skill once, and any compatible agent can use it.

This article explains why Agent Skills exist, how they work, and which problems they solve for authors, developers, and users.

Why Agent Skills Exist

AI agents keep getting more capable but still lack the context for reliable work. A general coding assistant might know Python syntax but not your review process, web development but not your design system, or SQL but not your database schema.

The problem affects three groups: skill authors who share knowledge, agent developers who extend capabilities, and end users who need agents that understand their context.

The Context Problem

Agents need two kinds of knowledge: declarative (facts) and procedural (how to do things). Training supplies facts, but procedural knowledge is often missing or outdated.

Consider a legal review process. An agent might understand what a contract is (declarative) but not how your organization reviews contracts (procedural). It might know React but not your team’s component patterns, or data analysis but not your pipeline.

Without procedural knowledge, agents make generic choices. They write code that works but ignores your conventions, and technically correct solutions that miss your domain’s requirements.

For example, an agent might generate React class components when your team uses hooks, create API endpoints without your authentication patterns, or write SQL queries that ignore your database conventions. These solutions work but don’t fit your context.

Agent Skills package procedural knowledge into reusable, discoverable folders. Instead of training new models or rewriting custom instructions, you create a skill once for any compatible agent to load. A React skill enforces your hooks patterns, an API skill applies your authentication rules, and a database skill follows your naming conventions.

The Reusability Problem

Before Agent Skills, you shared knowledge with agents in one of three ways:

  • Custom instructions per conversation. You paste the same instructions into every chat, which wastes time and invites inconsistency.
  • Fine-tuning models. You retrain models yourself, which is expensive and slow and locks you into one model provider.
  • Hardcoded capabilities. Agent developers build capabilities into their products, so users can’t extend them and developers maintain everything.

None of these approaches scale. Custom instructions don’t persist, fine-tuning is costly and inflexible, and hardcoded capabilities limit users and developers.

Agent Skills offer a fourth option: package knowledge once and use it anywhere. Skills are version-controlled, shareable, and portable across compatible agents. Build a skill for your team’s React patterns, and it works in Cursor, Claude Code, and any other skills-compatible agent.

The Interoperability Problem

Without a standard, each agent product needs its own integration, so teams duplicate knowledge and agent developers support multiple formats.

Anthropic created Agent Skills, and multiple agent products now support the format, so a skill works the same way in every compatible agent and teams write it once. The standard complements protocols such as the Agent2Agent Protocol (A2A), which lets agents communicate across vendors and platforms.

Think of a skill as a reusable npm module: write it once, and any compatible agent can load it, the way any Node.js app imports the same module.

How Agent Skills Work

Agent Skills rely on discovery and on-demand loading. Instead of carrying all knowledge in their training data, agents find skills when needed, load the relevant instructions and resources, and apply them to the current task.

The format is simple: a folder with a SKILL.md file that describes the skill’s purpose and usage, plus supporting resources. That simplicity makes skills easy to create, share, and maintain.

The Skill Structure

A skill packages knowledge in three layers:

Core instructions: The SKILL.md file describes what the skill does, when agents should use it, and how to apply its knowledge. Agents parse this structured file to learn the skill’s purpose and usage.

Supporting resources: Scripts, templates, examples, configuration files, and other materials the skill references. They give agents concrete patterns and domain knowledge to draw on.

Metadata: YAML front matter at the top of SKILL.md. The name and description fields are required, and the description is what agents match tasks against. Optional fields cover license, compatibility, and allowed tools.

A minimal skill is one file:

---
name: "code-review"
description: "Reviews pull requests against the team's conventions. Use when the user asks for a code review or shares a diff."
---

## Review checklist

1. Flag any new function that lacks a test.
2. Reject React class components; the team uses hooks.
3. Run `scripts/lint-sql.sh` on changed `.sql` files and report its output.

The front matter is all the agent reads until a task matches. The body loads only when the agent activates the skill.

When a task matches a skill’s purpose, the agent loads the skill’s instructions and resources and applies them. The agent needs no prior knowledge of the skill; it learns the skill on demand.

The Discovery Mechanism

You find skills in catalogs such as the Agent Skills Directory, in GitHub repositories, or in your organization’s private repositories, then install them into a directory your agent reads. The agent never searches a registry mid-task; it works from the skills already installed.

Discovery uses progressive disclosure. At startup, the agent reads only each installed skill’s name and description. When a task matches a description, the agent loads that skill’s full SKILL.md, and it opens bundled scripts or references only when those instructions call for them. A few dozen words per skill keep hundreds of installed skills cheap to carry.

Think of it like a library shelf. You don’t read every book to answer a question. You scan the spines (descriptions), pull the one book that matches (the full SKILL.md), and turn to its appendix (scripts and references) only when a chapter points there.

The Application Process

When an agent applies a skill, it evaluates the context, matches skills to the task, loads the relevant knowledge, and applies it. It chooses skills based on what you’re trying to accomplish, not because you named one.

If you’re working on a React component with a React best practices skill installed, the agent recognizes the context, loads the patterns, and applies them as it codes or reviews. With a presentation skill installed, it follows those guidelines when it generates slides. You don’t need to name a skill; the agent finds the right one from your work.

Key Relationships

Agent Skills connect to several related concepts in AI agent development:

Agent Skills vs. Custom Instructions

Custom instructions are temporary, conversation-specific text you give an agent. Agent Skills persist, and you reuse them across conversations and agents.

Custom instructions solve immediate problems but don’t scale. Think of custom instructions as sticky notes and Agent Skills as a documentation library.

Agent Skills vs. Fine-tuning

Fine-tuning retrains a model with new data, which is costly, slow, and provider-specific. Agent Skills add capabilities without retraining, work across providers, and take effect the moment you edit them.

Fine-tuning changes the model itself. Agent Skills change what the model knows how to do and leave the model untouched. Fine-tuning is like rewiring a person’s memory to teach new facts; Agent Skills are like handing that person a reference book.

Agent Skills and Model Context Protocol

Model Context Protocol (MCP) standardizes how agents connect to external tools and data sources. Agent Skills standardize how agents access procedural knowledge and instructions.

MCP manages “how to connect” (tools, resources, prompts), while Agent Skills focus on “what to know” (procedures, patterns, conventions). They complement each other: MCP provides system access, and Agent Skills supply the knowledge to use that access well.

Some skills use MCP servers to reach resources. A database design skill, for example, could query your schema through an MCP server and suggest improvements based on design patterns.

Agent Skills also work alongside the Agent2Agent Protocol (A2A), which lets agents communicate and coordinate. A2A handles agent-to-agent communication; Agent Skills supply the procedural knowledge each agent needs for its tasks. This division mirrors how API design separates interface contracts from implementation details.

The Agent Ecosystem Architecture

The following diagram shows how LLMs, MCP Servers, Agent Tools, and Agent Skills fit together:

graph TB LLM["LLMs"] Tool["Agent Tools"] MCP["MCP Servers"] subgraph "Agent Skills" Skill1["React Patterns
Skill"] Skill2["Code Review
Skill"] Skill3["Other Skills"] end LLM --> Tool Tool --> MCP Tool --> Skill1 Tool --> Skill2 Tool --> Skill3 Skill1 -.->|"may use"| MCP Skill2 -.->|"may use"| MCP Skill3 -.->|"may use"| MCP

This architecture shows:

  • LLMs provide core language understanding and generation. Tools may share an LLM or use different ones.
  • Agent Tools (Claude, Cursor, GitHub Copilot) are user interfaces that use LLMs to provide AI assistance.
  • MCP Servers connect agents to external systems such as databases, file systems, and APIs.
  • Agent Skills supply procedural knowledge and patterns that agents discover and apply to tasks, complementing MCP servers.

The relationships are flexible: a tool can use multiple LLMs, connect to several MCP servers, and load different skills as needed. Skills can also call MCP servers to reach external resources.

Agent Skills and Plugin Systems

Many applications use plugins to extend functionality, but Agent Skills carry knowledge rather than code. Plugins require code installation and version management, while agents read skills as folders of instructions.

Plugins add features and tools, while Agent Skills add procedures and patterns. Plugins run as code inside the host application. Agent Skills are mostly instructions, and their bundled scripts run only when the agent chooses to use them.

Agent Skills and the Agent Plugins Specification

Skills often depend on other components. A code review skill might need an MCP server that reads pull requests, and a database design skill might need one that queries the schema. Each agent product built its own plugin layout to bundle these pieces, so authors rearranged or duplicated the same files for every client.

The Agent Plugins Specification is an open, vendor-neutral standard for packaging skills and MCP servers into one portable plugin. Unlike the application plugins above, an agent plugin mostly bundles skills and server definitions rather than adding executable features. The project develops version 1.0.0 in public, and its initial Technical Steering Committee includes maintainers from Amazon, Cursor, Microsoft, OpenAI, and Vercel.

A plugin is a directory with one required manifest and components in fixed locations:

code-review-plugin/
├── plugin.json            # required manifest
├── skills/
│   └── code-review/
│       ├── SKILL.md       # unchanged Agent Skills format
│       ├── scripts/
│       └── references/
├── mcp.json               # MCP server definitions
└── com.example.client/    # one client's extensions, such as hooks
  • plugin.json names the plugin and declares the spec version it targets through a $schema URL. Optional fields cover version, description, author, license, and keywords.
  • skills/ holds skills in the Agent Skills format. The plugin spec builds on the Agent Skills specification instead of redefining it, so an existing skill drops in unchanged.
  • mcp.json declares MCP servers that use stdio, Streamable HTTP, or legacy SSE transports. A ${PLUGIN_ROOT} variable lets a server launch a script bundled inside the plugin.
  • Reverse-domain namespaces, such as com.example.client/, carry features only one client understands, like hooks. Clients ignore namespaces they don’t implement.

The spec favors partial loading over all-or-nothing failure. A client without MCP support still loads the skills, and a broken server entry skips that server, not the whole plugin. Only an invalid manifest rejects the plugin outright.

The spec also limits what it standardizes. Distribution, installation, permissions, and marketplaces stay with each client, so the same plugin still installs differently in each agent product.

In npm terms, a skill resembles a module, and a plugin resembles the package that ships several modules, plus the MCP servers they depend on, behind one manifest.

Trade-offs and Limitations

Agent Skills pay off for reusable procedures and cost more than they return in some situations.

Benefits

For skill authors:

  • Portability. Write a skill once, and it works across compatible agents.
  • Version control. Skills are files in repositories, so you can track changes, review updates, and keep history.
  • Community sharing. Publish skills to registries, and others can discover and use them.
  • Organizational knowledge capture. Package team or company knowledge as reusable skills.

For agent developers:

  • Extensibility without code. Users add capabilities without changing your agent’s code.
  • Ecosystem growth. Each new skill makes your agent more useful.
  • Reduced maintenance. Skill authors maintain their skills, so you don’t.
  • Standard format. One integration works for every skill.

For end users:

  • On-demand expertise. Install skills to give agents domain expertise, best practices, or team conventions.
  • Consistent application. Skills apply the same knowledge in every conversation.
  • Discoverability. Browse registries to find skills that solve your problems.
  • Interoperability. Use the same skills across different agent products.

Costs and Limitations

  • Skill quality varies. Skills are only as good as their authors, and poorly written ones mislead agents.
  • Discovery overhead. Every installed skill’s description takes up context, and overlapping descriptions can lead the agent to pick the wrong skill or none.
  • Skill maintenance. Skills go stale as practices change and need updates.
  • Compatibility requirements. Skills work only with agents that support the format.
  • Interpretation differences. Different agents may interpret the same skill differently.
  • Security exposure. Skills can bundle scripts the agent runs and instructions it follows. An untrusted skill can carry a prompt injection or malicious code, so review third-party skills the way you review dependencies.

When Not to Use Agent Skills

Agent Skills are sometimes the wrong choice:

  • Highly dynamic knowledge. If procedures change constantly, maintaining a skill can cost more than giving direct instructions.
  • Sensitive knowledge in shared repositories. A skill published to a public registry exposes everything in it. Keep confidential procedures in a private repository with access controls, or out of skills entirely.
  • Simple, one-off tasks. If you need the knowledge only once, custom instructions are simpler.
  • Performance-critical applications. Skill discovery and loading add overhead that can matter when latency is critical.

Use Agent Skills where reusability and standardization outweigh maintenance and discovery costs.

Common Misconceptions

Several misconceptions about Agent Skills cause confusion.

Agent Skills are only for coding

Agent Skills apply to any domain with procedural knowledge: design, writing, data analysis, legal review, and marketing. Any task with repeatable procedures benefits.

Agent Skills require programming knowledge

Skills are written in Markdown, so non-programmers can create skills for business processes, writing guidelines, or design patterns. Some skills include code, but many need none.

Agent Skills replace agent training

Agent Skills complement training data; they don’t replace it. Training supplies general knowledge, while skills supply specific, current procedural knowledge that training data lacks or that changes often.

Agent Skills are only for large teams

Skills benefit individuals, teams, and organizations. Solo developers can create skills for personal workflows, small teams can share conventions, and large organizations can standardize practices.

All agents support Agent Skills

Skills work only in agent products that implement the format. Adoption is wide but incomplete, so check your agent’s documentation.

Conclusion

Agent Skills are folders of instructions and resources that agents load on demand, so procedural knowledge lives in version control instead of in explanations you repeat. Skill authors write it once, agent developers gain extensibility without maintaining every capability, and end users stop pasting the same context into every chat, all without retraining a model.

Skip them for fast-changing knowledge, confidential procedures without a private repository, and one-off tasks. Otherwise, package procedural knowledge as a skill when more than one person or agent will need it more than once.

Next Steps

References