SKILL.md Format and Structure

Complete reference for the SKILL.md file format, including YAML frontmatter, markdown body, and best practices for writing effective skill instructions.

The SKILL.md file is the core of every skill. It contains YAML frontmatter with metadata and a markdown body with instructions that the AI agent will follow when the skill is active.

File Structure

A SKILL.md file has two parts:

1. YAML Frontmatter - Metadata enclosed in --- delimiters
2. Markdown Body - Instructions, examples, and guidelines

---
name: my-skill-name
description: A clear description of what this skill does and when to use it
compatibility: [optional] Required tools or dependencies
---

# Skill Instructions

[Markdown content with instructions, examples, and guidelines]

YAML Frontmatter

Required Fields

name · string · required

Unique identifier for the skill. Use lowercase letters, numbers, and hyphens. No spaces.

name: mcp-builder

description · string · required

Complete description of what the skill does and when to use it. This is the primary triggering mechanism - include both capabilities and specific contexts for when to use the skill.

The description should be “pushy” to combat Claude’s tendency to under-trigger skills. Include:

• What the skill does
• When to use it (specific contexts, keywords, scenarios)
• What it enables

description: Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).

Optional Fields

compatibility · string | array

Required tools, dependencies, or platform requirements. Rarely needed.

compatibility: Requires WebFetch tool for loading API documentation

license · string

License information or reference to a LICENSE.txt file in the skill folder.

license: Apache 2.0
# or
license: Complete terms in LICENSE.txt

Markdown Body

The markdown body contains the instructions the AI agent will follow. This is where you teach the agent how to accomplish the skill’s task.

Structure Guidelines

Keep it Under 500 Lines

The SKILL.md body should ideally be under 500 lines. If approaching this limit:

• Move detailed documentation to reference files
• Add clear pointers about when to read each reference
• Use progressive disclosure to load details on demand

Example:

## Implementation

For language-specific implementation details:
- [⚡ TypeScript Guide](./reference/node_mcp_server.md)
- [🐍 Python Guide](./reference/python_mcp_server.md)

Explain the Why, Not Just the What

Modern AI agents benefit from understanding why things are important, not just what to do.

Good:

Clear, descriptive tool names help agents find the right tools quickly.
Use consistent prefixes (e.g., `github_create_issue`, `github_list_repos`)
and action-oriented naming.

Less effective:

ALWAYS use descriptive tool names.
NEVER use abbreviations.

Use Imperative Form

Prefer imperative instructions for clarity:

## Report Structure

ALWAYS use this exact template:

# [Title]
## Executive Summary  
## Key Findings
## Recommendations

Include Examples

Examples help agents understand expected input/output formats:

## Commit Message Format

**Example 1:**
Input: Added user authentication with JWT tokens
Output: feat(auth): implement JWT-based authentication

**Example 2:**
Input: Fixed crash when user logs out
Output: fix(auth): prevent crash on logout

Reference Bundled Resources Clearly

When referencing bundled resources, be explicit about when and how to use them:

## API Documentation

For framework-specific implementation:
- **TypeScript**: Read [reference/node_mcp_server.md](./reference/node_mcp_server.md)
- **Python**: Read [reference/python_mcp_server.md](./reference/python_mcp_server.md)

## Validation

Use the provided validation script:
```bash
python scripts/validate_output.py <output-file>

Common Patterns

Defining Output Formats

## Output Format

Generate a JSON file with this structure:

```json
{
  "name": "string",
  "version": "string",
  "dependencies": []
}

Ensure all fields are present and properly formatted.

#### Multi-Step Workflows

```markdown
## Process

### Phase 1: Research and Planning

1. Review the API documentation
2. Identify key endpoints to implement
3. Plan authentication approach

### Phase 2: Implementation

1. Set up project structure
2. Implement core infrastructure
3. Implement individual tools

### Phase 3: Testing

1. Create test cases
2. Run validation scripts
3. Review results

Conditional Instructions

## Platform-Specific Instructions

**For TypeScript:**
- Use Zod for input validation
- Use the MCP TypeScript SDK
- Follow the TypeScript guide in references/

**For Python:**
- Use Pydantic for input validation
- Use the MCP Python SDK
- Follow the Python guide in references/

Error Handling

## Error Handling

When errors occur:

1. Read the error message carefully
2. Check if the issue is in the bundled documentation
3. Provide actionable error messages to the user
4. Suggest specific next steps

Common errors:
- **Authentication failed**: Check API credentials in environment variables
- **Rate limit exceeded**: Wait 60 seconds and retry
- **Invalid input**: Validate against the schema in references/schema.md

Writing Style

Theory of Mind

Write instructions with an understanding of how AI agents think and work:

• Agents benefit from context and reasoning
• Agents can generalize from principles
• Agents work better with “why” than rigid “always/never” rules
• Agents can compose solutions from flexible guidelines

Generality vs. Specificity

Balance general principles with specific examples:

## Tool Naming

Use clear, action-oriented names that describe what the tool does.
Consistent prefixes help with discoverability.

**Examples:**
- `github_create_issue` - Creates a new GitHub issue
- `github_list_repos` - Lists repositories
- `github_update_pr` - Updates a pull request

Notice the pattern: `service_action_resource`

Avoiding Over-Specification

If you find yourself writing ALWAYS or NEVER in all caps frequently, consider whether you can explain the reasoning instead. Rigid structures work less well than flexible guidelines grounded in understanding.

Instead of:

You MUST ALWAYS create a validation script.
You MUST NEVER skip error handling.
ALWAYS use the exact template provided.

Try:

Validation scripts catch errors early and can be reused across runs.
Write a validation script for any objectively verifiable requirements.

Error handling helps agents recover gracefully and provides clear feedback.
Include specific error messages and suggested next steps.

Complete Example

Here’s a complete SKILL.md example:

---
name: commit-message-formatter
description: Format git commit messages following conventional commits specification. Use when creating commits, formatting commit messages, or standardizing repository commit history.
---

# Commit Message Formatter

Format git commit messages following the Conventional Commits specification.

## Format

Use this structure:

<type>(<scope>): <description>

[optional body]

[optional footer]

## Types

- **feat**: New feature
- **fix**: Bug fix  
- **docs**: Documentation only
- **style**: Formatting, missing semicolons, etc.
- **refactor**: Code change that neither fixes a bug nor adds a feature
- **test**: Adding missing tests
- **chore**: Changes to build process or auxiliary tools

## Examples

**Example 1:**
Input: Added user authentication with JWT tokens
Output: `feat(auth): implement JWT-based authentication`

**Example 2:**
Input: Fixed crash when user logs out  
Output: `fix(auth): prevent crash on logout`

**Example 3:**
Input: Updated README with API documentation
Output: `docs(api): add endpoint documentation to README`

## Guidelines

- Keep description under 72 characters
- Use present tense ("add" not "added")
- Don't capitalize first letter of description
- No period at the end of description
- Scope is optional but recommended

Next Steps

Metadata Schema

Detailed schema reference for YAML frontmatter

Loading System

How the progressive disclosure system works