What Are Agent Skills — Adding Reusable Capabilities to AI Agents

Introduction

Claude Code, Cursor, Codex, Gemini CLI — AI-powered development tools keep multiplying. But as the number of tools grows, so do the challenges: "I want to reuse the setup from one agent in another" and "I need the whole team to share the same workflow."

Agent Skills is the solution to these challenges. They are reusable plugins you can add to any agent, defined in a common format called SKILL.md.

This article covers how Agent Skills came to be, how they differ from existing customization methods, the structure of SKILL.md, and how to build your own skills.

The Birth and Spread of Agent Skills

Origins

Agent Skills were designed and developed by Anthropic, first released in October 2025 as a feature of Claude Code. The design was led by Anthropic's Barry Zhang, Keith Lazuka, and Mahesh Murag — the latter also being one of the creators of the Model Context Protocol (MCP).

Shortly after launch, security researcher Simon Willison commented that Agent Skills "might have a bigger impact than MCP," drawing significant attention.

Open Standardization and Rapid Adoption

The same strategy that worked for MCP — Anthropic builds it first, releases it as an open standard, and competitors adopt en masse — has succeeded again.

How Agent Skills Differ from Custom Slash Commands

Before Agent Skills, each agent had its own customization mechanisms: .claude/commands/ for Claude Code, .cursor/rules/ for Cursor, and so on. How are Agent Skills different?

Three Layers of Customization

AI agent customization breaks down into roughly three layers:

Progressive Disclosure

The technical key to Agent Skills is efficient use of the context window:

1. Tier 1 (always): Only the frontmatter name and description are loaded (~100 tokens)
2. Tier 2 (when relevant): If the agent determines the task is related, the SKILL.md body is loaded
3. Tier 3 (at execution): Files in scripts/ and references/ are loaded only when actually needed

Rule files are always fully loaded, so they eat into the context window as they accumulate. Slash commands require the user to explicitly invoke them. Agent Skills combine the strengths of both — loading only when needed, and only as much as needed.

Portability

The other major difference is portability. .claude/commands/ only works in Claude Code; .cursor/rules/ only works in Cursor. Agent Skills run on every supported agent from the same SKILL.md. Team members using different agents can still share the same skills.

How Agent Skills Work

What Is a Skill?

Agent Skills are installable modules that add specific capabilities to an AI agent.

For example, installing a "spec generator" skill means you can simply tell the agent "create a requirements doc," and it produces a specification in the defined format. Without the skill, you'd need to craft a prompt every time. With it, the process, output format, and quality standards are all standardized.

Without skills: Craft a prompt each time → inconsistent output
With skills:    "Create a requirements doc" → standardized spec generated

The SKILL.md Format

Every skill is defined in a file called SKILL.md. It's an open standard created by Anthropic, with a simple structure: YAML frontmatter + Markdown body.

---
name: spec-generator
description: |
  Generate project requirements, design documents, and task lists.
  Triggers: "Create requirements", "Create a spec"
license: MIT
---
 
# spec-generator
 
(Detailed instructions for the agent go here)
 
## Execution Flow
1. Parse user input
2. Investigate project structure
3. Generate requirements document
...

The frontmatter contains skill metadata (name, description, trigger phrases), while the body describes the concrete steps the agent should follow at execution time.

Directory Structure

Skill directories follow this pattern:

skills/
└── skill-name/
    ├── SKILL.md              # Skill definition (required)
    └── references/           # Supplementary docs (optional)
        ├── guide.md          # English guide
        └── guide.ja.md       # Japanese guide

SKILL.md is the core of the skill, while references/ holds supplementary materials. The skill body can reference files in references/ to keep its own line count manageable while still providing detailed information.

Supported Agents and Ecosystem

Supported Agents

As of February 2026, 17+ agents support the SKILL.md format. The major ones:

Additional agents including Amp, Goose, Roo, Trae, and Droid also support the format. Since skills are agent-independent, a skill you create once works across all of these agents.

Installation

Skills are installed via the npx skills command:

# Install from a GitHub repository
npx skills add username/repo-name -g -y
 
# Install a specific skill only
npx skills add username/repo-name --skill skill-name -g -y

The -g flag installs globally (to ~/.claude/skills/). Omit -g for project-specific installation (to .claude/skills/).

Publishing Skills

Skills are published as GitHub repositories. Place skills in the repository's skills/ directory and include installation commands in the README. No dedicated registry like npm or PyPI is needed.

Building Your Own Skills

Minimal Setup

The minimum setup is just a directory and a SKILL.md file:

mkdir -p skills/my-skill

---
name: my-skill
description: |
  A brief description of what this skill does.
  Trigger: "do something"
license: MIT
---
 
# my-skill
 
## Execution Flow
 
1. Parse user input
2. Gather necessary information
3. Output results
 
## Output Format
 
(Describe output format and rules)

Design Tips

A few guidelines for designing effective skills:

Define clear trigger phrases

Include natural-language phrases in the description that users would naturally say. For multilingual support, include both languages:

description: |
  Generate requirements documents.
  Triggers: "Create requirements", "Create a spec"

Write concrete instructions

The steps the agent follows should be specific enough that a human reader wouldn't be confused. Avoid vague expressions like "handle appropriately" — spell out the specific inputs, processing steps, and outputs.

Don't hardcode tool names

Referencing specific MCP servers or tool names makes the skill break in environments without those tools. Describe actions in terms of capabilities instead:

# Good
Read the file to understand the existing code structure.

# Bad
Use mcp__serena__read_file to read the file.

Keep it under 500 lines

An overly long SKILL.md consumes too much agent context. Move detailed information to references/ and load it on demand.

Summary

Agent Skills are an open mechanism for adding reusable capabilities to AI agents.

• SKILL.md provides a common format for defining agent-independent skills
• npx skills add enables one-command installation from GitHub repositories
• Easy to build — start with just a directory and one Markdown file
• Team sharing — standardize workflows and ensure consistent quality through shared skills

At ZenChAIne, we've built on Agent Skills to publish an open-source agent-skills repository. It implements spec-driven development workflows as skills. See the articles below for details.

agent-skills をオープンソース公開 — AIエージェントによる仕様駆動開発の実践仕様駆動開発を AIエージェントのスキルとして実装した agent-skills をオープンソース公開しました。zench-aine.io

仕様駆動開発（Spec-Driven Development）実践ガイド仕様駆動開発の考え方、バイブコーディングとの違い、具体的なワークフローを解説します。zench-aine.io