Build Your Own Skill

What is a Skill?

A Skill is a markdown file Claude auto-references when a matching task occurs. The body holds the procedure, rules, or checklist — and Claude follows it.

If the workflow needs code execution, use a Plugin. If you just want to standardize a procedure or rule, use a Skill.

File layout

~/.claude/skills/<skill-name>/
├── SKILL.md          # required — frontmatter + body
└── (helper files)    # optional — references, templates

SKILL.md template

---
name: <skill-name>
description: <Specific trigger conditions for invoking this Skill>
---

# Skill title

## When to use
Describe the situations that should invoke this Skill.

## Procedure
1. First step
2. Second step
3. ...

## Checklist
- [ ] Item 1
- [ ] Item 2

Why the description matters

description is the primary signal Claude uses to invoke the Skill. Hallmarks of a good description:

• Explicit trigger conditions — “when doing X”, “when handling Y files”
• Includes feature names and keywords — words users actually use
• Optional negative conditions — “skip if Z”

Good

description: |
  Use when creating or modifying SQL migration files in db/migrations/.
  Enforces naming convention (timestamp_description.sql), reversibility,
  and schema review checklist. Skip for read-only queries.

Bad

description: Database stuff  # too vague — Claude won't trigger reliably

Body principles

1. Number the procedure

Numbered steps are followed more reliably than prose.

2. Bold the don’ts

**Never**:
- Delete migration files manually
- Alter columns without an explicit ALTER TABLE

3. Include verification

## Verify
- After applying: `npm test`
- Roundtrip: `npm run db:rollback && npm run db:migrate`

4. Use absolute references

When you reference another Skill or doc, name it explicitly.

Example: a content review Skill

---
name: review-content
description: |
  Use when reviewing or modifying content files in src/content/.
  Checks frontmatter schema, ko/en pair consistency, link validity,
  and applies the project quality rules.
---

# Content Review

## When to run
- After any content file is created or modified
- Before deployment

## Procedure
1. Verify frontmatter against schema
2. Check ko/en pair consistency (slug, dates align)
3. Validate external links
4. Review tone consistency

## Verify
\```bash
npm run build
\```

User-scope vs plugin-scope

Location	Scope	Distribution
~/.claude/skills/<name>/SKILL.md	Just you	Manual
skills/<name>/SKILL.md inside a plugin	All plugin users	Marketplace

For team or public distribution, bundle the Skill into a plugin and list it on a marketplace.

Common mistakes

• ❌ description too short — Claude won’t trigger
• ❌ Body written as prose — split into steps
• ❌ Skill scope too broad — one Skill = one procedure
• ❌ Trigger conditions overlap with another Skill — keep them distinct

Next steps

• Read the Skills bundled in Superpowers for structure
• Obsidian Skills — a well-designed Skill collection
• Writing a Great CLAUDE.md — separate Skill vs CLAUDE.md responsibilities