Technical requirements

File structure

your-skill-name/
├── SKILL.md          # Required - main skill file
├── scripts/          # Optional - executable code
│   ├── process_data.py # Example
│   └── validate.sh # Example
├── references/       # Optional - documentation
│   ├── api-guide.md # Example
│   └── examples/ # Example
└── assets/           # Optional - templates, etc.
    └── report-template.md # Example

Critical rules

SKILL.md naming:

• • Must be exactly SKILL.md (case-sensitive)
• • No variations accepted ( SKILL.MD , skill.md , etc.)

Skill folder naming:

• • Use kebab-case: notion-project-setup ✔
• • No spaces: Notion Project Setup ✘
• • No underscores: notion_project_setup ✘
• • No capitals: NotionProjectSetup ✘

No README.md:

• • Don't include README.md inside your skill folder
• • All documentation goes in SKILL.md or references/
• • Note: when distributing via GitHub, you'll still want a repo-level README for human users — see Distribution and Sharing.

YAML frontmatter: The most important part

The YAML frontmatter is how Claude decides whether to load your skill. Get this right.

Minimal required format

---
name: your-skill-name
description: What it does. Use when user asks to [specific phrases].
---

That's all you need to start.

Field requirements

name (required):

• • kebab-case only
• • No spaces or capitals
• • Should match folder name

description (required):

• • MUST include BOTH:
  • – What the skill does
  • – When to use it (trigger conditions)
• • Under 1024 characters
• • No XML tags (< or >)
• • Include specific tasks users might say
• • Mention file types if relevant