---

name: skill-mastery description: >- Provides master-level guidance for creating exceptional Claude Code skills using combined best practices from official plugin-dev toolkit, community patterns, and latest API. Use when creating skills, designing skill architecture, writing skill descriptions, planning progressive disclosure, choosing skill archetypes, optimising token efficiency, or when user says "create a skill", "skill best practices", "skill description help", "token-efficient skill". user-invocable: false

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

CopyLevel 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

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:

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

Good examples:

Copy# 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

Copyskill-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):

CopyPDF (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):

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

Required Frontmatter Fields

Optional Frontmatter Fields

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

Degrees of Freedom

Match specificity to task fragility:

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:

Copy## 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

Copy## 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:

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

Anti-Patterns to Avoid

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

Copypython 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

Copypython 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

CopySKILL 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