Skill Best Practices

Overview

Create effective Claude Code skills that provide specialized knowledge and workflows. High-quality skills transform Claude from a general-purpose assistant into a domain expert equipped with procedural knowledge.

Core Principles

Progressive Disclosure

Use a three-level loading system to manage context efficiently:

Metadata (name + description) - Always in context (~100 words)
SKILL.md body - When skill triggers (<2,000 words)
Bundled resources - As needed (unlimited, loaded selectively)

Keep SKILL.md lean. Move detailed content to references/ files.

Strong Triggering

The description field determines when Claude activates the skill. Use specific, concrete phrases:

✅ Good:

description: This skill should be used when the user asks to "create a hook",
"add a PreToolUse hook", "validate tool use", or mentions hook events
(PreToolUse, PostToolUse, Stop).

❌ Bad:

description: Use this skill when working with hooks.

Third-Person Descriptions

Always write descriptions in third person: "This skill should be used when..."

❌ Avoid second person: "Use this skill when you want to..."

Imperative Writing Style

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

✅ Good:

Create the skill directory structure.
Validate the frontmatter syntax.
Check required fields.

❌ Bad:

You should create the directory structure.
You need to validate the syntax.

Skill Structure

Required Components

Every skill must have:

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter (name, description required)
│   └── Markdown body
└── [Optional resources]
    ├── scripts/      - Executable utilities
    ├── references/   - Detailed documentation
    └── assets/       - Templates and output files

YAML Frontmatter

Required fields:

name - Skill name (Title Case)
description - Third-person description with specific triggers

Optional fields:

version - Skill version (semantic versioning)

Example:

---
name: My Skill
description: This skill should be used when the user asks to "task 1",
"task 2", or "task 3".
version: 0.1.0
---

Content Guidelines

SKILL.md Body (Core Content)

Target 1,500-2,000 words maximum. Include:

Essential Content:

Purpose and overview (what the skill does)
Core concepts and terminology
Essential procedures and workflows
Quick reference tables
Most common use cases
Links to supporting resources

Keep focused: Move detailed patterns, advanced techniques, and comprehensive examples to references/ files.

References/ (Detailed Documentation)

Move to references/ when content is:

Detailed and comprehensive (2,000-5,000+ words)
Advanced or specialized patterns
API documentation and specifications
Migration guides
Edge cases and troubleshooting

Benefits:

SKILL.md stays lean
Details load only when needed
Better context management
Easier to maintain

Never duplicate: Information should live in either SKILL.md OR references/, not both.

Examples/ (Working Code)

Store complete, runnable examples:

Full scripts that work
Configuration files
Template code
Real-world usage samples

Users can copy and adapt these directly.

Scripts/ (Utilities)

Include executable tools when:

The same code is repeatedly rewritten
Deterministic reliability is needed
Complex automation helps

Examples:

Validation scripts
Testing helpers
Parsing utilities

Trigger Phrase Optimization

Be Specific and Concrete

List exact phrases users would say:

✅ Good:

description: This skill should be used when the user asks to "create a hook",
"add a PreToolUse hook", "validate tool use", "implement prompt-based hooks",
or mentions hook events (PreToolUse, PostToolUse, Stop).

❌ Bad:

description: Load when user needs hook help.

Cover Variations

Include different ways users might ask:

description: This skill should be used when the user asks to "create a skill",
"write a new skill", "add a skill to my plugin", "how do I create SKILL.md",
or mentions skill development, SKILL.md files, or skill best practices.

Include Domain Context

Mention relevant concepts and terminology:

description: This skill should be used when working with MCP servers,
mentions "add MCP integration", "configure stdio server", or discusses
Model Context Protocol, MCP tools, or server authentication.

Content Quality Standards

Writing Style

Use imperative form throughout:

"Create the file structure"
"Validate the syntax"
"Configure the server"

Never use second person:

❌ "You should create..."
❌ "You need to validate..."

Be objective and instructional:

Focus on what to do
Avoid opinionated language
Provide clear procedures

Organization

Structure SKILL.md with:

Overview (what and why)
Core concepts
Essential procedures
Quick references
Links to detailed resources

Use markdown features:

Headers (##, ###) for hierarchy
Bullet points for lists
Code blocks for examples
Tables for quick reference

Clarity

Make content actionable:

Provide step-by-step procedures
Include concrete examples
Show expected outputs
Reference supporting files

Avoid ambiguity:

Be specific about requirements
Define terms clearly
Provide complete examples
Note edge cases

Common Mistakes

Mistake 1: Weak Trigger Description

❌ Problem:

description: Provides guidance for skills.

Why: Vague, no specific triggers, not third person.

✅ Fix:

description: This skill should be used when the user asks to "create a skill",
"write SKILL.md", or mentions skill development, trigger phrases, or skill
structure.

Mistake 2: Bloated SKILL.md

❌ Problem:

SKILL.md has 8,000 words
All documentation in one file
Details always loaded into context

✅ Fix:

Keep SKILL.md at 1,500-2,000 words
Move detailed content to references/
Use progressive disclosure

Mistake 3: Second Person Writing

❌ Problem:

You should start by creating the directory.
You need to configure the settings.

✅ Fix:

Start by creating the directory.
Configure the settings before use.

Mistake 4: Missing Resource References

❌ Problem: SKILL.md doesn't mention references/ files.

✅ Fix:

## Additional Resources

### Reference Files
- **`references/structure-guide.md`** - Detailed structure standards
- **`references/trigger-patterns.md`** - Trigger phrase patterns

### Examples
- **`examples/good-skill.md`** - Example SKILL.md

Skill Anatomy

Minimal Skill

For simple knowledge without complex resources:

skill-name/
└── SKILL.md

Use when: Skill provides straightforward guidance, no utilities needed.

Standard Skill (Recommended)

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

Use when: Skill has detailed documentation or examples.

Complete Skill

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

Use when: Complex domain with utilities and comprehensive docs.

Quick Validation Checklist

Before finalizing a skill, verify:

Structure:

SKILL.md exists with valid YAML frontmatter
Frontmatter has name and description
Markdown body is substantial

Description:

Uses third person ("This skill should be used when...")
Includes specific trigger phrases
Lists concrete scenarios

Content:

Body uses imperative form (no "you should")
SKILL.md is lean (1,500-2,000 words)
Detailed content in references/

Resources:

Referenced files exist
Examples are complete
Scripts are executable

Progressive Disclosure:

Core content in SKILL.md
Details in references/
Code in examples/
Utilities in scripts/

Additional Resources

Reference Files

For comprehensive guidance on specific aspects:

references/structure-guide.md - Detailed structure and formatting standards
references/trigger-patterns.md - Trigger phrase optimization patterns
references/content-quality.md - Content quality checklist and standards
references/common-mistakes.md - Common mistakes and how to fix them

These references provide in-depth coverage of each topic with examples and patterns.

Examples

Study these skills as best practice examples:

plugin-dev/skills/hook-development/ - Progressive disclosure, utilities
plugin-dev/skills/agent-development/ - Strong triggers, references
plugin-dev/skills/skill-development/ - Meta-example (this skill)

Implementation Workflow

Follow these steps when creating a skill:

Understand Use Cases - Identify concrete examples
Plan Resources - Determine scripts/references/examples needed
Create Structure - Make directories and SKILL.md
Write SKILL.md - Frontmatter + lean body in imperative form
Add Resources - Create references/, examples/, scripts/
Validate - Check description, style, organization
Test - Verify skill triggers on expected queries
Iterate - Improve based on usage

Focus on strong trigger descriptions, progressive disclosure, and imperative writing to create effective skills that load when needed and provide targeted guidance.