What Is an Agent Skill? AI Skills Explained for Claude, Cursor, Codex and More

The Short Version

An agent skill is a markdown file that teaches an AI agent how to do something specific. It follows the SKILL.md open standard and works across 20+ platforms including Claude Code, Cursor, Codex, and Windsurf.

Think of it like a training manual for your AI assistant. Instead of explaining your code review process, deployment workflow, or SEO strategy every conversation, you write it once as a skill. The agent loads it when relevant and follows the instructions.

What Makes a Skill Different from a Plugin or Extension?

If you have used browser extensions, IDE plugins, or ChatGPT custom GPTs, you might wonder how skills compare. Here is the key difference: skills are just files.

Concept	What it is	Complexity	Runtime needed
Skill	A markdown file with instructions	Low	None
Plugin	A bundled package of skills + config	Low	None
Extension	Platform-specific code module	Medium	Yes
MCP Server	A JSON-RPC tool server	High	Yes
Custom GPT	A ChatGPT-specific wrapper	Medium	OpenAI platform

A skill requires no build step, no server, no SDK, and no deployment. You create a folder with a SKILL.md file and your agent can use it immediately.

The SKILL.md Format

Every skill is a folder containing at minimum one file: SKILL.md. This file has two parts.

1. Frontmatter (YAML metadata at the top):

---
name: code-review
description: Reviews code for bugs, security issues, and style violations. Use when the user asks for a code review.
---

2. Instructions (Markdown body):

# Code Review

## When to use
Activate when the user asks for a code review, submits a PR, or shares code for feedback.

## Process
1. Read the code carefully
2. Check for bugs and edge cases
3. Look for security vulnerabilities
4. Verify style consistency
5. Provide actionable feedback with specific examples

That is the entire format. The name and description fields are required. Everything else is optional.

How Skills Work Under the Hood

Skills use a progressive disclosure architecture. This means the agent does not load everything at once. It loads information in stages to keep context usage efficient.

Level 1: Metadata (always loaded)

At startup, the agent reads only the name and description from every installed skill. This costs about 100 tokens per skill. The agent uses this lightweight index to know what skills are available.

Level 2: Instructions (loaded on demand)

When your request matches a skill's description, the agent reads the full SKILL.md body into its context window. This is where the real instructions live.

Level 3: Resources (loaded as needed)

Skills can include additional files like scripts, reference documents, and templates. These are only loaded when the instructions reference them.

seo-audit/
├── SKILL.md              # Main instructions (~3,000 tokens)
├── scripts/
│   └── check-meta.py     # Executed, output enters context
├── references/
│   └── CHECKLIST.md       # Loaded only if SKILL.md references it
└── assets/
    └── template.json      # Used by scripts

This architecture means you can install many skills without slowing down your agent. The cost is near-zero until a skill is actually activated.

Why Skills Matter

Reusable knowledge

Without skills, every conversation starts from scratch. You re-explain your coding conventions, your review process, your deployment steps. Skills capture this knowledge once and make it available automatically.

Shareable across teams

Project-level skills live in your git repo (e.g., .claude/skills/). When a teammate clones the repo, they get the same skills. When someone leaves the team, their expertise stays in the skills they wrote.

Cross-platform portability

Write a skill once. Use it in Claude Code, Cursor, Codex, Windsurf, Copilot, and 20+ other platforms. The same SKILL.md file works everywhere because it is an open standard.

Composable

Skills are independent modules. You can install a code review skill, a testing skill, and a deployment skill. The agent picks the right one based on context. No configuration needed.

Real Examples from the Directory

agentskill.sh indexes over 69,000 skills. Here are some examples of what skills look like in practice.

Development skills

Code review skills that enforce your team's specific conventions
Testing skills that follow your project's test patterns
Git workflow skills that match your branching strategy

Non-developer skills

SEO content skills that follow keyword research and on-page optimization workflows
Cold email skills with outreach templates and personalization rules
Accounting skills that handle country-specific tax regulations

Infrastructure skills

Deployment skills with step-by-step CI/CD procedures
Database migration skills with validation and rollback steps
Monitoring skills that check specific health endpoints

You can browse the full directory to find skills for your use case.

Skills vs MCP Servers

This is a common question. The short answer: skills provide knowledge and instructions. MCP servers provide tool access. They are complementary.

A skill might say: "When the user asks to analyze their database, run this query pattern and format the results as a table." An MCP server provides the actual database connection that makes the query possible.

You can use both together. A skill can reference MCP tools by name, combining instructions with tool access. Read the full comparison at Skill vs MCP.

The Open Standard

The SKILL.md format was originally developed by Anthropic and released as an open standard. It is now supported by 20+ AI platforms and has been adopted by thousands of developers.

The specification is maintained on GitHub and is open to contributions. Any platform can add skill support by parsing SKILL.md frontmatter and following the progressive disclosure loading pattern.

Getting Started

Ready to use skills? Here is where to go next.

Install skills: Learn how to add skills to your agent with How to Install a Skill
Create your own: Follow the step-by-step tutorial at How to Create a Skill
Understand frontmatter: See the complete field reference at SKILL.md Frontmatter Guide
Skills vs MCP: Read the detailed comparison at Skill vs MCP
Browse the directory: Find skills for your platform and use case at agentskill.sh

FAQ

What is a Claude skill?

A Claude skill is a SKILL.md file that teaches Claude how to perform a specific task. It contains metadata (name and description) plus markdown instructions that Claude loads on demand. Skills work in Claude Code, Claude Desktop, and via the Claude API.

What is the difference between a skill and an MCP server?

Skills are lightweight markdown files that provide instructions and knowledge. MCP servers are heavier runtime processes that give agents access to external tools and APIs. Skills teach agents how to do things. MCP servers give agents tools to interact with external systems. You can use both together.