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
4. •Skillfish Manager - Standard for distribution, installation, and management

Installation & Management

We recommend using skillfish to manage your skills. It handles installation across multiple agent environments (Claude, Cursor, etc.).

# Install skillfish globally
npm install -g skillfish

# Install a skill from a GitHub repository
skillfish add owner/repo

# Create a new skill structure
skillfish init

Cross-Platform Compatibility

Skills following this specification work across:

• •Claude Code (Anthropic)
• •Codex CLI (OpenAI)
• •Cursor (Anysphere)
• •Amp (Sourcegraph)
• •Letta (memGPT)

Non-compliant skills may break silently or fail validation on these platforms.

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

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

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

Semantic Versioning in Metadata

Standardize versioning using the metadata field:

metadata:
  version: "2.1.0"
  breaking-changes: "v2.0 changed API"

Triadic Classification (GF(3))

For plurigrid/asi skills, use triadic classification to balance verification vs generation:

metadata:
  trit: -1   # MINUS: verification, constraint, safety
  trit: 0    # ERGODIC: balance, mediation
  trit: +1   # PLUS: generation, exploration

Conservation: Σ trits ≡ 0 (mod 3) across compositions.

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:

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. •Initialize with Skillfish - Use skillfish init to scaffold standard 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. •Publish - Push to GitHub and use skillfish submit

Distribution

To make your skill installable via skillfish add owner/repo:

1. •Ensure your repository has a SKILL.md at the root, OR
2. •Place multiple skills in subdirectories (e.g., skills/my-skill/SKILL.md).

Users can then install:

# Install root skill
skillfish add your-username/your-repo

# Install specific skill from monorepo advice
skillfish add your-username/your-repo skill-name

Validation Commands

Ensure your skill is valid using these standard tools:

# Official validator (Standard)
skills-ref validate ./my-skill

# Codex-rs validator
python3 codex-rs/core/src/skills/assets/samples/skill-creator/scripts/quick_validate.py ./my-skill

# Batch validate
for d in skills/*/; do skills-ref validate "$d"; done

Utility Scripts

This skill includes two utility scripts in scripts/:

init_skill.py - Scaffold New Skills (Legacy)

[!NOTE] We recommend using skillfish init instead of this script for better compatibility.

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