metaskill-authoring

# 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

```yaml
---
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

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

### Content Structure Template

```markdown
# 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 compl