Skill Protocol Mastery

This skill provides comprehensive guidance for creating, validating, and optimizing Agent Skills for Claude Code, based on the official Anthropic protocol specification and best practices.

Core Concepts

What Skills Are

Skills are modular packages that extend Claude's capabilities through:

• Specialized workflows for specific domains
• Tool integrations for file formats or APIs
• Domain expertise with company-specific knowledge
• Bundled resources (scripts, references, assets)

Progressive Disclosure Architecture

Skills use a three-level loading system:

Level	Content	When Loaded	Size Limit
1	Metadata (name + description)	Always	~100 words
2	SKILL.md body	When triggered	1,500-2,000 words
3	Bundled resources	As needed	Unlimited*

*Scripts execute without loading into context.

Skill Structure

Required Files

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter (name, description)
│   └── Markdown instructions
└── Bundled Resources (optional)
    ├── scripts/      - Executable utilities
    ├── references/   - Detailed documentation
    ├── examples/     - Working code samples
    └── assets/       - Templates, images, fonts

YAML Frontmatter Requirements

Validation Rules:

• name: 1-64 characters, pattern ^[a-z0-9-]+$, no reserved words
• description: 1-1024 characters, third-person, specific triggers

Template:

---
name: skill-identifier
description: This skill should be used when the user asks to "trigger phrase 1", "trigger phrase 2", "trigger phrase 3". Provides [capability description].
version: 1.0.0
---

Writing Style Requirements

Imperative/Infinitive Form (Required)

Write verb-first instructions, not second person:

✅ Correct:

To create a hook, define the event type.
Configure the MCP server with authentication.
Validate settings before use.

❌ Incorrect (second person - avoid):

[Second person] create a hook by defining the event type.
[Second person] configure the MCP server.
[Second person] validate settings before use.

Third-Person Descriptions (Required)

✅ Correct:

description: This skill should be used when the user asks to "create X"...

❌ Incorrect:

description: Use this skill when you want to create X...

Description Quality Patterns

Strong Trigger Phrases

Include exact phrases users would say:

# Good - specific triggers
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 - vague
description: Provides guidance for working with hooks.

Description Components

1. Third-person opener: "This skill should be used when..."
2. Specific triggers: "create X", "configure Y", "validate Z"
3. Context keywords: File types, domain terms, action verbs
4. Capability summary: What the skill provides

Content Organization

What Goes in SKILL.md

Include (always loaded when triggered):

• Core concepts and overview
• Essential procedures and workflows
• Quick reference tables
• Pointers to references/examples/scripts
• Most common use cases

Keep under 2,000 words, maximum 3,000 words

What Goes in references/

Move to references (loaded as needed):

• Detailed patterns and advanced techniques
• Comprehensive API documentation
• Migration guides and edge cases
• Extensive examples and walkthroughs

Each file can be 2,000-5,000+ words

What Goes in scripts/

Utility scripts for:

• Validation tools
• Testing helpers
• Parsing utilities
• Automation scripts

Must be executable and documented

Skill Creation Workflow

Step 1: Understand Use Cases

Gather concrete examples of skill usage:

• "What would a user say to trigger this skill?"
• "What functionality should this skill support?"
• "Can you give examples of how this skill would be used?"

Step 2: Plan Resources

Analyze examples to identify:

• Scripts for repetitive code
• References for detailed documentation
• Assets for templates and output files
• Examples for working demonstrations

Step 3: Create Structure

mkdir -p skills/skill-name/{references,examples,scripts}
touch skills/skill-name/SKILL.md

Step 4: Write SKILL.md

1. Create frontmatter with third-person description and triggers
2. Write lean body (1,500-2,000 words) in imperative form
3. Reference all supporting files clearly

Step 5: Validate

Run validation checklist (see references/validation-checklist.md)

Step 6: Iterate

Test with real usage, improve based on observations.

Quick Reference Templates

Minimal Skill

skill-name/
└── SKILL.md

Standard Skill (Recommended)

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

Complete Skill

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

Common Mistakes

Mistake	Problem	Solution
Weak triggers	Skill doesn't load	Add specific phrases users say
Second person	Inconsistent style	Use imperative form
Too much in SKILL.md	Context bloat	Move to references/
Missing references	Claude can't find details	Add resource pointers
Vague description	Poor discovery	Include concrete scenarios

Best Practices Summary

✅ DO:

• Use third-person in description
• Include specific trigger phrases
• Keep SKILL.md lean (1,500-2,000 words)
• Use progressive disclosure
• Write in imperative form
• Reference supporting files
• Provide working examples

❌ DON'T:

• Use second person anywhere
• Have vague trigger conditions
• Put everything in SKILL.md
• Leave resources unreferenced
• Skip validation

Additional Resources

Reference Files

For detailed guidance, consult:

• references/protocol-specification.md - Complete protocol spec
• references/validation-checklist.md - Full validation checklist
• references/json-schemas.md - Schema documentation

Example Files

Working examples in examples/:

• examples/minimal-skill/ - Simple skill template
• examples/standard-skill/ - Recommended structure
• examples/complete-skill/ - Full-featured skill

Utility Scripts

Validation tools in scripts/:

• scripts/validate-skill.py - Validate skill structure
• scripts/check-frontmatter.sh - Check YAML frontmatter

JSON Schemas

Validation schemas in assets/:

• assets/skill-schema.json - Complete skill schema
• assets/skill-frontmatter-schema.json - Frontmatter schema