Skill Format

The SKILL.md format specification

Overview

Skills are markdown files with YAML frontmatter. Each skill lives in its own directory containing a single SKILL.md file. The frontmatter provides metadata while the markdown body contains the instructions for the AI agent.

Frontmatter

The frontmatter is a YAML block at the top of the file, delimited by ---.

Required Fields

FieldTypeDescription
namestringUnique identifier for the skill. Max 256 characters.
descriptionstringBrief one-line description. Max 4096 characters.

Optional Fields

FieldTypeDescription
versionstringSemantic version (e.g., "1.0.0")
authorstringSkill author name
tagsstring[]Tags for categorization and search
agentsstring[]Compatible agents (e.g., ["claude", "cursor"])
allowed-toolsstring | string[]Tools the skill needs (e.g., "Read, Edit" or ["Read", "Edit"])

Content Body

The content body is standard markdown. It contains the instructions, examples, and guidelines that the AI agent will follow. Use headers to organize sections and code blocks for examples.

Be specific in your instructions. Include concrete examples, before/after code snippets, and clear guidelines. The more specific your skill, the better the agent will perform.

Complete Example

my-skill/SKILL.md
---
name: code-review
description: Automated code review with best practices
version: 1.0.0
author: Your Name
tags:
  - review
  - quality
  - best-practices
agents:
  - claude
  - cursor
---

# Code Review

When reviewing code, follow these guidelines:

## Checklist
- Check for security vulnerabilities
- Verify error handling
- Ensure consistent naming conventions
- Look for performance issues

## Examples

### Good
```typescript
function getUser(id: string): Promise<User | null> {
  // Handle not found case
}
```

### Avoid
```typescript
function getUser(id: any) {
  // No type safety, no error handling
}
```
RepositoriesCreating Skills