Format Reference

Understanding the SKILL.md format helps you write higher-quality, more easily triggered Skills. This page explains how Skills work and provides writing tips.

How Skills Work

Progressive Disclosure

Skills use a three-level loading system for efficient context management, ensuring Claude can respond quickly while accessing deep knowledge when needed.

┌─────────────────────────────────────────────────────────┐
│  Level 1: Metadata (Always in context)                  │
│  ├── name + description (~100 words)                    │
│  └── Used to determine whether to trigger Skill         │
├─────────────────────────────────────────────────────────┤
│  Level 2: SKILL.md Body (When Skill triggers)           │
│  ├── Core instructions (under 5k words)                 │
│  └── Procedural knowledge and workflows                 │
├─────────────────────────────────────────────────────────┤
│  Level 3: Bundled Resources (Loaded as needed)          │
│  ├── scripts/ - Executable code                         │
│  ├── references/ - Detailed documentation               │
│  └── assets/ - Templates, images, etc.                  │
└─────────────────────────────────────────────────────────┘

Benefits of this design:

Level	When Loaded	Context Usage	Content Type
Metadata	Always	~100 words	Name, trigger description
SKILL.md body	On trigger	Under 5k words	Core instructions
Bundled resources	As needed	Unlimited	Detailed docs, scripts

Triggering Mechanism

Claude determines whether to trigger a Skill based on the description field:

User sends message
Claude analyzes message content, matching against all enabled Skills' descriptions
On match, loads SKILL.md body
During task execution, loads references/scripts/assets as needed

Skill Directory Structure

Each Skill consists of a required SKILL.md file and optional resource directories:

skill-name/
├── SKILL.md              # Required: Core instruction file
├── references/           # Optional: Detailed reference docs
│   ├── patterns.md
│   └── api-docs.md
├── scripts/              # Optional: Executable scripts
│   ├── validate.py
│   └── generate.sh
└── assets/               # Optional: Templates and assets
    ├── template.html
    └── logo.png

Directory Purposes

Directory	Purpose	When to Use
`references/`	Detailed docs, loaded into context as needed	When extensive reference material is needed
`scripts/`	Executable code, can be run directly	When deterministic operations are needed
`assets/`	Templates and assets, used in output	When reusable templates are needed

SKILL.md Format

SKILL.md files use YAML frontmatter for metadata and Markdown for the body.

Basic Structure

---
name: my-skill
description: This skill should be used when the user asks to 
  "specific phrase 1", "specific phrase 2", or needs help with 
  specific task type.
---

# Skill Title

Brief description of what this Skill does and when to use it.

## Core Guidelines

Detailed instructions and knowledge...

## Usage

Specific usage steps...

## Resource References

If there are references/scripts/assets, explain how to use them here.

Required Fields

Field	Description	Limit
`name`	Skill identifier, used for display and reference	Max 64 characters
`description`	Functionality and trigger conditions	Max 200 characters

Writing Tips

Writing Effective Descriptions

The description determines when a Skill triggers — it's the most critical field.

✅ Good Example:

description: This skill should be used when the user asks to 
  "create a dashboard", "build a landing page", "design a form", 
  or needs help with frontend development using React or Vue.

Key Elements:

Use third-person: "This skill should be used when..."
Include specific trigger phrases (in quotes)
More specific = more accurate triggering

❌ Bad Example:

description: Helps with frontend stuff.

Problems:

Too vague, hard to trigger accurately
No specific trigger phrases
Not third-person

Writing the SKILL.md Body

The body is the Skill's core content — specific instructions and knowledge for Claude.

Writing Style:

Use imperative form (verb-first)
Direct, clear, actionable
Avoid "you should...", use "Do X" or "X should be done"

✅ Correct:

Parse the configuration file.
Validate the input before processing.
Use the grep tool to search for patterns.

❌ Incorrect:

You should parse the configuration file.
You need to validate the input.
Claude can use the grep tool.

Content Organization:

Keep it lean — ideally 1,500-2,000 words
Core content in SKILL.md
Detailed content in references/ directory

Using Resource Files

When to use references/:

Detailed API documentation
Complete pattern references
Advanced technical guides
Edge case handling

Reference in SKILL.md:

## Detailed Reference

For complete API documentation, see `references/api-docs.md`.

When to use scripts/:

Operations requiring deterministic execution
Automation for repetitive tasks
Validation and check scripts

When to use assets/:

Project templates
Configuration file templates
Images, icon resources

Example Structures

Simple Skill

Contains only core instructions, suitable for coding standards, writing styles, etc.

coding-style/
└── SKILL.md

SKILL.md Content Example:

---
name: coding-style
description: This skill should be used when the user asks about 
  "code style", "naming conventions", "best practices" for 
  TypeScript or JavaScript development.
---

# Code Style Guide

## Naming Conventions

- Variables use camelCase
- Constants use UPPER_SNAKE_CASE
- Class names use PascalCase

## File Organization

- Each file exports only one main thing
- Related utility functions go in the same directory

...

Standard Skill

Includes reference documentation, suitable for scenarios needing detailed knowledge.

api-integration/
├── SKILL.md
└── references/
    ├── endpoints.md
    └── error-codes.md

Complete Skill

Includes all resource types, suitable for complex domains.

project-generator/
├── SKILL.md
├── references/
│   ├── architecture.md
│   └── best-practices.md
├── scripts/
│   └── validate-structure.py
└── assets/
    ├── template/
    │   ├── src/
    │   └── package.json
    └── config-templates/

Validation Checklist

After creating a Skill, verify these points:

Skill Validation Checklist

SKILL.md has valid YAML frontmatter
name and description fields exist and are valid
Description uses third-person and includes trigger phrases
Body uses imperative form
SKILL.md is under 3,000 words
All referenced files exist
references/scripts/assets are well-organized