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

Cross-Platform: Agent Skills standard adopted by Claude Code, Codex CLI, Gemini CLI, and VS Code Copilot. Skills are portable across platforms.

Skill Structure

skills/
└── skill-name/
    ├── SKILL.md           # Main reference (required)
    ├── scripts/           # Executable code (Python/Bash) - runs, not loaded
    │   └── validate.py
    ├── references/        # Documentation loaded into context on-demand
    │   ├── patterns.md
    │   └── examples.md
    ├── assets/            # Files for OUTPUT (templates, icons, fonts)
    │   └── template.html
    └── data/
        └── sources.json   # External references

Directory purposes:

• scripts/ – Executable code; output consumed, code never loads into context
• references/ – Documentation loaded into context when the agent needs it
• assets/ – Files used in generated output (not loaded into context)

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

The assistant 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**
- [references/skill-patterns.md](references/skill-patterns.md) - Common patterns
- [references/skill-validation.md](references/skill-validation.md) - Validation criteria

**Related Skills**
- [../claude-code-agents/SKILL.md](../claude-code-agents/SKILL.md) - Agent creation

Progressive Disclosure

Skills use progressive disclosure to optimize token usage:

Pattern: SKILL.md provides overview -> Resources load only when needed

Limits: Keep SKILL.md under 500 lines (<5K tokens)

When to Split Content

Frontmatter Specification

---
name: string                        # Required: lowercase-kebab-case, matches folder name
description: string                 # Required: PRIMARY trigger mechanism (50-300 chars)
disable-model-invocation: boolean   # Optional: Only user can invoke (for /deploy, /commit)
user-invocable: boolean             # Optional: false = background knowledge only
---

Name rules:

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

Description rules (PRIMARY TRIGGER):

• Description is the primary triggering mechanism – the runtime uses it to decide when to invoke
• Include “when to use” context HERE, not in the body
• Single line, 50-300 characters
• Include key technologies/concepts as trigger keywords

Optional frontmatter:

• disable-model-invocation: true – Only user can invoke (for workflows with side effects: /commit, /deploy, /send-slack)
• user-invocable: false – Not user-invocable (background knowledge only; runtime-dependent)

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 500 lines (split into references/ if needed)
[ ] references/ 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
└── references/
    └── nodejs-patterns.md

Multi-Tech Skill

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

Navigation

Resources

• references/skill-patterns.md – Common skill patterns
• references/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