Create Skill

Create a new skill following the Agent Skills standard.

Skill Basics

Each skill lives in its own directory with a SKILL.md file:

skill-name/
  SKILL.md           # Required: main skill file
  reference.md       # Optional: supporting content

Frontmatter

---
name: skill-name
description: "What this skill helps with. Automatically invoke when [trigger condition]. Do not apply when [exclusion condition]."
metadata:
  title: Human-Readable Title
  category: dev
---

The description must be a single line and must not exceed 200 characters. It should end with "Automatically invoke when..." to help agents pattern-match when to use the skill. Add "Do not apply when..." if there are common false-positive triggers.

Single vs Multi-File

Single-file: Everything fits in one SKILL.md (most skills)

Multi-file: Complex topics split into:

• SKILL.md — Overview and quick reference (router)
• topic-a.md — Detailed content
• topic-b.md — More detailed content

Use multi-file when content exceeds ~200 lines or covers distinct sub-topics.

Workflow

1. Interpret Intent

• Extract the core purpose of the skill
• Look for naming clues (they may say "foo" or "foo.md")
• If no name specified, infer a good skill name (kebab-case)
• Understand what problem it should solve

2. Propose the Skill

• Suggest a name like my-new-skill
• Write a clear description (when to use it)
• Draft the skill content
• Show the user what you plan to create

3. Get Approval

• Ask: "Should I create skill-name/SKILL.md with this functionality?"
• Wait for user confirmation or adjustments
• Iterate until they're satisfied

4. Confirm Location

Ask where to create the skill. Common locations:

Location	Use Case
skills/	In dev-skills repo
{project}/.claude/skills/	Project-specific
~/.claude/skills/	Personal global skills

Wait for user to specify the path.

5. Create the Skill

• Create directory: [path]/[skill-name]/
• Create main file: SKILL.md
• Add reference files if needed for multi-file skills

6. Design Principles

• Single, focused purpose
• Clear, direct language
• Description explains WHEN to use it
• Consider whether single-file or multi-file is appropriate

Skill Format

Required: Frontmatter

Every SKILL.md must have YAML frontmatter:

---
name: skill-name
description: "Brief description of what this skill helps with and when to use it. This helps AI agents decide when to apply it."
metadata:
  title: Human-Readable Title
  category: Category Name
---

Fields

Field	Required	Purpose
name	Yes	Skill identifier (kebab-case)
description	Yes	When to use this skill (helps AI select it)
metadata	No	Additional key-value pairs (title, category)

Body Content

After frontmatter, write the skill content in Markdown.

Single-File Skills

For focused skills, put everything in SKILL.md:

---
name: my-skill
description: When to use this skill.
metadata:
  title: Skill Title
  category: Category
---

# Skill Title

Main content here...

## Section

More content...

Multi-File Skills (Router Pattern)

For complex skills, SKILL.md acts as a router:

---
name: my-skill
description: When to use this skill.
metadata:
  title: Skill Title
  category: Category
---

# Skill Title

Brief overview of what this skill covers.

## Quick Reference

- [Topic A](topic-a.md) — Description of topic A
- [Topic B](topic-b.md) — Description of topic B

## Summary

Key points that don't need their own file...

When to Use Multi-File

Use multi-file when:

• Content exceeds ~200 lines
• Skill covers distinct sub-topics
• Users might need only part of the content

Keep as single-file when:

• Content is focused and cohesive
• Everything fits comfortably in one file

Content Patterns

Optional structures for organizing skill content, especially for skills that describe rules, patterns, or standards.

Simple Pattern Structure

For skills that describe a single rule or pattern:

## Problem & Solution

What problem exists and how this pattern solves it.

## Pattern

The specific rule or approach. Include rationale inline.

## Examples

❌ **DON'T** do this

✅ **DO** do this

## Checks

How to verify correct application:
- [ ] Check 1
- [ ] Check 2

## Notes

Edge cases, variations, and additional context.

Required sections: Problem & Solution, Pattern, Examples. Optional sections: Checks, Notes, What Not To Do.

Composite Pattern Structure

For skills covering multiple related rules:

## Problem & Solution

Overall problem and how this collection of rules solves it.

## Pattern

### Rule: Specific Requirement 1

Brief explanation. Keep it self-contained.

❌ **DON'T**

✅ **DO**

### Rule: Specific Requirement 2

Another self-contained rule with its own examples.

## Complete Example

Optional: Show all rules working together in a realistic scenario.

Aspect Types

Use appropriate labels for different kinds of rules:

Label	Use When
Rule:	Hard requirement, must follow
Guideline:	Strong recommendation
Principle:	General guidance

Ordering

Order aspects from most common/important to least.

Keep Aspects Minimal

Each aspect should be self-contained. Include DO/DON'T examples only when needed to clarify. Avoid verbosity.

Write checks, notes, and anti-patterns as inline prose within each aspect — do NOT create subsection headings like #### Checks or #### Notes.

Complete Example

When aspects work together, add a Complete Example section showing all rules applied in a realistic scenario.

Include Complete Example when:

• Multiple aspects typically apply together
• Showing the full picture helps understanding
• A realistic scenario demonstrates integration

Skip when aspects are independent and self-contained.

Presenting Code

Rule: Usage before implementation

Show what something gives the reader before showing how it works. When a skill documents both usage and implementation, put calling code first so the reader has context for the internals that follow.

Rule: Show code doing real work

Code examples should solve a recognizable problem, not demonstrate features in isolation.

Rule: Generalize when the behavior is general

If a behavior applies to every instance of a pattern, say so. Don't narrow the claim to one example.