Skip to main content
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:
  1. YAML Frontmatter - Structured metadata enclosed in --- delimiters
  2. 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

​
name
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
​
description
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

​
compatibility
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+"
​
license
string
License identifier for the skill.Example: "MIT", "Apache-2.0"
​
metadata
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"
​
allowed-tools
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

ConstraintValueSeverity
Token budget≤5,000 tokensWarning
Line budget≤500 linesWarning
Minimum content≥50 charactersWarning
Token estimates are calculated using a simplified tokenizer that approximates Claude’s tokenization. The actual token count may vary slightly.

​
Best Practices

  1. Include Code Examples - Use fenced code blocks (```) or <example> tags to show how the skill works
  2. Add Activation Context - Explain when and why the agent should use this skill
  3. Reference Scripts - If your skill includes scripts in the /scripts folder, mention them in the body
  4. 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.

Build docs developers (and LLMs) love

Get started for freeTalk to us