Agent Skills - Meta Reference

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

Quick Reference

Component Purpose Required

SKILL.md

Main reference file with frontmatter Yes

scripts/

Executable code (prefer running) Optional

references/

Documentation (loaded on-demand) Recommended

assets/

Output files (templates, icons) Optional

data/sources.json

Curated external links Recommended

Cross-Platform: Agent Skills are designed to be portable across runtimes (Claude Code, Codex CLI, Gemini CLI, VS Code Copilot).

Skill Structure

skills/ └── skill-name/ ├── SKILL.md # Main reference (required) ├── scripts/ # Executable code (Python/Bash) - prefer running; read only to patch/review │ └── 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; prefer running scripts and consuming output (read only when you need to modify/review)

• references/

• Documentation loaded into context when the agent needs it

• assets/

• Files used in generated output (not loaded into context)

Notes:

• Prefer executing scripts instead of pasting large code into context; read scripts only when you need to modify or review them.

SKILL.md Template

name: skill-name description: One-line description of what this skill provides and when to use it (include trigger keywords here)

Skill Name - Quick Reference

Brief overview of the skill's purpose and value.

Quick Reference

Scope (Optional)

Keep this brief; the primary trigger mechanism is the frontmatter description.

Core Concepts

Concept 1

Explanation with code example:

```language code example ```

Concept 2

Additional patterns...

Navigation

Resources

• references/skill-patterns.md - Common patterns
• references/skill-validation.md - Validation criteria

Related Skills

• ../agents-subagents/SKILL.md - Agent creation

Progressive Disclosure

Skills use progressive disclosure to optimize token usage:

Layer Content Token Cost

Discovery Name + description only ~50 tokens

Activation Full SKILL.md body 2K-5K tokens

Execution scripts/, references/, assets/ On-demand

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

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

When to Split Content

Keep in SKILL.md Move to references/

Decision trees Full API references

Quick commands Step-by-step tutorials

Common patterns Edge case handling

1-2 code examples Complete implementations

Frontmatter Specification

Field Type Required Purpose

name

string Yes Kebab-case, must match folder name

description

string Yes Primary trigger — runtime reads this to decide invocation

argument-hint

string No Autocomplete hint shown in / menu (e.g. [issue-number] )

disable-model-invocation

bool No true prevents auto-triggering; user must invoke with /

user-invocable

bool No false hides from / menu; still loads as background context

allowed-tools

string No Comma-separated tool allowlist (e.g. Read, Grep, Glob )

context

string No Set to fork to run skill body in a subagent

agent

string No Subagent type when context: fork (e.g. Explore , Plan )

model

string No Model override (opus , sonnet , haiku )

hooks

object No Lifecycle hooks scoped to this skill

license

string No License identifier

compatibility

string No Platform/version notes (1-500 chars)

metadata

object No Author, version, mcp-server

See references/frontmatter-reference.md for full specification, examples, and string substitutions.

Name rules:

• Use kebab-case: ai-llm , not AI_LLM_Engineering

• Match folder name exactly

• Be specific: software-backend not backend

• No claude or anthropic in names (reserved words)

• No XML angle brackets (<

) in any frontmatter value

Description rules (PRIMARY TRIGGER):

• The runtime uses descriptions to decide which skills to auto-invoke

• Format: [What it does]. Use when [trigger phrases].

• Target ~150 chars when library has 50+ skills (budget: 2% of context window, ~16K chars shared across ALL skill descriptions)

• Include key technologies/concepts as trigger keywords

• Single-line YAML only — no multiline >-

String substitutions (usable in skill body):

• $ARGUMENTS / $ARGUMENTS[N] / $N — user-provided arguments from /skill-name arg1 arg2

• ${CLAUDE_SESSION_ID} — current session identifier

• ${CLAUDE_SKILL_DIR} — absolute path to this skill's directory

Dynamic context injection: Use !command in the skill body to inject command output at load time.

Skill Categories

Category Prefix Examples

AI/ML ai-

ai-llm , ai-ml-data-science

Software software-

software-backend , software-frontend

Operations ops-

ops-devops-platform

Data data-

data-lake-platform , data-sql-optimization

Quality qa-

qa-debugging , qa-docs-coverage

Developer Tools dev-

dev-api-design , dev-git-commit-message , dev-workflow-planning

Product product-

product-management , docs-ai-prd

Document document-

document-pdf , document-xlsx

Testing testing- , qa-testing-

qa-testing-playwright , qa-testing-strategy

Marketing marketing-

marketing-social-media , marketing-seo

Agents/Tools agents-

agents-subagents , agents-skills , agents-hooks

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 [ ] Frontmatter description includes trigger keywords [ ] 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/anthropic-skills-guide.md - Anthropic's official skill-building guide (distilled)

• references/frontmatter-reference.md - Complete frontmatter field specification

• references/skill-patterns.md - Common skill patterns

• references/skill-validation.md - Validation criteria

• data/sources.json - Official documentation links

Related Skills

• ../agents-subagents/SKILL.md - Agent creation

• ../agents-hooks/SKILL.md - Hook automation

• ../agents-mcp/SKILL.md - MCP server integration

Fact-Checking

• Use web search/web fetch to verify current external facts, versions, pricing, deadlines, regulations, or platform behavior before final answers.

• Prefer primary sources; report source links and dates for volatile information.

• If web access is unavailable, state the limitation and mark guidance as unverified.