The Agent Skills Specification, Explained

What is the Agent Skills specification?

The fragmentation problem in AI tooling is real. You build a workflow for Claude Code, but your teammate uses Cursor. Another colleague is on Windsurf. Everyone has different configurations, different capabilities, different ways of doing the same thing.

The Agent Skills specification solves this. It's an open standard — originally developed at Anthropic — that defines a portable format for AI tool capabilities. Write a skill once, and it works across 40+ compatible tools.

How do Agent Skills work?

A skill is a directory containing a SKILL.md file plus any supporting resources (scripts, references, templates). The SKILL.md uses YAML frontmatter for metadata and Markdown for instructions:

my-skill/
├── SKILL.md              # Instructions + metadata
├── scripts/
│   └── run.sh            # Supporting scripts
└── references/
    └── format.md         # Reference docs

AI tools discover skills by scanning the .agents/skills/ directory (universal) or .claude/skills/ (Claude Code-specific). When a user's request matches a skill's description, the tool activates it automatically.

What is the skill file format?

A SKILL.md file looks like this:

---
name: my-skill
description: >
  Brief description of what this skill does and when to use it.
license: MIT
allowed-tools: Bash Read Write
---

# My Skill

Instructions for the AI tool to follow when this skill is activated.

## What steps does a skill follow?

1. First, do this
2. Then do that
3. Finally, verify the result

The frontmatter tells the AI tool what the skill is and what permissions it needs. The body contains the actual instructions.

Which AI tools support Agent Skills?

As of 2026, 40+ AI coding tools support the Agent Skills spec:

• Claude Code — Full support with slash command invocation
• Cursor — Auto-detection from project directory
• Windsurf — Auto-detection from project directory
• GitHub Copilot — Auto-detection from project directory
• Gemini CLI — Auto-detection from project directory
• Amp, Cline, Codex, Roo Code, OpenHands, Kiro, Junie — and many more

The universal install path is .agents/skills/ in your project root. Claude Code also checks .claude/skills/.

What is the difference between skills and MCP servers?

Both extend AI tool capabilities, but in different ways:

MCP servers provide live connections to external systems — databases, APIs, browsers. They run as background processes and expose tools the AI can call.

Skills provide instructions and workflows. They tell the AI how to do something, step by step. Skills can reference MCP servers as dependencies.

Think of it this way: an MCP server gives the AI access to Elasticsearch. A skill teaches the AI how to analyze logs using Elasticsearch effectively.

How do you create your own skill?

The best skills follow these principles:

Be specific about the trigger. The description field determines when the skill activates. "Publish AI agents" is better than "help with publishing."

Break work into phases. Numbered steps with clear decision points produce more reliable results than monolithic instructions.

Include error handling. Tell the AI what to do when things go wrong — common errors, retry strategies, fallback approaches.

Reference real tools. If your skill needs an MCP server, include the .mcp.json config so users can set it up.

How does the Agent Shelf publish skill work?

We built Agent Shelf's own publish skill as a reference implementation. It demonstrates all the best practices:

• 6-phase workflow — Detection, Analysis, Conversion, Authentication, Publishing, Bulk Operations
• Shell script helpers — Real scripts for auth, detection, and API calls
• Reference docs — Schema specification and valid categories
• Cross-tool compatibility — Works with Claude Code, Cursor, Windsurf, and any Agent Skills-compatible tool

You can download it and study the structure, or install it to publish agents directly from your coding environment.

Why does portability matter for AI skills?

The Agent Skills spec is still evolving, but the direction is clear: AI tool capabilities should be portable, discoverable, and composable. As the ecosystem matures, expect to see skill registries, dependency management, and automated skill discovery become standard.

Agent Shelf is built on this vision — a registry where agents and skills are shared across the entire ecosystem, not locked into any single tool.