/skill-dev

name: skill-dev
description: >
  Use this skill when creating or refining Claude Code skill definitions. Skills are model-invoked
  capabilities that Claude activates autonomously based on context. Helps design focused skills with
  discovery-optimized descriptions, proper directory structures, and supporting resources. Automatically
  invoked when user requests "create a skill", "make a capability", "add autonomous behavior", or mentions
  skill development. Ensures skills follow Anthropic specifications with clear activation triggers.
allowed-tools: Read, Write, Edit, Grep, Glob, Bash(mkdir:*), Bash(tree:*), mcp__Conventions__search_conventions

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

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

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 wha