Skip to main content
Want to understand how skills work under the hood? This guide breaks down every part of a skill file.

​
Basic Folder Structure

skills/
└── my-skill-name/
    ├── SKILL.md              ← Required: The main skill definition
    ├── examples/             ← Optional: Example files
    │   ├── example1.js
    │   └── example2.py
    ├── scripts/              ← Optional: Helper scripts
    │   └── helper.sh
    ├── templates/            ← Optional: Code templates
    │   └── template.tsx
    ├── references/           ← Optional: Reference documentation
    │   └── api-docs.md
    └── README.md             ← Optional: Additional documentation
Key Rule: Only SKILL.md is required. Everything else is optional!

​
SKILL.md Structure

Every SKILL.md file has two main parts:
  1. Frontmatter (Metadata) - YAML configuration at the top
  2. Content (Instructions) - Markdown documentation for the AI

​
Part 1: Frontmatter

The frontmatter is at the very top, wrapped in ---: 
---
name: my-skill-name
description: "Brief description of what this skill does"
---

​
Required Fields

  • What it is: The skill’s identifier
  • Format: lowercase-with-hyphens
  • Must match: The folder name exactly
  • Example: stripe-integration
  • What it is: One-sentence summary
  • Format: String in quotes
  • Length: Keep it under 200 characters (validator enforces this)
  • Example: "Stripe payment integration patterns including checkout, subscriptions, and webhooks"

​
Optional Fields

Some skills include additional metadata: 
---
name: my-skill-name
description: "Brief description"
risk: "safe" # none | safe | critical | offensive
source: "community"
tags: ["react", "typescript"]
date_added: "2024-01-15"
---
Risk level classification:
  • none: Pure text/reasoning (e.g., Brainstorming)
  • safe: Reads files, runs safe commands (e.g., Linter)
  • critical: Modifies state, deletes files, pushes to prod (e.g., Git Push)
  • offensive: Pentesting/Red Team tools (requires warnings)
  • unknown: Legacy/unclassified (prefer concrete level for new skills)
  • What it is: Attribution URL or origin
  • Format: URL to original source or “self” if original
  • Example: "https://github.com/vercel-labs/agent-skills"
  • What it is: The date when the skill was created or added to the collection
  • Format: YYYY-MM-DD (ISO 8601 date format)
  • Purpose: Helps track skill versioning and community contributions
  • Required: No (optional, but recommended)
  • Example: date_added: "2024-01-15"
  • Note: Can be managed automatically with the scripts/manage_skill_dates.py script

​
Part 2: Content

After the frontmatter comes the actual skill content. Here’s the recommended structure:
1

Title (H1)

# Skill Title
Use a clear, descriptive title that usually matches or expands on the skill name.
2

Overview

## Overview

A brief explanation of what this skill does and why it exists.
2-4 sentences is perfect.
3

When to Use

## When to Use This Skill

- Use when you need to [scenario 1]
- Use when working with [scenario 2]
- Use when the user asks about [scenario 3]
This section is critical! It helps the AI know when to activate this skill.
4

Core Instructions

## How It Works

### Step 1: [Action]

Detailed instructions...

### Step 2: [Action]

More instructions...
This is the heart of your skill - clear, actionable steps.
5

Examples

## Examples

### Example 1: [Use Case]

\```javascript
// Example code
\```

### Example 2: [Another Use Case]

\```javascript
// More code
\```
Examples show the AI exactly what good output looks like.
6

Best Practices

## Best Practices

- ✅ Do this
- ✅ Also do this
- ❌ Don't do this
- ❌ Avoid this

​
Writing Effective Instructions

​
Use Clear, Direct Language

You might want to consider possibly checking if the user has authentication.

​
Use Action Verbs

The file should be created...

​
Be Specific

Set up the database properly.

​
Optional Components

​
Scripts Directory

If your skill needs helper scripts: 
scripts/
├── setup.sh          ← Setup automation
├── validate.py       ← Validation tools
└── generate.js       ← Code generators
Reference them in SKILL.md: 
Run the setup script:
\```bash
bash scripts/setup.sh
\```

​
Examples Directory

Real-world examples that demonstrate the skill: 
examples/
├── basic-usage.js
├── advanced-pattern.ts
└── full-implementation/
    ├── index.js
    └── config.json

​
Templates Directory

Reusable code templates: 
templates/
├── component.tsx
├── test.spec.ts
└── config.json

​
References Directory

External documentation or API references: 
references/
├── api-docs.md
├── best-practices.md
└── troubleshooting.md

​
Skill Size Guidelines

  • Frontmatter: name + description
  • Content: 100-200 words
  • Sections: Overview + Instructions
  • Frontmatter: name + description
  • Content: 300-800 words
  • Sections: Overview + When to Use + Instructions + Examples
  • Frontmatter: name + description + optional fields
  • Content: 800-2000 words
  • Sections: All recommended sections
  • Extras: Scripts, examples, templates
Rule of thumb: Start small, expand based on feedback

​
Quality Checklist

Before finalizing your skill:

​
Content Quality

  • Instructions are clear and actionable
  • Examples are realistic and helpful
  • No typos or grammar errors
  • Technical accuracy verified

​
Structure

  • Frontmatter is valid YAML
  • Name matches folder name
  • Sections are logically organized
  • Headings follow hierarchy (H1 → H2 → H3)

​
Completeness

  • Overview explains the “why”
  • Instructions explain the “how”
  • Examples show the “what”
  • Edge cases are addressed

​
Usability

  • A beginner could follow this
  • An expert would find it useful
  • The AI can parse it correctly
  • It solves a real problem

​
Pro Tips

  1. Start with the “When to Use” section - This clarifies the skill’s purpose
  2. Write examples first - They help you understand what you’re teaching
  3. Test with an AI - See if it actually works before submitting
  4. Get feedback - Ask others to review your skill
  5. Iterate - Skills improve over time based on usage

Build docs developers (and LLMs) love

Get started for freeTalk to us