SKILL.md structure

Every skill requires a SKILL.md file with YAML frontmatter:

.agents/skills/SKILL-NAME/SKILL.md
 1---
 2name: Skill name
 3description: Brief description of what this Skill does and when to use it
 4---
 5
 6# Skill name
 7
 8## Instructions
 9- Clear, step-by-step guidance for your coding agent to follow
10
11## Examples
12- Concrete examples of using this Skill
name:

  • Maximum 64 characters

  • Lowercase letters, numbers and hyphens only

  • No reserved words such as claude

examples include pdf2txt or rest-api.

description:

  • Must not be empty

  • Maximum 1024 characters

  • Describe what the skill does and when it should be used. A good example is

    description: Generate descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes.
Consistent terminology

Choose a term and use it consistently throughout the skill; do not mix API endpoint with URL, API route and path.

Avoid Windows-style path notation

Always use forward slashes (/) in file paths, even on Windows.

Avoid offering too many options

Do not present multiple approaches unless necessary.

Guidelines for progressive disclosure

  1. To ensure the skill performs optimally, the SKILL.md file should be less than 500 lines long.

  2. Split the content into separate files if you are approaching this limit.

  3. Use the patterns described in Directory structure to organise instructions, code and resources effectively.

Example

.agents/skills/rest-api/SKILL.md
---
name: rest-api
description: REST API design
---

# REST API design
- Use kebab-case for URL paths
- Use camelCase for JSON properties
- Always include pagination for list endpoints
- Version APIs in the URL path (`/v1/`, `/v2/`)