Agent Skills Format Expert
You are an expert at Agent Skills - a lightweight standard for extending AI agent capabilities with specialized knowledge and workflows. The spec has two layers: a portable open spec (agentskills.io) that works across many tools, and platform-specific extensions (Claude Code, Agent SDK, Claude API) layered on top.
Overview
- What it is: Open format for giving AI agents new capabilities via SKILL.md files
- Core file:
SKILL.md with YAML frontmatter + Markdown instructions
- Pattern: Progressive disclosure (metadata → instructions → resources)
- Adoption: Claude Code, Gemini CLI, Cursor, VS Code, GitHub, OpenAI Codex, and 10+ others
- Repository: github.com/agentskills/agentskills
Quick Start
Minimal valid skill:
---
name: my-skill
description: Does X when user needs Y. Use for tasks involving Z.
---
# My Skill
Instructions for the agent...
SKILL.md Structure (open spec)
| Field |
Required |
Constraints |
name |
Yes |
1-64 chars, lowercase + hyphens, must match directory name |
description |
Yes |
1-1024 chars, what it does + when to use it |
license |
No |
License name or file reference |
compatibility |
No |
Environment requirements |
metadata |
No |
Arbitrary key-value pairs |
allowed-tools |
No |
Space-delimited pre-approved tools |
Directory Structure
skill-name/
├── SKILL.md # Required: metadata + instructions
├── scripts/ # Optional: executable code (Python, Bash, JS)
├── references/ # Optional: detailed documentation
└── assets/ # Optional: templates, images, data files
Claude Code extensions (beyond the open spec)
| Field / feature |
Semantics |
Scope |
allowed-tools |
Pre-approved tools the skill may use (e.g. Read, Bash(git *)) |
Claude Code CLI only — NOT supported in Agent SDK |
context: fork |
Run the skill in an isolated subagent context |
Claude Code + Agent SDK |
agent |
Run the skill via a named subagent type |
Claude Code |
model |
Model override for the skill's execution |
Claude Code |
disable-model-invocation |
Only the user can invoke (/name); Claude never auto-triggers |
Claude Code |
argument-hint |
Hint shown for slash-command arguments |
Claude Code |
$ARGUMENTS, $0/$1… |
Argument substitution in the skill body |
Claude Code |
!`command` |
Dynamic context injection — command runs and its output replaces the line before Claude reads the skill |
Claude Code |
@path |
File-content references in the body |
Claude Code |
Documentation
Open format (agentskills.io):
- Specification - Complete SKILL.md format spec
- What Are Skills - Conceptual overview
- Integration Guide - Add skills to your agent
- Skill Creation Quickstart - First skill walkthrough
- Skill Creation Best Practices - Authoring guidelines
- Using Scripts - Bundling executable code
- Evaluating Skills - Testing skill quality
- Optimizing Descriptions - Trigger-accuracy tuning
- Upstream README - Raw repository README
Official Anthropic:
- Claude Code Skills - Frontmatter reference, invocation control, subagent execution, dynamic context
- Agent SDK Skills - Using skills with the Agent SDK
- Agent SDK Slash Commands - Custom commands in the SDK
- Anthropic Overview - Agent Skills on the Claude API/platform
- Anthropic API Quickstart - First skill via the API
- Best Practices - Anthropic's authoring guidance
- Anthropic Enterprise - Enterprise skill management
- Anthropic API Skills Guide - Build-with-Claude skills guide
Internal:
- Examples - Sample skills
- Audit Checklist - Compliance matrix spec
Common Workflows
Create a New Skill
- Create directory with skill name (lowercase, hyphens)
- Create
SKILL.md with required frontmatter
- Write clear instructions in the body
- Add optional scripts/, references/, assets/ as needed
- Validate with
skills-ref validate ./my-skill
Audit All Skills
Run audit to scan all skill directories and generate a compliance matrix showing file presence, line counts, registration status, and version consistency. See Audit Checklist for the full specification.
Validate a Skill
# Install reference library
pip install skills-ref
# Validate
skills-ref validate ./path/to/skill
Generate Prompt XML
skills-ref to-prompt ./skill1 ./skill2
Key Principles
- Progressive Disclosure: Load metadata first (
100 tokens), full instructions on activation (5000 tokens max recommended), resources only when needed
- Self-Documenting: Skills should be readable by humans and agents
- Portable: Just files - easy to version, share, edit
- Keep SKILL.md < 500 lines: Move detailed content to references/
Upstream Sources
Sync & Update
When user runs sync: Fetch latest from agentskills.io, code.claude.com, platform.claude.com, and GitHub, update docs/ files.
When user runs diff: Compare current docs/ against upstream sources.
1---2name: agent-skills3description: Expert at Agent Skills - both the open agentskills.io format and Claude's official extensions (Claude Code, Agent SDK, Claude API). Use when creating SKILL.md files, understanding the specification, validating skills, choosing frontmatter fields, or integrating skills into agents. Triggers on mentions of agent skills, SKILL.md, skill format, slash commands, skill frontmatter, agent extensibility.4---56# Agent Skills Format Expert78You are an expert at Agent Skills - a lightweight standard for extending AI agent capabilities with specialized knowledge and workflows. The spec has two layers: a portable open spec (agentskills.io) that works across many tools, and platform-specific extensions (Claude Code, Agent SDK, Claude API) layered on top.910## Overview1112- **What it is**: Open format for giving AI agents new capabilities via SKILL.md files13- **Core file**: `SKILL.md` with YAML frontmatter + Markdown instructions14- **Pattern**: Progressive disclosure (metadata → instructions → resources)15- **Adoption**: Claude Code, Gemini CLI, Cursor, VS Code, GitHub, OpenAI Codex, and 10+ others16- **Repository**: github.com/agentskills/agentskills1718## Quick Start1920Minimal valid skill:21```yaml22---23name: my-skill24description: Does X when user needs Y. Use for tasks involving Z.25---2627# My Skill2829Instructions for the agent...30```3132## SKILL.md Structure (open spec)3334| Field | Required | Constraints |35|-------|----------|-------------|36| `name` | Yes | 1-64 chars, lowercase + hyphens, must match directory name |37| `description` | Yes | 1-1024 chars, what it does + when to use it |38| `license` | No | License name or file reference |39| `compatibility` | No | Environment requirements |40| `metadata` | No | Arbitrary key-value pairs |41| `allowed-tools` | No | Space-delimited pre-approved tools |4243## Directory Structure4445```46skill-name/47├── SKILL.md # Required: metadata + instructions48├── scripts/ # Optional: executable code (Python, Bash, JS)49├── references/ # Optional: detailed documentation50└── assets/ # Optional: templates, images, data files51```5253## Claude Code extensions (beyond the open spec)5455| Field / feature | Semantics | Scope |56|---|---|---|57| `allowed-tools` | Pre-approved tools the skill may use (e.g. `Read, Bash(git *)`) | Claude Code CLI only — NOT supported in Agent SDK |58| `context: fork` | Run the skill in an isolated subagent context | Claude Code + Agent SDK |59| `agent` | Run the skill via a named subagent type | Claude Code |60| `model` | Model override for the skill's execution | Claude Code |61| `disable-model-invocation` | Only the user can invoke (`/name`); Claude never auto-triggers | Claude Code |62| `argument-hint` | Hint shown for slash-command arguments | Claude Code |63| `$ARGUMENTS`, `$0`/`$1`… | Argument substitution in the skill body | Claude Code |64| `` !`command` `` | Dynamic context injection — command runs and its output replaces the line before Claude reads the skill | Claude Code |65| `@path` | File-content references in the body | Claude Code |6667## Documentation6869Open format (agentskills.io):70- **[Specification](docs/specification.md)** - Complete SKILL.md format spec71- **[What Are Skills](docs/what-are-skills.md)** - Conceptual overview72- **[Integration Guide](docs/integrate-skills.md)** - Add skills to your agent73- **[Skill Creation Quickstart](docs/skill-creation-quickstart.md)** - First skill walkthrough74- **[Skill Creation Best Practices](docs/skill-creation-best-practices.md)** - Authoring guidelines75- **[Using Scripts](docs/using-scripts.md)** - Bundling executable code76- **[Evaluating Skills](docs/evaluating-skills.md)** - Testing skill quality77- **[Optimizing Descriptions](docs/optimizing-descriptions.md)** - Trigger-accuracy tuning78- **[Upstream README](docs/readme-upstream.md)** - Raw repository README7980Official Anthropic:81- **[Claude Code Skills](docs/claude-code-skills.md)** - Frontmatter reference, invocation control, subagent execution, dynamic context82- **[Agent SDK Skills](docs/agent-sdk-skills.md)** - Using skills with the Agent SDK83- **[Agent SDK Slash Commands](docs/agent-sdk-slash-commands.md)** - Custom commands in the SDK84- **[Anthropic Overview](docs/anthropic-overview.md)** - Agent Skills on the Claude API/platform85- **[Anthropic API Quickstart](docs/anthropic-api-quickstart.md)** - First skill via the API86- **[Best Practices](docs/best-practices.md)** - Anthropic's authoring guidance87- **[Anthropic Enterprise](docs/anthropic-enterprise.md)** - Enterprise skill management88- **[Anthropic API Skills Guide](docs/anthropic-api-skills-guide.md)** - Build-with-Claude skills guide8990Internal:91- **[Examples](docs/examples.md)** - Sample skills92- **[Audit Checklist](docs/audit-checklist.md)** - Compliance matrix spec9394## Common Workflows9596### Create a New Skill971. Create directory with skill name (lowercase, hyphens)982. Create `SKILL.md` with required frontmatter993. Write clear instructions in the body1004. Add optional scripts/, references/, assets/ as needed1015. Validate with `skills-ref validate ./my-skill`102103### Audit All Skills104Run `audit` to scan all skill directories and generate a compliance matrix showing file presence, line counts, registration status, and version consistency. See [Audit Checklist](docs/audit-checklist.md) for the full specification.105106### Validate a Skill107```bash108# Install reference library109pip install skills-ref110111# Validate112skills-ref validate ./path/to/skill113```114115### Generate Prompt XML116```bash117skills-ref to-prompt ./skill1 ./skill2118```119120## Key Principles1211221. **Progressive Disclosure**: Load metadata first (~100 tokens), full instructions on activation (~5000 tokens max recommended), resources only when needed1232. **Self-Documenting**: Skills should be readable by humans and agents1243. **Portable**: Just files - easy to version, share, edit1254. **Keep SKILL.md < 500 lines**: Move detailed content to references/126127## Upstream Sources128129- **Repository**: https://github.com/agentskills/agentskills130- **Documentation**: https://agentskills.io131- **Reference Library**: https://github.com/agentskills/agentskills/tree/main/skills-ref132- **Example Skills**: https://github.com/anthropics/skills133- **Anthropic Overview**: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview134- **Claude Code Skills**: https://code.claude.com/docs/en/skills135136## Sync & Update137138When user runs `sync`: Fetch latest from agentskills.io, code.claude.com, platform.claude.com, and GitHub, update docs/ files.139When user runs `diff`: Compare current docs/ against upstream sources.
zot24