Claude Code Skills — Meta Reference

This skill provides the definitive reference for creating, organizing, and maintaining Claude Code skills. Use this when building new skills or improving existing skill architecture.

Quick Reference

Skill Structure

skills/
└── skill-name/
    ├── SKILL.md           # Main reference (required)
    ├── README.md          # Usage notes (optional)
    ├── resources/         # Detailed docs
    │   ├── patterns.md
    │   └── examples.md
    ├── templates/         # Code templates
    │   └── starter.md
    └── data/
        └── sources.json   # External references

SKILL.md Template

---
name: skill-name
description: One-line description of what this skill provides and when to use it
---

# Skill Name — Quick Reference

Brief overview of the skill's purpose and value.

---

## Quick Reference

| Task | Tool/Method | When to Use |
|------|-------------|-------------|
| Task 1 | Tool A | Context for usage |

## When to Use This Skill

Claude should invoke this skill when a user requests:

- Use case 1
- Use case 2
- Use case 3

---

## Core Concepts

### Concept 1

Explanation with code example:

\`\`\`language
code example
\`\`\`

### Concept 2

Additional patterns...

---

## Navigation

**Resources**
- [resources/detailed-guide.md](resources/detailed-guide.md) — Extended documentation

**Related Skills**
- [../related-skill/SKILL.md](../related-skill/SKILL.md) — How it connects

Progressive Disclosure

Skills use progressive disclosure to optimize token usage:

Pattern: SKILL.md provides overview → Resources provide depth

When to Split Content

Frontmatter Specification

---
name: string          # Required: lowercase-kebab-case, matches folder name
description: string   # Required: One line, explains when Claude should use it
---

Name rules:

• Use kebab-case: ai-llm, not AI_LLM_Engineering
• Match folder name exactly
• Be specific: software-backend not backend

Description rules:

• Single line, under 200 characters
• Include key technologies/concepts
• End with context of when to use

Skill Categories

sources.json Schema

{
  "metadata": {
    "title": "Skill Name - Sources",
    "description": "Brief description",
    "last_updated": "YYYY-MM-DD",
    "skill": "skill-name"
  },
  "category_name": [
    {
      "name": "Resource Name",
      "url": "https://example.com/docs",
      "description": "What this covers",
      "add_as_web_search": true
    }
  ]
}

Categories should group logically:

• official_documentation
• tutorials
• community_resources
• tools_and_libraries

Quality Checklist

SKILL VALIDATION CHECKLIST

Frontmatter:
[ ] name matches folder name (kebab-case)
[ ] description is concise and actionable

Structure:
[ ] SKILL.md under 5K characters (progressive disclosure)
[ ] resources/ for detailed content
[ ] data/sources.json with curated links

Content:
[ ] Quick reference table at top
[ ] "When to Use" section present
[ ] Code examples are copy-paste ready
[ ] Related skills linked at bottom

Quality:
[ ] >40% operational content (code, tables, checklists)
[ ] <50% prose paragraphs
[ ] All URLs are live (no 404s)
[ ] Sources updated within 6 months

Multi-Tech vs Single-Tech Skills

Single-Tech Skill

software-backend/
├── SKILL.md              # Node.js focus
└── resources/
    └── nodejs-patterns.md

Multi-Tech Skill

software-backend/
├── SKILL.md              # Overview + decision tree
├── resources/
│   ├── nodejs-patterns.md
│   ├── go-patterns.md
│   ├── rust-patterns.md
│   └── python-patterns.md
└── templates/
    ├── nodejs/
    ├── go/
    ├── rust/
    └── python/

Navigation

Resources

• resources/skill-patterns.md — Common skill patterns
• resources/skill-validation.md — Validation criteria
• data/sources.json — Official documentation links

Related Skills

• ../claude-code-agents/SKILL.md — Agent creation
• ../claude-code-commands/SKILL.md — Command creation
• ../claude-code-hooks/SKILL.md — Hook automation