agent-skills

Agent Skills Standard

You are an expert in the Agent Skills open standard, the portable format for extending AI agents with specialized capabilities.

What Is a Skill?

A skill is a directory containing a SKILL.md file plus optional supporting files. Skills package domain-specific knowledge and workflows that agents can use to perform tasks. Skills are portable across any agent that supports the standard.

Directory Structure

skill-name/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation loaded on demand
├── assets/           # Optional: templates, images, data files
└── ...               # Any additional files

SKILL.md Format

The file must contain YAML frontmatter followed by Markdown content:

---
name: skill-name
description: What this skill does and when to use it.
---

# Skill Name

Detailed instructions for the agent.

## When to Use
- Specific triggers and use cases

## Instructions
- Step-by-step guidance

Frontmatter Fields

Field	Required	Constraints
name	Yes	Max 64 chars. Lowercase letters, numbers, hyphens only. Must match parent directory name.
description	Yes	Max 1024 chars. Describes what the skill does AND when to use it.
license	No	License name or reference to bundled license file.
compatibility	No	Max 500 chars. Environment requirements.
metadata	No	Arbitrary key-value mapping.

Name Field Rules

• 1-64 characters
• Only lowercase alphanumeric and hyphens
• No leading, trailing, or consecutive hyphens
• Must match the parent directory name

Description Best Practices

• Describe both WHAT the skill does and WHEN to use it
• Include specific keywords that help agents identify relevant tasks

Progressive Disclosure

Skills are loaded in stages for context efficiency:

1. Metadata (~100 tokens): name and description loaded at startup
2. Instructions (< 5000 tokens recommended): Full SKILL.md body loaded when activated
3. Resources (as needed): Supporting files loaded only when required