The SKILL.md Format: Complete Specification and Examples
Complete specification for the SKILL.md format including all fields, best practices, and examples for different skill types in Claude Code.
The SKILL.md Format: Complete Specification and Examples
The SKILL.md file is the heart of every Claude Code skill. It defines what the skill does, how it behaves, and what resources it needs. This guide provides the complete specification with examples for every field and skill type.
Format Overview
SKILL.md uses a combination of YAML frontmatter and Markdown content:
---
# YAML frontmatter (metadata and configuration)
name: my-skill
version: 1.0.0
description: A brief description
---
# Markdown content (system prompt and documentation)
Your system prompt and instructions go here...
Complete Field Reference
Required Fields
These fields must be present in every SKILL.md:
---
# Unique identifier for the skill
name: code-review
# Semantic version (MAJOR.MINOR.PATCH)
version: 1.2.3
# Brief description (max 160 characters for SEO)
description: Automated code review with security and performance analysis
---
Identity Fields
---
# Display name (can include spaces, shown in UI)
displayName: "Code Review Assistant"
# Author information
author: "Jane Developer"
authorEmail: "jane@example.com"
authorUrl: "https://github.com/janedeveloper"
# License (SPDX identifier recommended)
license: "MIT"
# Repository URL
repository: "https://github.com/janedeveloper/code-review-skill"
# Homepage URL
homepage: "https://skills.example.com/code-review"
# Keywords for discovery (max 10)
keywords:
- code-review
- security
- performance
- best-practices
---
Categorization Fields
---
# Primary category
category: development
# Subcategory for more specific classification
subcategory: code-quality
# Skill type (command, agent, hook, or mcp)
type: command
# Difficulty level for users
difficulty: intermediate # beginner, intermediate, advanced
# Target audience
audience:
- developers
- tech-leads
- security-engineers
---
Compatibility Fields
---
# Minimum Claude Code version required
minClaudeVersion: "1.0.0"
# Maximum Claude Code version (if deprecated)
maxClaudeVersion: "2.0.0"
# Platform compatibility
platforms:
- macos
- linux
- windows
# Language requirements
languages:
- javascript
- typescript
- python
# Framework compatibility (optional)
frameworks:
- react
- nextjs
- express
---
Permission Fields
---
# Filesystem access configuration
filesystem:
read:
- "${PROJECT_ROOT}/**/*"
- "${HOME}/.config/skill-name/*"
write:
- "${PROJECT_ROOT}/reports/*"
- "${TEMP}/*"
deny:
- "**/.env*"
- "**/*secret*"
- "**/*.key"
- "**/*.pem"
# Network access configuration
network:
allowedHosts:
- "api.github.com"
- "registry.npmjs.org"
deniedHosts:
- "*" # Deny all by default, then allow specific hosts
# Tool access configuration
tools:
allowed:
- read_file
- write_file
- grep
- glob
- bash
denied:
- mcp # Deny specific tools if needed
bashCommands:
allowed:
- "npm test"
- "npm run lint"
- "git status"
- "git diff"
denied:
- "rm -rf"
- "sudo"
---
Input/Output Fields
---
# Input configuration
input:
# Arguments the skill accepts
arguments:
- name: files
type: string[]
description: Files to review
required: true
- name: strict
type: boolean
description: Enable strict mode
required: false
default: false
- name: format
type: string
description: Output format
required: false
default: "markdown"
enum: ["markdown", "json", "html"]
# Context the skill needs
context:
requiresProject: true
requiresGit: false
requiresPackageJson: false
# Output configuration
output:
# Primary output format
format: markdown # text, markdown, json, code
# Structured output schema (for JSON output)
schema:
type: object
properties:
issues:
type: array
items:
type: object
properties:
severity:
type: string
enum: [critical, high, medium, low]
file:
type: string
line:
type: number
message:
type: string
---
Behavior Fields
---
# Execution behavior
behavior:
# Maximum execution time in seconds
timeout: 120
# Retry configuration
retry:
maxAttempts: 3
backoffMs: 1000
# Caching configuration
cache:
enabled: true
ttlSeconds: 3600
keyFields:
- files
- strict
# Interactive mode settings
interactive:
confirmDestructive: true
showProgress: true
# AI model preferences
model:
preferred: "claude-sonnet-4-20250514"
fallback: "claude-3-5-sonnet-20241022"
temperature: 0.3
maxTokens: 4096
---
Trigger Fields (for Hooks)
---
# Hook trigger configuration
triggers:
# Event types that activate this hook
events:
- PreToolUse
- PostToolUse
# Filter conditions
filters:
# Only trigger for specific tools
tools:
- bash
- write_file
# Only trigger for specific file patterns
files:
- "**/*.ts"
- "**/*.tsx"
# Priority (higher runs first)
priority: 100
---
Dependencies Field
---
# External dependencies
dependencies:
# NPM packages required
npm:
- typescript@^5.0.0
- eslint@^8.0.0
# Python packages required
pip:
- black>=23.0.0
- mypy>=1.0.0
# System commands required
commands:
- git
- node
- npm
# Other skills required
skills:
- file-utils@^1.0.0
---
Complete Examples
Command Skill Example
---
name: code-review
displayName: "Code Review Assistant"
version: 2.1.0
description: Comprehensive code review with security, performance, and style analysis
author: "Jane Developer"
license: "MIT"
repository: "https://github.com/janedeveloper/code-review-skill"
category: development
subcategory: code-quality
type: command
difficulty: intermediate
keywords:
- code-review
- security
- performance
- linting
minClaudeVersion: "1.0.0"
platforms:
- macos
- linux
- windows
filesystem:
read:
- "${PROJECT_ROOT}/**/*"
write:
- "${PROJECT_ROOT}/review-reports/*"
deny:
- "**/.env*"
- "**/node_modules/**"
network:
allowedHosts: []
tools:
allowed:
- read_file
- grep
- glob
denied:
- bash
input:
arguments:
- name: files
type: string[]
description: Files or directories to review
required: false
default: ["."]
- name: focus
type: string
description: Focus area for review
required: false
enum: ["security", "performance", "style", "all"]
default: "all"
- name: strict
type: boolean
description: Enable strict mode (more findings)
required: false
default: false
output:
format: markdown
schema:
type: object
properties:
summary:
type: string
issues:
type: array
score:
type: number
behavior:
timeout: 300
cache:
enabled: true
ttlSeconds: 600
---
# Code Review Assistant
You are an expert code reviewer with deep knowledge of software engineering best practices, security vulnerabilities, and performance optimization.
## Your Role
Review code for:
1. **Security Issues**: SQL injection, XSS, authentication flaws, secrets in code
2. **Performance Problems**: N+1 queries, memory leaks, inefficient algorithms
3. **Code Quality**: Readability, maintainability, SOLID principles
4. **Style Violations**: Based on project conventions
## Review Process
1. Read the files provided
2. Analyze each file for issues
3. Categorize issues by severity (critical, high, medium, low)
4. Provide actionable fix suggestions
5. Calculate an overall score (0-100)
## Output Format
Provide your review in this format:
```markdown
## Summary
[Brief overview of findings]
## Issues Found
### Critical
- [Issue description with file:line reference]
- **Fix**: [How to fix it]
### High
...
### Medium
...
### Low
...
## Score: [X]/100
## Recommendations
[Top 3 recommendations for improvement]
Guidelines
- Be specific about locations (file:line)
- Provide code examples for fixes when helpful
- Prioritize critical issues
- Be constructive, not harsh
- Consider project context
When strict mode is enabled:
- Report all potential issues, even minor ones
- Apply stricter security standards
- Flag style inconsistencies
### Agent Skill Example
```markdown
---
name: project-analyzer
displayName: "Project Analyzer Agent"
version: 1.0.0
description: Autonomous agent that analyzes project structure, dependencies, and architecture
author: "Tech Team"
license: "MIT"
category: development
subcategory: analysis
type: agent
difficulty: intermediate
minClaudeVersion: "1.0.0"
filesystem:
read:
- "${PROJECT_ROOT}/**/*"
write:
- "${PROJECT_ROOT}/analysis-reports/*"
network:
allowedHosts:
- "api.github.com"
- "registry.npmjs.org"
tools:
allowed:
- read_file
- write_file
- grep
- glob
- bash
bashCommands:
allowed:
- "npm list"
- "npm outdated"
- "git log"
- "git diff"
input:
arguments:
- name: depth
type: string
description: Analysis depth
enum: ["quick", "standard", "deep"]
default: "standard"
output:
format: markdown
behavior:
timeout: 600
interactive:
showProgress: true
---
# Project Analyzer Agent
You are an autonomous agent that analyzes software projects to understand their structure, dependencies, and architecture.
## Capabilities
You can:
- Explore the file system to understand project structure
- Read and analyze source files
- Check package dependencies and versions
- Examine Git history for context
- Generate comprehensive reports
## Analysis Process
### Quick Analysis
1. Read README and package.json
2. Identify main technologies
3. List top-level structure
4. Report in 2-3 paragraphs
### Standard Analysis
1. All of Quick, plus:
2. Analyze source directory structure
3. Identify architectural patterns
4. Check dependency health
5. Review configuration files
### Deep Analysis
1. All of Standard, plus:
2. Read key source files
3. Map component relationships
4. Analyze code quality indicators
5. Check for security concerns
6. Generate detailed recommendations
## Exploration Strategy
1. Start with project root files (README, package.json, etc.)
2. Use `glob` to find file patterns
3. Use `grep` before reading full files
4. Prioritize main source directories
5. Limit file reads to avoid context overflow
## Output Format
Generate a structured report:
```markdown
# Project Analysis Report
## Overview
- **Name**: [project name]
- **Type**: [web app, library, CLI, etc.]
- **Technologies**: [main stack]
## Structure
[Directory tree with descriptions]
## Architecture
[Patterns identified, data flow]
## Dependencies
[Key dependencies, versions, health]
## Recommendations
[Prioritized list of improvements]
Guidelines
- Be thorough but efficient with file reads
- Use grep to find relevant sections before reading full files
- Track your exploration to avoid redundant reads
- Provide specific, actionable recommendations
### Hook Skill Example
```markdown
---
name: security-guard
displayName: "Security Guard Hook"
version: 1.0.0
description: Pre-commit hook that blocks commits containing secrets or security issues
author: "Security Team"
license: "MIT"
category: security
type: hook
difficulty: beginner
minClaudeVersion: "1.0.0"
triggers:
events:
- PreToolUse
filters:
tools:
- bash
- write_file
priority: 100
filesystem:
read:
- "${PROJECT_ROOT}/**/*"
write: []
behavior:
timeout: 30
---
# Security Guard Hook
You are a security-focused hook that runs before code changes are committed or files are written.
## Purpose
Prevent security issues from entering the codebase by:
1. Detecting hardcoded secrets
2. Identifying security vulnerabilities
3. Blocking dangerous operations
## Detection Rules
### Secrets to Block
- API keys (sk-*, ghp_*, AKIA*, etc.)
- Private keys (-----BEGIN.*PRIVATE KEY-----)
- Passwords in code (password = "...", pwd: "...")
- Connection strings with credentials
- JWT tokens
### Dangerous Patterns
- SQL queries with string concatenation
- Shell commands with user input
- Disabled security features
- Hardcoded credentials
## Response Format
When you detect an issue, respond with:
```json
{
"allowed": false,
"reason": "Detected hardcoded API key",
"details": {
"file": "config.js",
"line": 42,
"pattern": "sk-****",
"severity": "critical"
},
"suggestion": "Use environment variables: process.env.API_KEY"
}
When content is safe:
{
"allowed": true
}
Guidelines
- Be strict about secrets - false positives are acceptable
- Provide specific remediation suggestions
- Include file and line information
- Categorize by severity
### MCP Integration Example
```markdown
---
name: github-integration
displayName: "GitHub Integration"
version: 1.0.0
description: GitHub integration via MCP for issue management and PR operations
author: "Platform Team"
license: "MIT"
category: integration
type: mcp
difficulty: intermediate
minClaudeVersion: "1.0.0"
network:
allowedHosts:
- "api.github.com"
mcp:
server:
command: "npx"
args: ["-y", "@anthropic/mcp-server-github"]
env:
GITHUB_TOKEN: "${GITHUB_TOKEN}"
tools:
- name: create_issue
description: Create a new GitHub issue
- name: list_issues
description: List issues in a repository
- name: create_pr
description: Create a pull request
- name: get_pr
description: Get pull request details
---
# GitHub Integration
This skill provides GitHub integration through the Model Context Protocol (MCP).
## Available Tools
### create_issue
Create a new issue in a GitHub repository.
Parameters:
- `owner`: Repository owner
- `repo`: Repository name
- `title`: Issue title
- `body`: Issue description
- `labels`: Array of label names
### list_issues
List issues in a repository.
Parameters:
- `owner`: Repository owner
- `repo`: Repository name
- `state`: Issue state (open, closed, all)
- `labels`: Filter by labels
### create_pr
Create a new pull request.
Parameters:
- `owner`: Repository owner
- `repo`: Repository name
- `title`: PR title
- `body`: PR description
- `head`: Source branch
- `base`: Target branch
### get_pr
Get details of a pull request.
Parameters:
- `owner`: Repository owner
- `repo`: Repository name
- `number`: PR number
## Usage Examples
"Create an issue for the login bug"
"List all open issues with the 'bug' label"
"Create a PR from feature-branch to main"
"Get details of PR #42"
## Configuration
Requires GITHUB_TOKEN environment variable with appropriate permissions:
- `repo` scope for private repositories
- `public_repo` scope for public repositories
Validation Rules
Required Field Validation
interface SkillValidation {
required: string[];
patterns: Record<string, RegExp>;
ranges: Record<string, { min: number; max: number }>;
}
const VALIDATION_RULES: SkillValidation = {
required: ['name', 'version', 'description'],
patterns: {
name: /^[a-z][a-z0-9-]*$/,
version: /^\d+\.\d+\.\d+$/,
license: /^[A-Z0-9-]+$/,
},
ranges: {
'description.length': { min: 10, max: 160 },
'keywords.length': { min: 0, max: 10 },
'behavior.timeout': { min: 1, max: 3600 },
},
};
Common Validation Errors
| Error | Cause | Fix |
|---|---|---|
| Missing required field | name, version, or description absent | Add the field |
| Invalid name format | Contains uppercase or special chars | Use lowercase with hyphens |
| Invalid version | Not semver format | Use X.Y.Z format |
| Description too long | Over 160 characters | Shorten description |
| Too many keywords | More than 10 keywords | Reduce to top 10 |
Best Practices
1. Keep Prompts Focused
<!-- Good: Focused prompt -->
You are a TypeScript code formatter that ensures consistent style.
Format code according to:
- 2-space indentation
- Semicolons required
- Single quotes for strings
<!-- Bad: Unfocused prompt -->
You are an expert developer who knows everything about code...
2. Be Specific About Permissions
# Good: Minimal permissions
filesystem:
read:
- "${PROJECT_ROOT}/src/**/*.ts"
write:
- "${PROJECT_ROOT}/reports/*"
# Bad: Overly broad permissions
filesystem:
read:
- "**/*"
write:
- "**/*"
3. Include Examples in Prompts
## Examples
Input: "Review auth.ts for security issues"
Output:
```json
{
"issues": [
{
"severity": "high",
"file": "auth.ts",
"line": 23,
"message": "Password compared with timing-unsafe equality"
}
]
}
### 4. Version Thoughtfully
```yaml
# Breaking change: new major version
version: 2.0.0 # Changed output format
# New feature: minor version
version: 1.1.0 # Added new parameter
# Bug fix: patch version
version: 1.0.1 # Fixed parsing error
5. Document Thoroughly
Include in your SKILL.md:
- Clear description of purpose
- All parameters with examples
- Expected output format
- Error handling behavior
- Usage examples
Conclusion
The SKILL.md format provides a powerful way to define Claude Code skills with:
- Metadata for discovery and compatibility
- Permissions for security
- Configuration for behavior
- System prompt for AI instructions
Following this specification ensures your skills are discoverable, secure, and work reliably across different environments.
Ready to build your first skill? Return to our Getting Started Guide for step-by-step instructions.