Skill Development for Claude Code Plugins

This skill provides guidance for creating effective skills for Claude Code plugins.

About Skills

Skills are modular, self-contained packages that extend Claude's capabilities by providing specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific domains or tasks—they transform Claude from a general-purpose agent into a specialized agent equipped with procedural knowledge that no model can fully possess.

What Skills Provide

1. Specialized workflows - Multi-step procedures for specific domains
2. Tool integrations - Instructions for working with specific file formats or APIs
3. Domain expertise - Company-specific knowledge, schemas, business logic
4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks

Anatomy of a Skill

Every skill consists of a required SKILL.md file and optional bundled resources:

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter metadata (required)
│   │   ├── name: (required)
│   │   └── description: (required)
│   └── Markdown instructions (required)
└── Bundled Resources (optional)
    ├── scripts/          - Executable code (Python/Bash/etc.)
    ├── references/       - Documentation intended to be loaded into context as needed
    └── assets/           - Files used in output (templates, icons, fonts, etc.)

SKILL.md (required)

Metadata Quality: The name and description in YAML frontmatter determine when Claude will use the skill. Be specific about what the skill does and when to use it. Use the third-person (e.g. "This skill should be used when..." instead of "Use this skill when...").

Optional Frontmatter Fields

allowed-tools

Optionally restrict which tools Claude can use when the skill is active:

---
name: code-reviewer
description: Review code for best practices...
allowed-tools: Read, Grep, Glob
---

Use allowed-tools for:

• Read-only skills that shouldn't modify files
• Security-sensitive workflows
• Skills with limited scope

When specified, Claude can only use the listed tools without needing permission. If omitted, Claude follows the standard permission model.

Bundled Resources (optional)

Scripts (scripts/)

Executable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten.

• When to include: When the same code is being rewritten repeatedly or deterministic reliability is needed
• Example: scripts/rotate_pdf.py for PDF rotation tasks
• Benefits: Token efficient, deterministic, may be executed without loading into context

References (references/)

Documentation and reference material intended to be loaded as needed into context.

• When to include: For documentation that Claude should reference while working
• Examples: references/schema.md for database schemas, references/api_docs.md for API specifications
• Best practice: If files are large (>10k words), include grep search patterns in SKILL.md
• Avoid duplication: Information should live in either SKILL.md or references files, not both

Assets (assets/)

Files not intended to be loaded into context, but rather used within the output Claude produces.

• When to include: When the skill needs files that will be used in the final output
• Examples: assets/logo.png for brand assets, assets/slides.pptx for templates

Progressive Disclosure Design Principle

Skills use a three-level loading system to manage context efficiently:

1. Metadata (name + description) - Always in context (~100 words)
2. SKILL.md body - When skill triggers (<5k words)
3. Bundled resources - As needed by Claude (Unlimited*)

*Unlimited because scripts can be executed without reading into context window.

Skill Creation Process

To create a skill, follow these six steps. For detailed instructions on each step, see references/skill-creation-workflow.md.

1. Understand the Skill: Gather concrete examples of how the skill will be used through user questions and feedback
2. Plan Reusable Contents: Analyze examples to identify what scripts, references, and assets would be helpful
3. Create Structure: Set up the skill directory with mkdir -p skills/skill-name/{references,examples,scripts}
4. Edit the Skill: Write SKILL.md with proper frontmatter and imperative-form body; create bundled resources
5. Validate and Test: Check structure, trigger phrases, writing style, and progressive disclosure
6. Iterate: Improve based on real-world usage and feedback

Key Writing Guidelines

• Description: Use third-person ("This skill should be used when...") with specific trigger phrases
• Body: Use imperative/infinitive form ("To create X, do Y"), not second person ("You should...")
• Size: Target 1,500-2,000 words; move detailed content to references/

Plugin-Specific Considerations

Skill Location in Plugins

Plugin skills live in the plugin's skills/ directory:

my-plugin/
├── .claude-plugin/
│   └── plugin.json
├── commands/
├── agents/
└── skills/
    └── my-skill/
        ├── SKILL.md
        ├── references/
        ├── examples/
        └── scripts/

Auto-Discovery

Claude Code automatically discovers skills:

• Scans skills/ directory
• Finds subdirectories containing SKILL.md
• Loads skill metadata (name + description) always
• Loads SKILL.md body when skill triggers
• Loads references/examples when needed

No Packaging Needed

Plugin skills are distributed as part of the plugin, not as separate ZIP files. Users get skills when they install the plugin.

Testing in Plugins

Test skills by installing plugin locally:

# Test with --plugin-dir
claude --plugin-dir /path/to/plugin

# Ask questions that should trigger the skill
# Verify skill loads correctly

Examples from Plugin-Dev

Study the skills in this plugin as examples of best practices:

hook-development skill:

• Excellent trigger phrases: "create a hook", "add a PreToolUse hook", etc.
• Lean SKILL.md (2,125 words)
• 3 references/ files for detailed content
• 3 examples/ of working hooks
• 3 scripts/ utilities

agent-development skill:

• Strong triggers: "create an agent", "agent frontmatter", etc.
• Focused SKILL.md (1,896 words)
• References include the AI generation prompt from Claude Code
• Complete agent examples

plugin-settings skill:

• Specific triggers: "plugin settings", ".local.md files", "YAML frontmatter"
• References show real implementations (multi-agent-swarm, ralph-wiggum)
• Working parsing scripts

Each demonstrates progressive disclosure and strong triggering.

Validation Checklist

Before finalizing a skill:

Structure:

• SKILL.md file exists with valid YAML frontmatter
• Frontmatter has name and description fields
• Name uses only lowercase letters, numbers, and hyphens (max 64 chars)
• Description is under 1024 characters
• (Optional) allowed-tools field if restricting tool access
• Markdown body is present and substantial
• Referenced files actually exist

Description Quality:

• Uses third person ("This skill should be used when...")
• Includes specific trigger phrases users would say
• Lists concrete scenarios ("create X", "configure Y")

Content Quality:

• SKILL.md body uses imperative/infinitive form
• Body is focused and lean (1,500-2,000 words ideal, <3k max)
• Detailed content moved to references/
• Examples are complete and working

Testing:

• Skill triggers on expected user queries
• Content is helpful for intended tasks
• No duplicated information across files

Quick Reference

Minimal Skill

skill-name/
└── SKILL.md

Good for: Simple knowledge, no complex resources needed

Standard Skill (Recommended)

skill-name/
├── SKILL.md
├── references/
│   └── detailed-guide.md
└── examples/
    └── working-example.sh

Good for: Most plugin skills with detailed documentation

Complete Skill

skill-name/
├── SKILL.md
├── references/
│   ├── patterns.md
│   └── advanced.md
├── examples/
│   ├── example1.sh
│   └── example2.json
└── scripts/
    └── validate.sh

Good for: Complex domains with validation utilities

Best Practices Summary

DO:

• Use third-person in description ("This skill should be used when...")
• Include specific trigger phrases ("create X", "configure Y")
• Keep SKILL.md lean (1,500-2,000 words)
• Use progressive disclosure (move details to references/)
• Write in imperative/infinitive form
• Reference supporting files clearly
• Provide working examples
• Create utility scripts for common operations

DON'T:

• Use second person ("You should...")
• Have vague trigger conditions
• Put everything in SKILL.md (>3,000 words without references/)
• Leave resources unreferenced
• Include broken or incomplete examples

Additional Resources

Example Skills

Copy-paste ready skill templates in examples/:

• examples/minimal-skill.md - Bare-bones skill with just SKILL.md (git conventions example)
• examples/complete-skill.md - Full skill with references/, examples/, and scripts/ (API testing example)
• examples/frontmatter-templates.md - Quick-reference frontmatter patterns for common use cases

Reference Files

For detailed guidance, consult:

• references/skill-creation-workflow.md - Plugin-specific skill creation workflow (recommended for plugin skills)
• references/skill-creator-original.md - Original generic skill-creator methodology (includes init/packaging scripts for standalone skills)

Study These Skills

Plugin-dev's skills demonstrate best practices:

• ../hook-development/ - Progressive disclosure, utilities
• ../agent-development/ - AI-assisted creation, references
• ../mcp-integration/ - Comprehensive references
• ../plugin-settings/ - Real-world examples
• ../command-development/ - Clear critical concepts
• ../plugin-structure/ - Good organization