This page provides a step-by-step tutorial for creating a new skill in the anthropics/skills repository. It covers using the skill template, structuring your SKILL.md file with YAML frontmatter, validating your skill, and registering it for deployment. For comprehensive information about the SKILL.md file format specification, see page 2.2. For marketplace and plugin system details, see page 2.3. For platform-specific deployment (Claude Code, Claude.ai, Claude API), see page 2.4.
Before creating a new skill, ensure you have:
Sources: README.md1-95
The following diagram maps the creation workflow to the actual file system artifacts and tooling involved.
Skill Creation File System and Tooling Map
Sources: README.md61-88 skills/skill-creator/scripts/quick_validate.py1-103
Create a new directory under skills/ with a name that matches your skill's purpose. Use lowercase letters and hyphens for spaces:
skills/
└── my-skill-name/
└── SKILL.md
The folder name should be descriptive and unique within the repository. Convention is to use kebab-case naming.
Sources: README.md16 README.md25
Every skill requires a SKILL.md file at the root of its folder. This file contains both YAML frontmatter (metadata) and Markdown content (instructions).
SKILL.md: Sections and Their Code-Level Fields
Sources: README.md65-88
The frontmatter appears at the top of SKILL.md, delimited by --- markers. The two required fields are name and description. Optional fields are also supported.
SKILL.md Frontmatter Fields
| Field | Required | Constraints | Notes |
|---|---|---|---|
name | Yes | kebab-case, max 64 chars, no consecutive hyphens | Identifies the skill; used for loading |
description | Yes | Max 1024 chars, no < or > characters | Drives trigger matching in Claude |
license | No | string | e.g., Apache-2.0 |
allowed-tools | No | list | Restrict which Claude tools the skill may invoke |
metadata | No | YAML dict | Arbitrary key-value metadata |
compatibility | No | string, max 500 chars | Platform compatibility notes |
These constraints are enforced by quick_validate.py skills/skill-creator/scripts/quick_validate.py42-93
Field requirements:
name: kebab-case ([a-z0-9-]+), cannot start or end with a hyphen, no consecutive hyphens, max 64 characters. See skills/skill-creator/scripts/quick_validate.py64-71description: Cannot contain < or >, max 1024 characters. Claude uses this field to determine when to activate the skill, so it must be specific and comprehensive. See skills/skill-creator/scripts/quick_validate.py74-84Sources: README.md66-69 README.md84-87 skills/skill-creator/scripts/quick_validate.py42-93
Below the YAML frontmatter, add Markdown content that provides instructions, examples, and guidelines for Claude to follow when the skill is active.
The template in README.md71-82 suggests this structure:
| Section | Purpose | Best Practices |
|---|---|---|
| Title | Human-readable skill name | Use H1 heading, clear and descriptive |
| Instructions | Core task description | Be specific, actionable, and sequential |
| Examples | Concrete usage scenarios | Provide realistic, diverse examples |
| Guidelines | Rules and constraints | Include edge cases, formatting rules, quality standards |
Sources: README.md71-82
Your skill folder may include additional resources beyond SKILL.md:
skills/my-skill-name/
├── SKILL.md
├── scripts/
│ └── helper.py
├── agents/
│ └── subagent.md
└── assets/
└── template.png
The document skills in this repository demonstrate this pattern:
scripts/recalc.py and LibreOffice macrosscripts/accept_changes.py, scripts/comment.pyscripts/add_slide.py, scripts/thumbnail.pyscripts/extract_form_structure.pySources: README.md18
Here is a minimal complete skill based on the template:
Sources: README.md65-82
The following diagram shows how SKILL.md is parsed by the validator and loaded by Claude at runtime, mapping file sections to the code checks that validate them.
SKILL.md Parsing: File Sections to Validator Checks in quick_validate.py
Sources: README.md65-88 skills/skill-creator/scripts/quick_validate.py12-94
Before testing, run quick_validate.py against your skill directory to catch formatting errors early:
python skills/skill-creator/scripts/quick_validate.py skills/my-skill-name/
The script exits with code 0 on success and 1 on failure, printing the first validation error it finds. See page 5.2 for the full list of validation gates.
Sources: skills/skill-creator/scripts/quick_validate.py96-103
After validating, test the skill in one of the Claude platforms:
/plugin marketplace add anthropics/skills"Use the my-skill-name skill to..."The skill-creator meta-skill (page 4) provides a structured evaluation pipeline: it runs parallel with_skill and without_skill subagent evaluations, grades outputs, and generates a benchmark report. This is useful for skills where you need to measure improvement quantitatively. See page 4.1 for the full workflow.
Sources: README.md29-59
To make your skill available via Claude Code's plugin system, add it to .claude-plugin/marketplace.json. See page 2.3 for the registry format.
| Element | Convention | Example |
|---|---|---|
| Folder name | kebab-case | doc-coauthoring |
| YAML name field | kebab-case, matches folder | doc-coauthoring |
| Markdown title | Title Case | Document Co-authoring |
The description field should:
Good description: "Creates professional PowerPoint presentations with consistent formatting, brand guidelines, and visual hierarchy. Use when generating slide decks for business presentations, reports, or educational content."
Poor description: "Makes presentations" (too vague)
Sources: README.md84-87
After creating your basic skill:
.claude-plugin/marketplace.json (see Skill Development Lifecycle)For marketplace registration and platform-specific deployment, continue to Skill Development Lifecycle.
Refresh this wiki
This wiki was recently refreshed. Please wait 4 days to refresh again.