Skill Design Skill

This meta-skill teaches you how to design excellent Claude Code skills. Skills are unique among Claude Code components - they provide progressive knowledge disclosure and guidance that loads when relevant.

Fundamentals

Everything in this skill is built on top of the box-factory-architecture skill. Load that first!

Workflow Selection

Creating a skill? Start with skill-md.md for the template and quality checklist. Traverse when: writing any SKILL.md file, validating before completion.

Official Documentation

Fetch the official skills documentation for current syntax and features:

• https://code.claude.com/docs/en/skills - Official skills documentation

Core Understanding

Skills Are Progressive Knowledge Disclosure

Key insight: Skills solve the "you can't put everything in the system prompt" problem.

Base Prompt (always loaded)
    ↓
Topic becomes relevant
    ↓
Skill loads automatically
    ↓
Provides specialized knowledge

• Without skills: Important knowledge buried in long prompts or forgotten
• With skills: Knowledge loads automatically when topics become relevant
• Value proposition: Right information at the right time, without token bloat

Decision test: Does this information need to be available across multiple contexts, but not always?

Skills vs System Prompts vs Memory (eg CLAUDE.md)

The Knowledge Delta Principle

Critical: Skills should only document what Claude doesn't already know.

Claude's training includes common tools, standard workflows, and general best practices. Skills that duplicate this waste tokens.

Deep dive: knowledge-delta.md - Full include/exclude criteria with decision test. Traverse when: deciding what content to include, reviewing for bloat. Skip when: clear user-specific content, already understand delta principle.

Quick test: Would Claude get this wrong without the skill? If no, don't include it.

The Box Factory Philosophy

1. Low-Maintenance by Design

Point to official documentation for details Claude might not know:

## Official Documentation

For syntax details or recent changes, fetch:

- **https://code.claude.com/docs/en/skills** - Skills documentation

Why: Documentation changes; skills that defer stay valid.

Critical nuance - doc fetching depends on knowledge reliability:

Don't hardcode:

• Model names, tool lists, version-specific syntax

Do reference:

• Official docs via WebFetch instructions

2. Two-Layer Approach

Layer 1: Official Specification

• What the docs explicitly say
• Required fields and syntax
• Mark accordingly: (Official Specification)

Layer 2: Best Practices or User Preference

• What the docs don't emphasize
• Common gotchas and anti-patterns
• Mark accordingly: ## X (Best Practices)

Example:

<!-- Official specification lists the `description` field is optional and defaults to first line. -->
## Description Field Design (Best Practices)

Always include `description` even though it's optional - improves discoverability.

3. Evidence-Based Recommendations

All claims must be:

• Grounded in official documentation, OR
• Clearly marked as opinionated best practices, OR
• Based on documented common pitfalls

Avoid: Presenting opinions as official requirements.

Deep dive: common-pitfalls.md - Catalog of anti-patterns with symptoms and fixes. Traverse when: reviewing skills, debugging why a skill isn't working, checking for common mistakes. Skip when: creating new skill from scratch, following patterns above.

When to Create Skills

Skill vs Other Components

For the full decision framework on choosing between Skills, Agents, Commands, Hooks, and Memory, load the box-factory-architecture skill.

Quick test: Is this knowledge that shapes behavior, or work to be done?

• Knowledge → Skill
• Work → Agent

Scope Guidelines

Good skill scope:

• Focused on single domain
• Self-contained knowledge
• Clear boundaries
• Composable with other skills

Bad skill scope:

• "Everything about development" (too broad)
• Just 3-4 bullet points (put in CLAUDE.md)
• Project-specific details (put in CLAUDE.md)

File Structure

Skills live in subdirectories within skills/:

plugin-name/
├── skills/
│   ├── skill-one/
│   │   ├── SKILL.md          # Required (uppercase)
│   │   ├── some-topic.md     # Optional subfiles (any name)
│   │   └── another-topic.md
│   └── skill-two/
│       └── SKILL.md

Only SKILL.md has a required name. Subfiles can use any descriptive names.

Deep dive: skill-structure.md - Complete folder layouts, splitting guidance, navigation table patterns. Traverse when: structuring complex skills, deciding subfile organization, adding scripts or assets. Skip when: simple single-file skill, basic structure questions answered above.

Documentation References

Official documentation:

• https://code.claude.com/docs/en/skills - Official skills documentation

This skill demonstrates its own patterns: routes to subfiles for reference content, keeps the main file focused on philosophy, and defers to official docs.