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:
```python
# ✅ 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