SKILL.md Format Specification

Relevant source files

This document defines the required structure and content of SKILL.md files, which serve as the entry point for all skills in the anthropics/skills repository. The specification covers YAML frontmatter fields, Markdown body requirements, naming conventions, and the validation rules enforced by quick_validate.py.

For information about how skills are discovered and loaded by Claude, see page 2.1. For guidance on creating new skills using this format, see page 5.1. For running validation, see page 5.2.

Sources: skills/skill-creator/scripts/quick_validate.py1-103 README.md61-88

File Structure Overview

Every skill must be organized as a folder containing a SKILL.md file as its entry point. The file combines structured metadata (YAML frontmatter) with freeform instructions (Markdown body).

Minimal Skill Structure:

my-skill/
  - SKILL.md

Complex Skill Structure:

algorithmic-art/
  - SKILL.md
  - generator_template.js
  - viewer.html
  - philosophy/

Sources: README.md61-88 skills/skill-creator/scripts/quick_validate.py12-94

YAML Frontmatter Specification

The YAML frontmatter must appear at the very beginning of SKILL.md, delimited by --- markers. It contains structured metadata that enables skill discovery and execution.

The complete set of allowed top-level frontmatter keys is defined in quick_validate.py as ALLOWED_PROPERTIES:

{'name', 'description', 'license', 'allowed-tools', 'metadata', 'compatibility'}

Any key outside this set causes validation to fail. skills/skill-creator/scripts/quick_validate.py42-50

Required Fields

Field	Type	Constraints	Purpose
`name`	string	kebab-case (`[a-z0-9-]+`); no leading, trailing, or consecutive hyphens; max 64 characters	Unique identifier for the skill
`description`	string	No angle brackets (`<` or `>`); max 1024 characters	Describes what the skill does and when Claude should use it

Field Details:

name

Format: kebab-case (e.g., algorithmic-art, brand-guidelines, pdf)
Character set: lowercase letters, digits, hyphens only — validated by regex ^[a-z0-9-]+$ skills/skill-creator/scripts/quick_validate.py65
Cannot start or end with a hyphen, and cannot contain consecutive hyphens (--) skills/skill-creator/scripts/quick_validate.py67
Maximum length: 64 characters skills/skill-creator/scripts/quick_validate.py69-71
Used for: Skill identification, marketplace lookups, user invocation

description

Purpose: Drives Claude's trigger matching — Claude reads the description to decide whether to load the skill for a given user request
Cannot contain angle brackets (< or >) skills/skill-creator/scripts/quick_validate.py80-81
Maximum length: 1024 characters skills/skill-creator/scripts/quick_validate.py83-84
Best practice: Include both what the skill does and when it should be activated

Sources: skills/skill-creator/scripts/quick_validate.py52-84

Optional Fields

Field	Type	Constraints	Purpose
`license`	string	None	License applied to the skill
`allowed-tools`	list of strings	None	Pre-approved tools that can be executed
`metadata`	map (string → string)	None	Client-specific additional properties
`compatibility`	string	Max 500 characters	Platform or version compatibility notes

Field Details:

license

Recommended format: Short SPDX identifier (e.g., Apache-2.0) or reference to a bundled license file
Purpose: Clarifies usage rights and redistribution terms
Example values: Apache-2.0, MIT

allowed-tools

Type: Array of tool identifier strings
Support: Currently only supported in Claude Code
Purpose: Security constraint that limits which tools the skill can invoke
Example: ["bash", "str_replace_editor"]
Behavior: When set, Claude restricts its tool use to the listed tools while the skill is active

metadata

Type: Map from string keys to string values
Purpose: Extensibility mechanism for client-specific properties
Key naming: Use reasonably unique key names to avoid conflicts with future spec additions
Example use cases: Custom categorization, version tracking, client-specific configuration

compatibility

Type: string
Maximum length: 500 characters skills/skill-creator/scripts/quick_validate.py90-92
Purpose: Documents platform or version compatibility requirements for the skill

Sources: skills/skill-creator/scripts/quick_validate.py42-44 skills/skill-creator/scripts/quick_validate.py86-92

Markdown Body Specification

The Markdown body follows the YAML frontmatter and has no structural restrictions. It contains the actual instructions, examples, and guidelines that Claude uses when executing the skill.

Content Freedom:

No mandatory sections or structure
Any valid Markdown syntax supported
Skills can organize content based on their specific needs
Common patterns include: overviews, instructions, examples, guidelines, resource references

Design Principle: The unrestricted Markdown body allows skill authors to provide context, instructions, and examples in whatever format best suits the skill's domain and complexity.

Sources: README.md72-83

Complete Format Schema

SKILL.md field structure and validation sources

Sources: skills/skill-creator/scripts/quick_validate.py42-92 README.md61-88

Validation Rules (quick_validate.py)

quick_validate.py is the authoritative validator for SKILL.md files. It is located at skills/skill-creator/scripts/quick_validate.py1-103 The following table lists every check it performs, in the order they are evaluated.

Validation gate ordering in validate_skill()

Gate	Condition Checked	Error Message
1. File existence	`SKILL.md` present in skill directory	`SKILL.md not found`
2. Frontmatter marker	File starts with `---`	`No YAML frontmatter found`
3. Frontmatter format	Regex `^---\n(.*?)\n---` matches	`Invalid frontmatter format`
4. YAML validity	`yaml.safe_load()` succeeds and returns a dict	`Invalid YAML in frontmatter: ...`
5. Allowed keys	All keys are in `ALLOWED_PROPERTIES`	`Unexpected key(s) in SKILL.md frontmatter: ...`
6. `name` present	`name` key exists	`Missing 'name' in frontmatter`
7. `description` present	`description` key exists	`Missing 'description' in frontmatter`
8a. `name` type	`name` is a string	`Name must be a string, got ...`
8b. `name` format	Matches `^[a-z0-9-]+$`	`Name '...' should be kebab-case`
8c. `name` hyphens	No leading/trailing/consecutive hyphens	`Name '...' cannot start/end with hyphen...`
8d. `name` length	`len(name) <= 64`	`Name is too long (N characters). Maximum is 64 characters.`
9a. `description` type	`description` is a string	`Description must be a string, got ...`
9b. `description` content	No `<` or `>` characters	`Description cannot contain angle brackets (< or >)`
9c. `description` length	`len(description) <= 1024`	`Description is too long (N characters). Maximum is 1024 characters.`
10a. `compatibility` type	If present, is a string	`Compatibility must be a string, got ...`
10b. `compatibility` length	If present, `len(compatibility) <= 500`	`Compatibility is too long (N characters). Maximum is 500 characters.`

Sources: skills/skill-creator/scripts/quick_validate.py12-94

Running the Validator

python quick_validate.py <skill_directory>

Exit code 0: skill is valid
Exit code 1: validation failed; error message printed to stdout

Sources: skills/skill-creator/scripts/quick_validate.py96-103

Example SKILL.md Files

Minimal Example

The template/ directory demonstrates the absolute minimum required structure (see README.md63-82):

---
name: my-skill-name
description: A clear description of what this skill does and when to use it
---

# My Skill Name

[Add your instructions here that Claude will follow when this skill is active]

## Examples
- Example usage 1
- Example usage 2

## Guidelines
- Guideline 1
- Guideline 2

Complete Example with All Optional Fields

---
name: algorithmic-art
description: Create philosophical generative art using p5.js. Use this skill when the user
  wants to create interactive algorithmic art that expresses a conceptual theme
  through emergent visual patterns.
license: Apache-2.0
allowed-tools:
  - bash
  - str_replace_editor
metadata:
  category: creative
  complexity: advanced
compatibility: Claude Code 1.0+
---

# Algorithmic Art Skill

Instructions for creating philosophy-driven generative art...

Sources: README.md63-82

Integration Points

The SKILL.md format integrates with other components of the skills system:

SKILL.md runtime integration — from file to Claude execution

Related Systems:

Marketplace registration: See Marketplace and Plugin System
Skill discovery and loading: See Skills System Architecture
Practical skill creation: See Creating a New Skill

Sources: agent_skills_spec.md1-56

SKILL.md Format Specification

Relevant source files

For information about how skills are discovered and loaded by Claude, see page 2.1. For guidance on creating new skills using this format, see page 5.1. For running validation, see page 5.2.

Sources: skills/skill-creator/scripts/quick_validate.py1-103 README.md61-88

File Structure Overview

Every skill must be organized as a folder containing a SKILL.md file as its entry point. The file combines structured metadata (YAML frontmatter) with freeform instructions (Markdown body).

Minimal Skill Structure:

my-skill/
  - SKILL.md

Complex Skill Structure:

algorithmic-art/
  - SKILL.md
  - generator_template.js
  - viewer.html
  - philosophy/

Sources: README.md61-88 skills/skill-creator/scripts/quick_validate.py12-94

YAML Frontmatter Specification

The YAML frontmatter must appear at the very beginning of SKILL.md, delimited by --- markers. It contains structured metadata that enables skill discovery and execution.

The complete set of allowed top-level frontmatter keys is defined in quick_validate.py as ALLOWED_PROPERTIES:

{'name', 'description', 'license', 'allowed-tools', 'metadata', 'compatibility'}

Any key outside this set causes validation to fail. skills/skill-creator/scripts/quick_validate.py42-50

Required Fields

Field	Type	Constraints	Purpose
`name`	string	kebab-case (`[a-z0-9-]+`); no leading, trailing, or consecutive hyphens; max 64 characters	Unique identifier for the skill
`description`	string	No angle brackets (`<` or `>`); max 1024 characters	Describes what the skill does and when Claude should use it

Field Details:

name

Format: kebab-case (e.g., algorithmic-art, brand-guidelines, pdf)
Character set: lowercase letters, digits, hyphens only — validated by regex ^[a-z0-9-]+$ skills/skill-creator/scripts/quick_validate.py65
Cannot start or end with a hyphen, and cannot contain consecutive hyphens (--) skills/skill-creator/scripts/quick_validate.py67
Maximum length: 64 characters skills/skill-creator/scripts/quick_validate.py69-71
Used for: Skill identification, marketplace lookups, user invocation

description

Purpose: Drives Claude's trigger matching — Claude reads the description to decide whether to load the skill for a given user request
Cannot contain angle brackets (< or >) skills/skill-creator/scripts/quick_validate.py80-81
Maximum length: 1024 characters skills/skill-creator/scripts/quick_validate.py83-84
Best practice: Include both what the skill does and when it should be activated

Sources: skills/skill-creator/scripts/quick_validate.py52-84

Optional Fields

Field	Type	Constraints	Purpose
`license`	string	None	License applied to the skill
`allowed-tools`	list of strings	None	Pre-approved tools that can be executed
`metadata`	map (string → string)	None	Client-specific additional properties
`compatibility`	string	Max 500 characters	Platform or version compatibility notes

Field Details:

license

Recommended format: Short SPDX identifier (e.g., Apache-2.0) or reference to a bundled license file
Purpose: Clarifies usage rights and redistribution terms
Example values: Apache-2.0, MIT

allowed-tools

Type: Array of tool identifier strings
Support: Currently only supported in Claude Code
Purpose: Security constraint that limits which tools the skill can invoke
Example: ["bash", "str_replace_editor"]
Behavior: When set, Claude restricts its tool use to the listed tools while the skill is active

metadata

Type: Map from string keys to string values
Purpose: Extensibility mechanism for client-specific properties
Key naming: Use reasonably unique key names to avoid conflicts with future spec additions
Example use cases: Custom categorization, version tracking, client-specific configuration

compatibility

Type: string
Maximum length: 500 characters skills/skill-creator/scripts/quick_validate.py90-92
Purpose: Documents platform or version compatibility requirements for the skill

Sources: skills/skill-creator/scripts/quick_validate.py42-44 skills/skill-creator/scripts/quick_validate.py86-92

Markdown Body Specification

The Markdown body follows the YAML frontmatter and has no structural restrictions. It contains the actual instructions, examples, and guidelines that Claude uses when executing the skill.

Content Freedom:

No mandatory sections or structure
Any valid Markdown syntax supported
Skills can organize content based on their specific needs
Common patterns include: overviews, instructions, examples, guidelines, resource references

Design Principle: The unrestricted Markdown body allows skill authors to provide context, instructions, and examples in whatever format best suits the skill's domain and complexity.

Sources: README.md72-83

Complete Format Schema

SKILL.md field structure and validation sources

Sources: skills/skill-creator/scripts/quick_validate.py42-92 README.md61-88

Validation Rules (quick_validate.py)

Validation gate ordering in validate_skill()

Gate	Condition Checked	Error Message
1. File existence	`SKILL.md` present in skill directory	`SKILL.md not found`
2. Frontmatter marker	File starts with `---`	`No YAML frontmatter found`
3. Frontmatter format	Regex `^---\n(.*?)\n---` matches	`Invalid frontmatter format`
4. YAML validity	`yaml.safe_load()` succeeds and returns a dict	`Invalid YAML in frontmatter: ...`
5. Allowed keys	All keys are in `ALLOWED_PROPERTIES`	`Unexpected key(s) in SKILL.md frontmatter: ...`
6. `name` present	`name` key exists	`Missing 'name' in frontmatter`
7. `description` present	`description` key exists	`Missing 'description' in frontmatter`
8a. `name` type	`name` is a string	`Name must be a string, got ...`
8b. `name` format	Matches `^[a-z0-9-]+$`	`Name '...' should be kebab-case`
8c. `name` hyphens	No leading/trailing/consecutive hyphens	`Name '...' cannot start/end with hyphen...`
8d. `name` length	`len(name) <= 64`	`Name is too long (N characters). Maximum is 64 characters.`
9a. `description` type	`description` is a string	`Description must be a string, got ...`
9b. `description` content	No `<` or `>` characters	`Description cannot contain angle brackets (< or >)`
9c. `description` length	`len(description) <= 1024`	`Description is too long (N characters). Maximum is 1024 characters.`
10a. `compatibility` type	If present, is a string	`Compatibility must be a string, got ...`
10b. `compatibility` length	If present, `len(compatibility) <= 500`	`Compatibility is too long (N characters). Maximum is 500 characters.`

Sources: skills/skill-creator/scripts/quick_validate.py12-94

Running the Validator

python quick_validate.py <skill_directory>

Exit code 0: skill is valid
Exit code 1: validation failed; error message printed to stdout

Sources: skills/skill-creator/scripts/quick_validate.py96-103

Example SKILL.md Files

Minimal Example

The template/ directory demonstrates the absolute minimum required structure (see README.md63-82):

---
name: my-skill-name
description: A clear description of what this skill does and when to use it
---

# My Skill Name

[Add your instructions here that Claude will follow when this skill is active]

## Examples
- Example usage 1
- Example usage 2

## Guidelines
- Guideline 1
- Guideline 2

Complete Example with All Optional Fields

---
name: algorithmic-art
description: Create philosophical generative art using p5.js. Use this skill when the user
  wants to create interactive algorithmic art that expresses a conceptual theme
  through emergent visual patterns.
license: Apache-2.0
allowed-tools:
  - bash
  - str_replace_editor
metadata:
  category: creative
  complexity: advanced
compatibility: Claude Code 1.0+
---

# Algorithmic Art Skill

Instructions for creating philosophy-driven generative art...

Sources: README.md63-82

Integration Points

The SKILL.md format integrates with other components of the skills system:

SKILL.md runtime integration — from file to Claude execution

Related Systems:

Marketplace registration: See Marketplace and Plugin System
Skill discovery and loading: See Skills System Architecture
Practical skill creation: See Creating a New Skill

Sources: agent_skills_spec.md1-56

SKILL.md Format Specification

File Structure Overview

YAML Frontmatter Specification

Required Fields

Optional Fields

Markdown Body Specification

Complete Format Schema

Validation Rules (quick_validate.py)

Running the Validator

Example SKILL.md Files

Minimal Example

Complete Example with All Optional Fields

Integration Points

On this page

SKILL.md Format Specification

File Structure Overview

YAML Frontmatter Specification

Required Fields

Optional Fields

Markdown Body Specification

Complete Format Schema

Validation Rules (quick_validate.py)

Running the Validator

Example SKILL.md Files

Minimal Example

Complete Example with All Optional Fields

Integration Points

On this page