SKILL.md Format

The SKILL.md file is the core component of any agent skill. It consists of YAML frontmatter followed by Markdown instructions that guide the agent’s behavior.

File Structure

A SKILL.md file has two main parts:

YAML Frontmatter - Structured metadata enclosed in --- delimiters
Markdown Body - Instructions, examples, and guidance for the agent

Basic Example

---
name: creating-reports
description: Creates detailed reports from data when the user asks for report generation or data summaries.
---

# Creating Reports Skill

This skill helps generate comprehensive reports from various data sources.

## Usage

This skill is triggered when users request:
- Report generation
- Data summaries
- Analytics exports

Frontmatter Fields

The frontmatter section supports the following fields according to the Agent Skills specification:

Required Fields

string

required

Skill identifier in lowercase-hyphen format. Must match the parent directory name.Constraints:

Maximum 64 characters
Lowercase letters, numbers, and hyphens only
Cannot start or end with a hyphen
No consecutive hyphens (--)

Example: creating-reports, data-analysis, api-client

string

required

Brief explanation of what the skill does and when to use it.Constraints:

Maximum 1024 characters
Should not be empty or whitespace-only
Should include activation phrases like “Use when…”, “Designed for…”

Example: "Creates detailed reports from data when the user asks for report generation or data summaries."

Optional Fields

string

Runtime requirements and prerequisites for this skill.Constraints:

Maximum 500 characters if provided
Cannot be empty if present

Example: "Requires Node.js 18+ and Python 3.9+"

string

License identifier for the skill.Example: "MIT", "Apache-2.0"

object

Custom key-value pairs for additional metadata.Constraints:

Must be a string-to-string mapping
Both keys and values must be strings

Example:

metadata:
  author: "Jane Smith"
  version: "1.0.0"

string

Space-delimited list of allowed tools (experimental).Constraints:

Must be a string, not a YAML list
Use space-delimited format

Example: "bash read write edit"

Custom fields should be placed in the metadata map rather than as top-level frontmatter fields to maintain spec compliance.

Markdown Body

The body section provides instructions and context for the agent. This is where you explain how the skill works, when to use it, and provide examples.

Body Guidelines

Constraint	Value	Severity
Token budget	≤5,000 tokens	Warning
Line budget	≤500 lines	Warning
Minimum content	≥50 characters	Warning

Token estimates are calculated using a simplified tokenizer that approximates Claude’s tokenization. The actual token count may vary slightly.

Best Practices

Include Code Examples - Use fenced code blocks (```) or <example> tags to show how the skill works
Add Activation Context - Explain when and why the agent should use this skill
Reference Scripts - If your skill includes scripts in the /scripts folder, mention them in the body
Keep It Concise - Aim for clarity and brevity to stay within token budgets

Example Body Structure

# Skill Name

Brief overview of what this skill does.

## When to Use

Describe scenarios where this skill should be activated:
- Scenario 1
- Scenario 2
- Scenario 3

## Instructions

Step-by-step guidance for the agent.

## Examples

```python
# Example code showing the skill in action
def example():
    pass

Notes

Additional context, limitations, or tips.

## Folder Structure

A complete skill directory may include:

skill-name/ ├── SKILL.md # Required: Main skill definition ├── scripts/ # Optional: Helper scripts │ ├── setup.py │ └── process.sh ├── references/ # Optional: Reference documentation │ ├── api-docs.md │ └── examples.txt └── assets/ # Optional: Static assets └── template.json

### Scripts Folder

Valid script extensions (from `structure.py:11`):
- `.py` - Python
- `.sh` - Shell
- `.js` - JavaScript
- `.ts` - TypeScript
- `.bash` - Bash
- `.rb` - Ruby

<Warning>
  Scripts should not use interactive input patterns (like `input()` in Python or `read` in Bash) as agents run in non-interactive shells.
</Warning>

### References Folder

Valid reference file extensions (from `structure.py:14`):
- `.md` - Markdown
- `.txt` - Plain text
- `.rst` - reStructuredText

<Note>
  References should be maximum 1 level deep to avoid excessive nesting.
</Note>

## Validation

Skill Lab performs 28 static checks across 4 dimensions to validate SKILL.md files. Use the following commands:

```bash
# Full evaluation with quality score
sklab evaluate ./my-skill

# Quick pass/fail validation
sklab validate ./my-skill

# Show skill metadata and token estimates
sklab info ./my-skill

See Quality Scoring for details on how skills are evaluated.

Get Started

Guides

Core Concepts

Development

File Structure

Basic Example

Frontmatter Fields

Required Fields

Optional Fields

Markdown Body

Body Guidelines

Best Practices

Example Body Structure

Notes

​File Structure

​Basic Example

​Frontmatter Fields

​Required Fields

​Optional Fields

​Markdown Body

​Body Guidelines

​Best Practices

​Example Body Structure

​Notes

File Structure

Basic Example

Frontmatter Fields

Required Fields

Optional Fields

Markdown Body

Body Guidelines

Best Practices

Example Body Structure

Notes