Skill Mastery: The Ultimate Guide

Combines three authoritative sources into a unified approach:

1. Official plugin-dev toolkit - Validation, patterns, AI-assisted creation
2. Community best practices - Token hierarchy, archetypes, advanced patterns
3. Official documentation - Current API fields, latest features

Mental Model: How Skills Actually Work

Skills use pure LLM reasoning for selection - no embeddings or keyword matching. Claude evaluates all skill descriptions via natural language understanding, making description quality critical.

Token Loading Hierarchy

Level 1: Metadata (~100 tokens)        Always loaded at startup
         name + description in system prompt
                    ↓
Level 2: SKILL.md (~1,500-5,000 tokens) Loaded when skill triggers
         Full instructions after selection
                    ↓
Level 3: Resources (unlimited)          Loaded on-demand only
         scripts/, references/, assets/
         Zero cost until accessed

Key insight: Only Level 1 costs tokens in every conversation. Design accordingly.

Quick Start: Creating a Skill

1. Choose Your Archetype

Archetype	Best For	Structure
CLI Reference	Tool documentation (git, gcloud)	Pure reference, minimal prose
Methodology	Workflows, processes	Philosophy + THE EXACT PROMPT + examples
Safety Tool	Validation, security	Threat model + risk tiers + what blocks/allows
Orchestration	Multi-agent coordination	Quick start + robot mode APIs + integrations

See references/archetypes.md for detailed templates.

2. Write the Description (Most Critical)

Rules:

• Third person always ("Processes files" not "I help you")
• Include WHAT it does AND WHEN to trigger
• Specific trigger phrases users would say
• Max 1024 characters

Template:

description: >-
  [What it does - actions, capabilities].
  Use when [trigger phrases, contexts, file types, user intents].

Good examples:

# Specific + triggers
description: >-
  Extract text and tables from PDF files, fill forms, merge documents.
  Use when working with PDF files or when user mentions PDFs, forms,
  or document extraction.

# Action + context
description: >-
  Generate descriptive commit messages by analysing git diffs.
  Use when user asks for help writing commit messages or reviewing
  staged changes.

3. Structure with Progressive Disclosure

skill-name/
├── SKILL.md              # Core guidance (<500 lines, ~2,000 words)
├── references/           # Detailed docs (loaded on-demand)
│   ├── api.md
│   └── patterns.md
├── examples/             # Working code samples
│   └── complete-example.md
└── scripts/              # Executable utilities (run, not loaded)
    └── validate.py

Critical rules:

• Keep references ONE level deep from SKILL.md
• No chains: SKILL.md -> advanced.md -> details.md (Claude may partial-read)
• Long files (>100 lines): include TOC at top

4. Write the Body

Style:

• Imperative/infinitive form (verb-first): "Extract the data", "Run validation"
• NOT second person: avoid "You should extract..."
• Concise - assume Claude is intelligent
• Challenge each line: "Does Claude need this?"

Bad (~150 tokens):

PDF (Portable Document Format) files are a common file format that
contains text, images, and other content. To extract text from a PDF,
you'll need to use a library. There are many libraries available...

Good (~50 tokens):

## Extract PDF text
Use pdfplumber:
python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()

Required Frontmatter Fields

Field	Required	Constraints
name	Yes	Max 64 chars, [a-z0-9-] only, no "anthropic"/"claude"
description	Yes	Max 1024 chars, non-empty, no XML tags

Optional Frontmatter Fields

Field	Purpose	Example
allowed-tools	Limit tool access	Read, Grep, Glob
model	Specific model	claude-sonnet-4-20250514
context	Isolation	fork for separate context
agent	Subagent type	Explore, Plan, custom
hooks	Lifecycle events	PreToolUse, PostToolUse, Stop
user-invocable	Slash menu visibility	false to hide
disable-model-invocation	Block Skill tool	true to prevent programmatic use

See references/api-reference.md for complete field documentation.

Degrees of Freedom

Match specificity to task fragility:

Freedom	When	Example
High	Multiple valid approaches	Code review guidelines
Medium	Preferred pattern exists	Report templates
Low	Fragile/error-prone	DB migration scripts - exact command

Analogy: Narrow bridge with cliffs = low freedom (exact guardrails). Open field = high freedom (general direction).

Advanced Patterns

THE EXACT PROMPT Pattern

For reproducible prompts in agent-to-agent handoff:

## THE EXACT PROMPT - Plan Review

Carefully review this entire plan and provide revisions for
better architecture, new features, edge cases...

Copy-paste ready, automation friendly, no ambiguity.

Validation Loop Pattern

## Validation workflow

1. Make edits
2. **Validate immediately**: python scripts/validate.py output/
3. If validation fails:
   - Review error message
   - Fix issues
   - Run validation again
4. **Only proceed when validation passes**

Risk Tiering Pattern

For safety-critical skills:

Tier	Approvals	Auto-approve	Examples
CRITICAL	2+	Never	rm -rf /, DROP DATABASE
DANGEROUS	1	Never	git reset --hard
CAUTION	0	After 30s	rm file.txt

See references/advanced-patterns.md for more patterns.

Anti-Patterns to Avoid

Anti-Pattern	Why Bad	Fix
Windows paths (scripts\helper.py)	Breaks on Unix	Forward slashes
Deeply nested references	Partial reads	One level deep
Too many options	Confusing	Default + escape hatch
Vague descriptions	Never triggers	Specific + triggers
Magic numbers	Unverifiable	Document why

Workflow: Creating Your Skill

1. Identify the archetype - CLI, methodology, safety, or orchestration?
2. Write description first - This determines if skill ever triggers
3. Initialise with script - Use init_skill.py to scaffold structure
4. Draft SKILL.md - Core guidance only (<500 lines)
5. Extract to references - Detailed docs, API specs, schemas
6. Add examples - Working code that demonstrates usage
7. Create scripts - Utilities that execute (not load into context)
8. Test with fresh instance - Does it trigger? Apply rules correctly?
9. Validate - Use skill-reviewer or plugin-validator agents
10. Package for distribution - Use package_skill.py to create zip

Utility Scripts

This skill includes two utility scripts in scripts/:

init_skill.py - Scaffold New Skills

python scripts/init_skill.py <skill-name> --path <location>

# Examples:
python scripts/init_skill.py my-api-helper --path ~/.claude/skills
python scripts/init_skill.py database-tool --path .claude/skills

Creates a complete skill directory structure:

• SKILL.md with template and TODO placeholders
• scripts/ directory with example script
• references/ directory with example reference
• assets/ directory for output files

package_skill.py - Create Distributable Zip

python scripts/package_skill.py <path/to/skill> [output-dir]

# Examples:
python scripts/package_skill.py ~/.claude/skills/my-skill
python scripts/package_skill.py ./my-skill ./dist

Validates the skill and creates a distributable zip file:

• Checks frontmatter format and required fields
• Validates naming conventions
• Ensures no TODO placeholders remain
• Excludes __pycache__ and .pyc files

Integration with Plugin-Dev

This skill works alongside the official plugin-dev toolkit (requires plugin-dev@claude-plugins-official):

• Use /plugin-dev:create-plugin for full plugin creation workflow
• Use plugin-dev:skill-reviewer agent for quality validation
• Use plugin-dev:plugin-validator agent for comprehensive checks

Quick Reference Card

SKILL CHECKLIST
===============
[ ] name: lowercase, hyphens, ≤64 chars
[ ] description: third person, specific triggers, ≤1024 chars
[ ] SKILL.md body: <500 lines
[ ] References: one level deep
[ ] Long refs: include TOC
[ ] Scripts: tested, explicit error handling
[ ] Forward slashes only
[ ] Consistent terminology
[ ] Examples concrete, not abstract
[ ] Tested with real scenarios

DESCRIPTION TEMPLATE
====================
description: >-
  [What it does - actions, capabilities].
  Use when [trigger phrases, contexts, file types].

Further Reading

• Token Hierarchy Deep Dive
• Skill Archetypes
• Advanced Patterns
• Official API Reference