What is an agent skill? How agent skills work

Introduction

AI agents are becoming more capable, but capability alone does not tell an agent how your team expects a task to be handled. That knowledge often lives across prompts, documentation, examples, and internal processes.

Agent skills provide a way to package that knowledge into reusable instructions and resources an agent can load when needed. This guide explains what an agent skill is, how agent skills work, what belongs in a SKILL.md file, and how skills relate to prompts, tools, MCP, and workflows.

What is an agent skill?

An agent skill is a reusable package of instructions, knowledge, and supporting resources that helps an AI agent perform a specific type of task. It gives the agent a repeatable method for approaching the work, including the steps to follow, standards to apply, and resources to use.

An agent skill can capture:

• Procedures: Steps for handling a recurring task, such as reviewing code or triaging an incident.
• Organizational practices: Team conventions, review criteria, approval requirements, or internal processes.
• Domain knowledge: Specialized guidance the agent needs for areas such as engineering, security, finance, or product management.
• Templates and examples: Reference outputs that show the expected structure, format, or level of detail.
• Scripts and supporting resources: Executable code, documentation, schemas, or other files the agent can use while completing the task.

For example, a code-review skill could give an AI agent the team's review criteria, required security and quality checks, expected response format, and references to relevant engineering standards. The same skill can then guide future code reviews without requiring those instructions to be rewritten each time.

The Agent Skills format has also been published as an open standard designed to make skills portable across compatible tools and platforms. A skill is typically organized around a SKILL.md file, which contains the core metadata and instructions the agent uses to understand when and how to apply the skill.

What is inside an agent skill?

An agent skill is organized as a directory containing the instructions and resources an AI agent needs for a particular kind of work. The required piece is a SKILL.md file. More involved skills can add scripts, reference material, templates, and other assets that the agent accesses when needed.

A typical skill can look like this:

example-skill/
├── SKILL.md
├── scripts/
├── references/
└── assets/

SKILL.md

SKILL.md is the central file in an agent skill. It tells the agent what the skill is for and provides the instructions it should follow when using it.

The file typically covers:

• Skill name: A clear identifier for the capability.
• Description: A concise explanation of what the skill does and when it should be used.
• Instructions: The steps, rules, constraints, and guidance the agent should follow.
• Expected process or behavior: Details about how the work should be carried out, including relevant standards, checks, or output requirements.

For example, a release-notes skill might instruct an agent to collect completed work items, group changes by category, follow a specific writing style, exclude internal-only information, and produce the final notes in a defined format.

Metadata and YAML frontmatter

A SKILL.md file begins with YAML frontmatter containing metadata about the skill. In the Agent Skills structure described by Anthropic, name and description are required fields.

---
name: release-notes
description: Create release notes from completed work items using the team's publishing guidelines.
---

The description deserves particular attention because it helps the agent determine when the skill is relevant. A vague description can make skill selection harder, while a specific one gives the agent a clearer signal about the situations in which the skill should be loaded.

The detailed procedure then lives in the body of SKILL.md, keeping lightweight discovery information separate from the instructions needed during execution.

Supporting resources

Some skills need more than written instructions. Supporting files can sit alongside SKILL.md and provide deeper context or executable resources for specific parts of the task.

• Scripts: Executable code, such as Python or Bash scripts, for operations where a repeatable programmatic step is useful.
• References: Documentation, schemas, policies, specifications, API guidance, or detailed domain information the agent can consult when relevant.
• Assets: Templates, examples, document files, or other materials used to produce the expected output.

Keeping these resources separate also supports progressive disclosure. The agent can begin with lightweight information about the skill, load the full SKILL.md when the skill becomes relevant, and reach for additional files only when the task requires them.

How do agent skills work?

Agent skills work by giving an AI agent access to specialized instructions only when a task calls for them. The agent starts with lightweight information about the skills available, identifies a relevant skill, loads its instructions, and then pulls in supporting resources as the work progresses.

A typical runtime flow looks like this:

1. Discovery

The agent first sees the metadata for the skills available in its environment. This usually includes the skill's name and description, which provide enough context to understand what the skill is designed to handle.

Keeping this initial layer small helps the agent scan a larger set of skills without loading every instruction into its context window.

2. Selection

When a task arrives, the agent compares the request with the available skill descriptions and determines whether a relevant skill should be used.

This makes the skill description especially important. It needs to give the agent a clear signal about the situations in which the skill applies.

3. Loading

Once a skill is selected, the agent loads the body of its SKILL.md file into the working context. At this point, it gains access to the detailed procedure, rules, constraints, and guidance required to complete the task.

4. Execution

The agent follows those instructions while carrying out the task. Depending on the skill, this may involve reasoning through a process, using agent tools, running scripts, retrieving information, or combining several capabilities.

For example, a release-management skill could instruct the agent to gather completed work, check required fields, group changes by release type, and format the final output according to the team's release process.

5. Additional resource loading

If the task requires more detail, the agent can access supporting files referenced by the skill, such as documentation, templates, schemas, or scripts.

These resources are loaded as they become relevant rather than being placed in the context from the start.

How does progressive disclosure work?

Progressive disclosure is the mechanism that keeps this process efficient. Information is revealed to the agent in layers:

Metadata → SKILL.md instructions → supporting resources

The first layer helps the agent discover the right skill. The second provides the working instructions once that skill is selected. The third contains deeper material that the agent can access only when the task requires it.

This approach keeps the agent's working context focused. A system may contain many agent skills, each with substantial documentation and supporting files, while only the relevant pieces are loaded for the task at hand.

Agent skills vs. prompts vs. tools vs. MCP vs. workflows

Agent skills sit alongside several other building blocks used in AI agent systems. The differences become clearer when you look at the role each one plays.

Agent skill vs. prompt

A prompt gives an AI agent instructions for the interaction at hand. You might ask an agent to review a pull request, summarize a project update, or follow a particular output format.

An agent skill packages guidance that can be reused whenever that type of work appears. A team that reviews hundreds of pull requests, for example, could place its review process, coding standards, security checks, and expected output structure inside a skill. Future reviews can draw on the same maintained procedure without recreating the guidance in every conversation.

This makes prompts useful for immediate context and skills useful for procedures that need to persist across repeated work.

Agent skill vs. tool

The distinction between agent skills vs. tools comes down to procedural knowledge and executable capability.

• A tool gives the agent a callable operation. Depending on the environment, that could mean searching a codebase, querying a database, creating a work item, calling an API, or reading a file.
• A skill gives the agent guidance for carrying out a broader job. That guidance can include which tools to use, when to use them, what information to check, and how to interpret the result.

For example, an incident-response skill might instruct an agent to:

1. Retrieve recent alerts.
2. Check affected services.
3. Review relevant logs.
4. Compare findings with the incident runbook.
5. Create an incident record.
6. Prepare a structured summary for the on-call team.

The individual search, log, and work-item operations may come from agent tools. The skill provides the procedure that connects those capabilities into a meaningful way of handling the incident.

Agent skill vs. MCP

The Model Context Protocol, or MCP, is an open standard for connecting AI applications to external systems. An MCP server can expose tools, resources, and prompts that an AI application can discover and use.

An agent skills package contains reusable knowledge about how to perform a type of work.

Consider an agent responsible for preparing a weekly engineering status report. An MCP server could give the agent access to project data and callable operations. A reporting skill could contain the team's rules for choosing metrics, identifying risks, grouping updates, and formatting the final report.

Used together, MCP can provide the access and capabilities, while the skill provides the procedure for applying them to the task. MCP tools themselves are designed as callable functions that let models take actions such as querying databases or invoking external APIs.

Agent skill vs. workflow

A workflow describes how a process moves through a defined set of steps, conditions, or actions. Workflows are especially useful when the sequence itself needs to be coordinated reliably.

A skill gives the agent reusable guidance for carrying out work that may require judgment along the way.

For example, a bug-triage workflow might route a newly reported issue through predefined stages based on priority or ownership. A bug-triage skill could teach the agent how to assess severity, identify likely duplicates, determine what context is missing, and prepare a useful triage summary.

These concepts can also work together. A workflow can determine when a particular piece of work happens, tools can provide the actions required to complete it, MCP can expose external capabilities and data, and an agent skill can provide the specialized knowledge the agent uses while handling the task.

What are agent skills used for?

Agent skills are useful when a task depends on repeatable judgment, domain knowledge, or a defined way of working. The strongest use cases tend to be areas where teams already rely on checklists, standards, templates, review criteria, or internal processes.

1. Software development

In engineering teams, AI agent skills can capture the practices that shape how code is written, reviewed, tested, and released.

A code-review skill, for example, could guide an agent through repository conventions, security checks, test expectations, and review criteria. Other skills might cover debugging procedures, test generation, release preparation, or the conventions used across a specific codebase.

2. Research and analysis

Research work often depends on a consistent method for gathering evidence, evaluating sources, and presenting findings.

An agent skill could define how an AI agent should structure a market analysis, assess source quality, apply domain-specific evaluation criteria, or turn raw data into a report. The skill can also point the agent to relevant reference material, templates, or scripts used during the analysis.

3. Operations and support

Operational work is usually shaped by established procedures, escalation paths, and service standards, which makes it a natural fit for reusable skills.

An incident-investigation skill could guide an agent through collecting logs, checking recent changes, reviewing known issues, and preparing a handoff for the on-call engineer. Support teams could use skills for ticket classification, gathering missing context, applying escalation criteria, or following standard operating procedures.

4. Content and communication

Teams can also use agent skills to encode the rules behind recurring communication tasks.

A content-review skill might contain brand guidelines, terminology rules, editorial standards, and review criteria. A documentation skill could guide the agent through a required structure, audience assumptions, formatting conventions, and source requirements. Similar skills can support release notes, status updates, internal reports, and customer-facing communication.

5. Project and work management

Project and product teams often have their own conventions for how work is created, reviewed, prioritized, and communicated.

An agent skill could guide work-item triage by defining which fields to check, how to assess missing context, and when an item should be escalated. Other examples include preparing project status reports, applying team naming conventions, reviewing planning inputs, or following project-specific procedures when creating and updating work.

Across these examples, the value comes from giving AI agents a reusable method for carrying out work according to the standards of the team or organization using them.

What are the benefits of agent skills?

Agent skills make specialized guidance easier to reuse, maintain, and apply across repeated work.

1. Reusability: Define a procedure once and make it available whenever the same type of task appears, instead of recreating the instructions each time.
2. Context efficiency: Load specialized instructions only when they are relevant, which helps keep the agent's working context focused on the task at hand.
3. Consistency: Give agents access to the same procedures, standards, and supporting context across similar tasks. Results can still vary because model behavior and task context influence execution.
4. Maintainability: Update the skill in one place when a process, policy, or standard changes, rather than editing instructions scattered across prompts and workflows.
5. Composability: Different skills can cover different areas of expertise, allowing an agent to draw on the capabilities that are relevant to a particular task.
6. Portability: Skills built around interoperable formats can be reused across compatible agent environments, reducing the effort required to recreate the same procedural knowledge for each system.

How do you create an effective agent skill?

A useful agent skill should have a narrow purpose, clear instructions, and enough supporting context for the agent to apply it reliably.

1. Start with one repeatable job: Choose a task with a clear responsibility and outcome. Skills are easier to design and evaluate when their scope is specific.
2. Give the skill a clear name and description: Use a recognizable name, then describe what the skill does and when it should be used. A precise description also helps the agent identify when the skill is relevant.
3. Write focused instructions: Define the process, important constraints, decision criteria, and expected result. Keep the guidance specific to the task and avoid adding background information the agent does not need.
4. Separate supporting information: Keep the core SKILL.md focused and move detailed documentation, policies, schemas, or examples into reference files that can be loaded when required.
5. Add scripts where they improve reliability: Use executable scripts for steps that benefit from deterministic processing, such as transforming data, validating formats, or running repeatable calculations.
6. Define expected inputs and outputs: Make clear what information the skill needs before it can begin and what a successful result should contain.
7. Test skill selection in both directions: Check tasks where the skill should activate as well as similar tasks where another skill, tool, or approach would be more appropriate. This helps uncover vague descriptions and overlapping scopes.
8. Maintain and version the skill: Review the skill as processes, tools, policies, or dependencies change. Versioning makes those updates easier to track and helps teams understand which guidance an agent is using.

How are agent skills shared and managed?

Agent skills can be treated much like other project resources. Because a skill is typically stored as a self-contained directory, teams can keep it alongside code, documentation, or other files and manage changes through version control.

Common approaches include:

1. Project-specific skills: Stored with a particular project or repository and tailored to its workflows, standards, or domain knowledge.
2. Shared organizational skills: Maintained centrally so multiple teams or agents can use the same procedures and guidance.
3. Internal skill libraries: Repositories that help teams discover approved skills, track ownership, and manage updates.
4. Public and third-party skills: External skills can extend an agent's capabilities, but teams should review their instructions, scripts, dependencies, and permissions before use.
5. Version control: Changes to SKILL.md, scripts, references, and supporting assets can be reviewed and tracked over time.
6. Open formats: Skills built around interoperable formats are easier to move between compatible agent systems and reuse across different environments.

As skill libraries grow, ownership and review become increasingly important. Teams need to know who maintains each skill, when it was last updated, and whether its instructions still reflect the current process.

Final thoughts

As AI agents take on more specialized work, reusable procedural knowledge becomes increasingly important. Agent skills provide a practical way to package that knowledge into instructions, references, scripts, and supporting resources that can be applied when relevant.

Their value comes from making repeatable work easier to maintain and reuse across tasks, teams, and compatible agent environments. The quality of the skill still depends on clear scope, precise instructions, thoughtful testing, and regular maintenance.

For teams experimenting with agentic workflows, the best place to start is usually a well-defined task that already has a repeatable process behind it.

Frequently asked questions

1. What is an agent skill?

An agent skill is a reusable package of instructions, knowledge, and supporting resources that helps an AI agent perform a specific type of task. It can include procedures, references, scripts, templates, and examples that the agent loads when the skill is relevant.

2. What is a SKILL.md file?

A SKILL.md file is the central file in an agent skill. It typically contains the skill's name, description, instructions, and guidance for how the agent should perform the task. Supporting scripts, references, and assets can be stored alongside it.

3. What is the difference between agent skills and tools?

The difference between agent skills vs. tools is their role. A tool gives an AI agent a capability it can execute, such as calling an API or searching a database. An agent skill provides reusable guidance for how and when to use capabilities as part of a broader task.

4. What is the difference between agent skills and MCP?

In the agent skills vs. MCP comparison, agent skills package reusable procedural knowledge, while MCP provides a standardized way for AI applications to access external tools, data, and resources. They can work together within the same agent system.

5. How do agent skills work?

Agent skills typically work through discovery, selection, loading, and execution. The agent first sees lightweight skill metadata, selects a relevant skill, loads its SKILL.md instructions, and accesses supporting resources such as scripts or references when needed.