Skill Mastery: The Ultimate Guide

Combines three authoritative sources into a unified approach:

• Official plugin-dev toolkit - Validation, patterns, AI-assisted creation

• Community best practices - Token hierarchy, archetypes, advanced patterns

• 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

• Identify the archetype - CLI, methodology, safety, or orchestration?

• Write description first - This determines if skill ever triggers

• Initialise with script - Use init_skill.py to scaffold structure

• Draft SKILL.md - Core guidance only (<500 lines)

• Extract to references - Detailed docs, API specs, schemas

• Add examples - Working code that demonstrates usage

• Create scripts - Utilities that execute (not load into context)

• Test with fresh instance - Does it trigger? Apply rules correctly?

• Validate - Use skill-reviewer or plugin-validator agents

• 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