skill-development

What this skill does

# Skill Development for Claude Code Plugins

## Overview

Skills are modular knowledge packages that extend Claude's capabilities with specialized workflows, domain expertise, and bundled resources. They transform Claude from a general-purpose agent into a specialized expert.

Skills use **progressive disclosure** - a three-level loading system that manages context efficiently:

1. **Metadata** (name + description) - Always in context (~100 words)
2. **SKILL.md body** - Loaded when skill triggers (~1,500-2,000 words)
3. **Bundled resources** - Loaded as needed by Claude (unlimited)

## Skill Structure

```text
skill-name/
├── SKILL.md              # Required: Core instructions
├── references/           # Optional: Detailed documentation
│   ├── patterns.md       #   Loaded when Claude needs detail
│   └── advanced.md
├── examples/             # Optional: Working code examples
│   └── example.sh        #   Users can copy and adapt
├── scripts/              # Optional: Executable utilities
│   └── validate.sh       #   Token-efficient, deterministic
└── assets/               # Optional: Output resources
    └── template.html     #   Used in output, not loaded into context
```

**Only create directories you actually need.** A minimal skill is just `SKILL.md`.

## SKILL.md Format

### Frontmatter (Required)

This is the canonical shape every new skill MUST follow. Deviating is the #1 cause of skills that never trigger.

```yaml
---
name: skill-name                                  # REQUIRED: kebab-case, matches directory name
description: One-sentence summary of what the skill covers. PROACTIVELY activate for: (1) concrete named trigger, (2) concrete named trigger, ..., (N) concrete named trigger. Provides: comma-separated capability nouns (concrete, not abstract).
---
```

Or, if the description is multi-line (only needed for very long descriptions — prefer single-line when practical):

```yaml
---
name: skill-name
description: |
  One-sentence summary. PROACTIVELY activate for: (1) trigger, (2) trigger, ..., (N) trigger. Provides: capability list.
---
```

### Hard rules for the frontmatter

1. **`name:` is required** and must match the enclosing directory name exactly (`skills/skill-name/SKILL.md` → `name: skill-name`).
2. **`description:` is required** and MUST contain BOTH the `PROACTIVELY activate for: (1)... (N)...` enumeration AND a `Provides: ...` capability list.
3. **A SKILL.md with NO frontmatter at all is broken.** It will never trigger, will not appear in skill discovery, and should be treated as a P0 bug. If you open a SKILL.md and the first line is not `---`, fix the frontmatter before doing anything else.
4. **Enumerate concrete, named triggers — not abstract capabilities.** "PROACTIVELY activate for: (1) creating Azure Functions, (2) binding config" is good. "Use this skill when working with Azure" is NOT.
5. **Describe WHEN to use, not WHAT it does.** The description drives routing, so it must read as a trigger list from the user's point of view. Put the capability summary in `Provides: ...` at the end.
6. **Keep descriptions single-line YAML-safe.** If you use `|` block scalar, do not embed unescaped colons or other YAML-confusing characters in the middle of lines.
7. **Target 400-1000 characters for the description; hard ceiling is 1024 characters (Claude Code API spec).** Claude's current listing cap is 1536 chars per entry (raised from 250 in v2.1.105), and the aggregate budget across all installed skills is ~1% of the model context window. Front-load trigger keywords. If you genuinely need more triggers than fit in ~1000 chars, prefer splitting into two skills over a bloated description.
8. **Do NOT put cross-cutting boilerplate (Windows paths, docs policy) inside the YAML description.** Put it in the markdown body.

### Canonical "good" description

```yaml
description: Expert guide to Terraform AzureRM provider for Azure infrastructure. PROACTIVELY activate for: (1) authoring AzureRM resource blocks, (2) state management (remote backends, state locking), (3) module design and composition, (4) variable and output patterns, (5) provider version pinning, (6) debugging plan/apply errors, (7) importing existing Azure resources, (8) CI/CD for Terraform (Azure DevOps, GitHub Actions). Provides: AzureRM provider patterns, state backend templates, module scaffolding, debugging playbook, and import recipes.
```

### Broken descriptions (each of these fails to route reliably)

```yaml
# BROKEN: no frontmatter at all
# (file starts with `# Skill Title` - will not appear in discovery)

# BROKEN: wrong shape, no enumeration
description: Use this skill when working with Terraform.

# BROKEN: abstract capability, no triggers
description: Provides Terraform expertise and guidance.

# BROKEN: WHAT-it-does instead of WHEN-to-use
description: This skill contains Terraform AzureRM provider documentation.

# BROKEN: second person (wrong voice)
description: You should load this skill when the user mentions Terraform.

# BROKEN: missing Provides list
description: PROACTIVELY activate for: (1) Terraform tasks. (No Provides section means the capability summary is lost.)

# BROKEN: cross-cutting Windows boilerplate inside YAML
description: |
  Terraform expert. MANDATORY: Always Use Backslashes on Windows for File Paths...
  (This is routing-match pollution. Move Windows rules to the body.)
```


### Body - Writing Style

Write the entire skill body using **imperative/infinitive form** (verb-first instructions):

**Correct (imperative):**
```text
To create a hook, define the event type.
Configure the MCP server with authentication.
Validate settings before use.
Start by reading the configuration file.
```

**Incorrect (second person):**
```bash
You should create a hook by defining the event type.
You need to configure the MCP server.
You can use the grep tool to search.
```

### Body - Structure

```markdown
# Skill Title

## Overview
[Purpose and when to use - 2-3 sentences]

## Quick Reference
[Tables with key facts, common values, or patterns]

## Core Content
[Essential procedures and workflows - the main value]

## Additional Resources

### Reference Files
- **`references/patterns.md`** - Common patterns
- **`references/advanced.md`** - Advanced techniques

### Example Files
- **`examples/example.sh`** - Working example
```

### Body - Size Guidelines

| Target | Words |
|--------|-------|
| Ideal | 1,500-2,000 |
| Maximum | 3,000 (absolute hard limit) |

**If SKILL.md exceeds 2,000 words**, move detailed content to `references/` files.

**Size enforcement process:**
1. After writing SKILL.md, count words (exclude frontmatter). Use `wc -w` or estimate ~5 words per line.
2. If over 2,000 words, identify sections that are reference material (detailed tables, exhaustive lists, server-specific configs, troubleshooting matrices) and extract them to `references/`.
3. If over 3,000 words after extraction, the skill is too broad — split into two skills or move more content to references.
4. **Never leave a section in SKILL.md just because it was written there first.** Always evaluate whether each section earns its place in the core file.

### Body - Avoiding Duplicate Content

**Within a single SKILL.md**, never repeat the same table, list, or block of content. Before adding any table or reference block, search the file for similar content already present.

**Across SKILL.md and references/**, information lives in one place only. If a detailed table is in `references/patterns.md`, SKILL.md should contain only a brief summary and a pointer to the reference file — not a copy of the table.

### The "≥ 2 verbatim copies = extract" gate (MANDATORY)

When authoring or revising any skill, before pasting a paragraph, table, checklist, or fenced code block into a SKILL.md or reference file, run this check:

```bash
# From the plugin root - adjust path to the candidate paragraph's first distinctive line:
grep -rn "FIRST_DISTINCTIVE_LINE_OF_THE_BLOCK" skills/ agent