Writing Great Claude Code Skills

First: Two Key Questions

1. What should I name this? See /metaskill-naming for the naming convention and brainstorming process.

2. Single skill or skill group? Does this topic have 3+ distinct concerns users might approach from different angles? If YES, you need a skill GROUP (multiple skills in a plugin), not a single skill. See /metaskill-grouping for the skill group pattern.

Skill Directory Structure

Simple Skill (Single Concern)

skill-name/ SKILL.md

Skill with Deep Content

skill-name/ SKILL.md <- Quick answers and rules references/ <- Deep dives (OPTIONAL reading) topic-a.md topic-b.md

Skill Group (Multiple Concerns)

plugin-name/ .claude-plugin/ plugin.json skills/ plugin-name-doing/ <- ends in -ing SKILL.md plugin-name-other-ing/ <- ends in -ing SKILL.md README.md

Note: See /metaskill-naming for naming conventions (neutral noun prefix, -ing suffix for skills).

SKILL.md Structure

Required Frontmatter

name: skill-name description: <What it does>. Use when <specific actions>. Triggers on "<keyword1>", "<keyword2>", "<keyword3>", or when <conditions>.

The description is CRITICAL - it's the only field that affects triggering. See /metaskill-triggering for optimization techniques.

Optional Frontmatter Fields

name: skill-name description: ... allowed-tools: Read, Edit, Bash(npm test:*) disable-model-invocation: true # Blocks auto-triggering (user must invoke)

Content Structure Template

Skill Title

Core Philosophy (1-2 sentences)

What problem does this skill solve? What's the key insight?

Quick Start

The 80% case - what users need most often.

Critical Rules

Essential dos and don'ts as code blocks:

# ✅ CORRECT
good_example()

# ❌ INCORRECT
bad_example()

Checklist

Before completing, verify:

-  Item 1

-  Item 2

Reference Files (if using references/)

For detailed patterns:

- references/topic-a.md - Deep dive on A

- references/topic-b.md - Deep dive on B

Related Skills

- For X, see /related-skill-a

- For Y, see /related-skill-b

## Progressive Disclosure

**Principle:** Quick answers in SKILL.md body, deep dives in references.

| Location | Content Type | Reading |
|----------|-------------|---------|
| SKILL.md body | Rules, quick start, checklists | MANDATORY |
| references/ | Deep explanations, many examples | OPTIONAL |

**Warning:** Don't put critical rules ONLY in references - they might be skipped!

## When to Use References vs Skill Groups

**Use `references/` when:**
- Content supports the main skill but isn't required
- Users who trigger the skill need the SAME core content
- Deep dives are nice-to-have, not essential

**Use a skill group when:**
- Content is independently triggerable (different keywords)
- Users might ONLY want a subset
- Each area has substantial, distinct content

Example:

references/ appropriate

testing/
SKILL.md              <- All testers need this
references/
mocking.md          <- Some need deep mocking info
fixtures.md         <- Some need deep fixture info

Skill group appropriate (note: neutral prefix, -ing suffix)

metaskill/
skills/
metaskill-authoring/   <- "write skill"
metaskill-triggering/  <- "fix trigger" (different concern!)
metaskill-grouping/    <- "create plugin" (different concern!)

## Trigger Optimization

Your skill is useless if it never triggers. Key points:
- ONLY the `description` field affects triggering
- Include exact phrases users say
- Include action verbs (Create, Write, Generate)
- Include keyword variants (test, tests, testing)

For comprehensive trigger optimization, see `/metaskill-triggering`.

## Common Mistakes

**Body too long:** Extract deep content to references/

**Critical rules in references:** Keep essential rules in SKILL.md body

**Weak description:** See `/metaskill-triggering` for optimization

**Monolithic skill for complex topic:** See `/metaskill-grouping` for when to split

**Bad naming:** See `/metaskill-naming` for the naming convention

## Related Skills

- For naming conventions, see `/metaskill-naming`
- For trigger optimization, see `/metaskill-triggering`
- For skill group pattern, see `/metaskill-grouping`
- For plugin packaging and placement, see `/metaskill-packaging`
- To test triggers, use the `metaskill-trigger-tester` agent