name: 1-64 chars, lowercase + hyphens, match directory
description: 1-1024 chars, ≤60 words, explain WHAT and WHEN
Use WHEN: with quoted trigger phrases (preferred over USE FOR:)
Avoid DO NOT USE FOR: unless the skill has trigger overlap with a broader skill (see frontmatter guidelines)
Use inline double-quoted strings (not >- folded scalars)
SKILL.md: <500 tokens (soft), <5000 (hard)
references/*.md: <1000 tokens each

Structure

SKILL.md (required) - Instructions
references/ (optional) - Detailed docs
scripts/ (optional) - Executable code

Frontmatter: name (lowercase-hyphens), description (WHAT + WHEN)

Progressive Disclosure

Metadata (~100 tokens) loads at startup. SKILL.md (<5000 tokens) loads on activation. References load only when explicitly linked (not on activation). Keep SKILL.md lean.

Reference Loading

References are JIT (just-in-time) loaded:

Only files explicitly linked via [text](references/file.md) load
Link to files, not folders - [Recipes](references/recipes/README.md) not [Recipes](references/recipes/)
Each file loads in full (not sections)
No caching between requests - write self-contained files
Use recipes/services patterns for multi-option skills

See REFERENCE-LOADING.md for details.

Validation

# Run from the scripts directory
cd scripts
npm run references              # Validate all skill links
npm run tokens -- check         # Check token limits

Integrity Checks

When reviewing or authoring skills, verify:

No broken links - All referenced files exist
No orphaned references - All reference files are linked
Token budgets - References under 1000 tokens (split if exceeded)
No duplicates - Consolidate repeated content
No out-of-place guidance - Service-specific content belongs in service-specific references

See Validation for detailed procedures.

Reference Documentation

Guidelines - Detailed writing guidelines
Token Budgets - Limits and splitting guidance
Reference Loading - How references load
Checklist - Pre-submission checklist
Validation - Link and reference validation
agentskills.io/specification - Official spec

skill-authoring

Skill Authoring Guide

When to Use

Constraints