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

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:

1. Metadata for discovery and compatibility
2. Permissions for security
3. Configuration for behavior
4. 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.