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

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:

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

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:

description: Helps with documents  # Too vague, no trigger terms

allowed-tools (optional)

Restrict which tools the skill can use when activated.

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

# 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: support@example.com

Skill Content Best Practices

1. Start with Overview

# 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

## Usage