skill-dev

What this skill does

# Skill Dev Skill

This skill helps create production-ready Claude Code skills following Anthropic's official specifications and best practices.

## Skills vs Agents: Key Differences

| Aspect | Skills | Sub-agents |
|--------|--------|------------|
| **Invocation** | Model-invoked (automatic) | User-invoked (explicit) or Task tool |
| **Scope** | Single capability | Multiple capabilities |
| **File** | Directory with SKILL.md | Single .md file |
| **Supporting files** | Can include templates, scripts | System prompt only |
| **Discovery** | Description matching | Description + explicit invocation |
| **Use case** | Reusable patterns, tools, workflows | Specialized AI assistants |

**When to use Skills**: Create autonomous capabilities that Claude should invoke automatically when context matches (e.g., PDF processing, form filling, specific workflows)

**When to use Agents**: Create specialized AI assistants for complex domains requiring multi-step reasoning (e.g., database expert, security auditor)

## Use Case Categories

Anthropic identifies three common skill categories:

| Category | Purpose | Example |
|----------|---------|---------|
| **Document & Asset Creation** | Produce tangible outputs (reports, documents, designs, code) | A `frontend-design` skill that creates production-grade UI components |
| **Workflow Automation** | Orchestrate multi-step processes with validation gates | A `skill-creator` skill that walks users through use case definition, frontmatter, and validation |
| **MCP Enhancement** | Add knowledge and best practices on top of MCP tool access | A `sentry-code-review` skill that uses Sentry's MCP to analyze and fix bugs in PRs |

**The kitchen analogy**: MCP provides the professional kitchen (tools, ingredients, equipment). Skills provide the recipes (step-by-step instructions on how to create something valuable). Together, they enable users to accomplish complex tasks without figuring out every step themselves. See `patterns/skill-mcp-integration.md` for in-depth MCP integration guidance.

### Problem-First vs. Tool-First

When designing a skill, choose your framing:

- **Problem-first**: Start from a user pain point, then orchestrate the right tools to solve it. Users describe outcomes; the skill handles the tools. Example: "I need to set up a project workspace" → skill orchestrates MCP calls in the right sequence.
- **Tool-first**: You have MCP tools connected, and the skill teaches Claude optimal workflows and best practices for using them. Users have access; the skill provides expertise. Example: "I have Notion MCP connected" → skill teaches Claude the best project setup workflows.

Most skills lean one direction. Knowing which framing fits your use case helps you choose the right pattern (see Common Patterns below).

## Skill Structure

```
skill-name/
├── SKILL.md                    # Required: Skill definition and content
├── examples/                   # Optional: Example usage
│   ├── basic-usage.md
│   └── advanced-patterns.md
├── templates/                  # Optional: Code templates
│   └── template-file.py
├── references/                 # Optional: Reference materials
│   └── api-docs.md
├── assets/                     # Optional: Static resources (templates, fonts, icons)
│   └── report-template.md
└── scripts/                    # Optional: Helper scripts
    └── helper.py
```

**Important**: Do NOT include `README.md` inside skill directories. `SKILL.md` serves as both the skill definition and documentation. When distributing via GitHub, use a repo-level README for human users — that is separate from the skill folder contents.

## SKILL.md Format

```yaml
---
name: skill-name
description: >
  Detailed description of what this skill does, when Claude should use it,
  and specific trigger terms. This field is CRITICAL for skill discovery.

  Include:
  - What the skill accomplishes
  - When to activate (specific scenarios)
  - Key trigger terms users might mention
  - Concrete examples of usage

allowed-tools: Tool1, Tool2    # Optional: Tool restrictions
---

# Skill Content

Main skill content starts here. This is what Claude sees when the skill is activated.

Include:
- Clear instructions
- Examples
- Best practices
- Common patterns
- Error handling

Reference supporting files with relative paths:
- See `examples/basic-usage.md` for getting started
- Use templates from `templates/` directory
- Consult `references/api-docs.md` for API details
```

## Required Fields

### name
Unique identifier for the skill.

**Constraints**:
- Should match the skill folder name
- Lowercase alphanumeric with hyphens only
- Maximum 64 characters
- Descriptive of the capability

```yaml
name: pdf-form-filling        # Good
name: PDF Form Filling        # Bad - no spaces/capitals
name: helper                  # Bad - too generic
name: skill-that-does-pdf-form-filling-and-extraction  # Bad - too long
```

### description
The MOST IMPORTANT field. Claude uses this to decide when to activate the skill.

**Critical elements**:
1. **Primary capability**: What does this skill do? (1-2 sentences)
2. **Activation triggers**: When should Claude use this? (be specific)
3. **Key terms**: Words/phrases users might mention
4. **Scope boundaries**: What this skill does NOT handle
5. **Negative triggers**: Explicitly state what the skill does NOT handle to prevent over-triggering (see "Do NOT use for:" in example below)

**Constraints**: Description must be under 1024 characters. No XML angle brackets (`<` or `>`).

**Debug technique**: Ask Claude: "When would you use the [skill name] skill?" Claude will quote the description back — adjust based on what's missing or misaligned.

**Good description example**:
```yaml
description: >
  Extract text and tables from PDF documents, fill PDF forms programmatically,
  and merge multiple PDFs. Use when user mentions PDF files, form filling,
  document parsing, or PDF manipulation.

  Activate for:
  - "Extract data from this PDF"
  - "Fill out this PDF form"
  - "Parse tables from PDF"
  - "Combine these PDFs"

  Do NOT use for:
  - Creating PDFs from scratch (use document generation skill)
  - Image extraction (use image processing skill)
```

**Bad description example**:
```yaml
description: Helps with documents  # Too vague, no trigger terms
```

### allowed-tools (optional)
Restrict which tools the skill can use when activated.

```yaml
# Read-only skill
allowed-tools: Read, Grep, Glob

# File manipulation skill
allowed-tools: Read, Write, Edit

# Full access (can run commands)
allowed-tools: Read, Write, Bash, Grep
```

**When to restrict tools**:
- Security-sensitive operations
- Skills that should only read/analyze
- Prevent accidental modifications

**When to omit** (inherit all tools):
- Skills need flexible tool access
- General-purpose capabilities
- Orchestration skills

### Optional Frontmatter Fields

Beyond `name`, `description`, and `allowed-tools`, skills support these optional fields:

```yaml
# Optional fields
license: MIT                                    # For open-source skills
compatibility: claude-code, claude-ai, api      # 1-500 chars, environment requirements
# Note: Skills work identically across Claude.ai, Claude Code, and API.
# Create once, use everywhere — provided the environment supports any
# dependencies the skill requires.
metadata:
  author: Your Name
  version: 1.0.0
  mcp-server: server-name                       # If skill enhances an MCP server
  category: workflow                            # document | workflow | mcp-enhancement
  tags: [deployment, automation]
  documentation: https://example.com/docs
  support: [email protected]
```

## Skill Content Best Practices

### 1. Start with Overview
```markdown
# Skill Name

## Overview
Brief description of what this skill provides and when to use it.

## Capabilities
- List specific capabilities
- Be concrete and actionable
- Include limitations
```

### 2. Provide Clear Instructions
```markdown
## Usage