claude-mods/templates/SKILL.template.md

Skill Template

Official specification: https://agentskills.io/specification

Frontmatter Reference

---
# ┌─────────────────────────────────────────────────────────────────────────────┐
# │ REQUIRED FIELDS                                                              │
# └─────────────────────────────────────────────────────────────────────────────┘

name: my-skill-name
# - 1-64 characters
# - Lowercase letters, numbers, and hyphens only
# - Must NOT start or end with a hyphen
# - Examples: "code-review", "git-workflow", "api-client"

description: "Clear description of what this skill does and when Claude should use it."
# - Max 1024 characters
# - Must be non-empty
# - Should answer: What does it do? When should it activate?
# - Include trigger phrases for discoverability

# ┌─────────────────────────────────────────────────────────────────────────────┐
# │ OPTIONAL FIELDS                                                              │
# └─────────────────────────────────────────────────────────────────────────────┘

license: MIT
# - Licensing terms for the skill
# - Keep brief (e.g., "MIT", "Apache-2.0", "Proprietary")

compatibility: "Requires Node.js 18+, macOS/Linux only"
# - Max 500 characters
# - Only include if skill has specific environment requirements
# - Omit if skill works everywhere

metadata:
  author: "Your Name"
  version: "1.0.0"
  tags: ["git", "workflow", "automation"]
# - Key-value mapping for custom properties
# - Not defined by spec - use for your own tracking

allowed-tools: "Bash Read Write Glob Grep"
# - Space-delimited list of pre-approved tools
# - EXPERIMENTAL: May change in future spec versions
# - Use when skill requires specific tool access
---

Progressive Disclosure

Skills load content in stages to minimize context consumption:

Level	Content	When Loaded	Token Budget
Metadata	name + description	Startup (all skills)	~100 tokens
Instructions	SKILL.md body	Skill activated	<5000 tokens
Resources	references/, scripts/, assets/	On-demand	As needed

When to Split Content

SKILL.md Size	Action
< 150 lines	Keep as single file
150-300 lines	Consider extracting reference tables
300+ lines	Must split - extract to references/

Directory Structure

Simple Skill (<150 lines)

my-skill/
└── SKILL.md

Medium Skill (150-300 lines)

my-skill/
├── SKILL.md
└── references/
    └── REFERENCE.md         # Extended patterns

Complex Skill (300+ lines)

my-skill/
├── SKILL.md                    # Core only (<300 lines)
├── references/
│   ├── REFERENCE.md            # Primary reference
│   ├── {lang}-patterns.md      # Language-specific
│   └── {domain}-examples.md    # Domain-specific
├── scripts/                    # Optional
│   └── helper.{sh,py,js}
└── assets/                     # Optional
    └── template.{json,yaml}

Content Migration Rules

What Stays in SKILL.md

• Frontmatter (name, description, compatibility, allowed-tools)
• Purpose/Overview (1-3 sentences)
• Activation triggers (when to use)
• Top 10 most-common patterns (essential use cases)
• Quick reference table
• "Additional Resources" section linking to references/

What Moves to references/

Content Type	Destination
Complete pattern lookup tables	references/REFERENCE.md
Language-specific patterns	references/{lang}-patterns.md
Framework-specific patterns	references/{framework}-patterns.md
Domain-specific examples	references/{domain}-examples.md
Edge cases and gotchas	references/REFERENCE.md

What Goes in scripts/

Content Type	Destination
Reusable shell scripts	scripts/{name}.sh
Python helper utilities	scripts/{name}.py
Node.js helpers	scripts/{name}.js

What Goes in assets/

Content Type	Destination
JSON/YAML templates	assets/{name}.template.{ext}
Schema definitions	assets/{name}.schema.json
Example configs	assets/example-{name}.{ext}

File Naming Conventions

Location	Convention	Example
references/ primary	REFERENCE.md	references/REFERENCE.md
references/ language	{lang}-patterns.md	references/python-patterns.md
references/ domain	{domain}-examples.md	references/k8s-examples.md
scripts/	{action}.{ext}	scripts/validate.sh
assets/ templates	{name}.template.{ext}	assets/server.template.py
assets/ schemas	{name}.schema.json	assets/tool.schema.json

Reference Loading Pattern

Add this section to SKILL.md files with supporting references:

## Additional Resources

For detailed patterns, load:

- `./references/REFERENCE.md` - Complete pattern library
- `./references/{domain}-patterns.md` - Domain-specific examples

Minimum Compliant Skill

---
name: example-skill
description: "Brief description of skill purpose and activation triggers."
---

# Example Skill

Instructions for Claude to follow when this skill is active.

## Usage

Step-by-step instructions with examples.

## Examples

- Example input → expected output
- Another example scenario

Recommended Structure

---
name: my-skill
description: "What it does. Triggers on: keyword1, keyword2, action phrases."
compatibility: "Requires tool-x. Install: brew install tool-x"
allowed-tools: "Bash Read"
---

# Skill Name

Brief purpose statement.

## Essentials

Top 10 most-common patterns (inline).

## Quick Reference

| Task | Command |
|------|---------|
| Common task 1 | `command` |
| Common task 2 | `command` |

## When to Use

- Use case 1
- Use case 2

## Additional Resources

For complete patterns, load:
- `./references/REFERENCE.md` - Extended patterns

Validation Checklist

• name is 1-64 chars, lowercase + numbers + hyphens only
• name does not start or end with hyphen
• description is non-empty and under 1024 chars
• description explains what AND when
• SKILL.md under 300 lines (target for progressive disclosure)
• Top 10 essential patterns inline, rest in references/
• All file references use relative paths (./references/)
• No nested directories (one level deep only)
• Works without loading references (basic cases)
• Optional fields only included if needed

Backwards Compatibility

Skills must remain functional even if supporting files are missing:

1. SKILL.md is self-contained for basic use cases
2. Top 10 patterns stay inline (no reference file required)
3. Quick reference table always in SKILL.md
4. References are additive, not required
5. Graceful degradation if reference files missing