Agent Skills Specification

The skill-tools ecosystem implements the Agent Skills open standard — a portable, vendor-neutral format for packaging AI agent capabilities as SKILL.md files.

The full specification is maintained at agentskills.io/specification. This page summarizes the key rules our tooling enforces.

File Format

A skill is a directory containing a SKILL.md file. The file uses YAML frontmatter delimited by --- followed by a Markdown body.

my-skill/
  SKILL.md              # Required
  scripts/              # Optional executable scripts
  references/           # Optional reference documents
  assets/               # Optional static files

Required Fields

Field Type Rules
name string Required. 1-64 chars. Lowercase letters, numbers, hyphens only. No consecutive hyphens. Must match the parent directory name.
description string Required. 1-1024 chars. Tells agents when to use this skill. Used for discovery and routing.

Optional Fields

Field Description
version Semantic version string
license SPDX license identifier
compatibility Agent compatibility information
metadata Structured key-value map for custom fields
user-invocable Whether users can trigger this skill directly
allowed-tools Comma-separated list of tools the skill can use
context Execution context (e.g., fork)
agent Agent type for execution

Progressive Disclosure

Skills follow a three-tier information model:

  1. Metadata (~100 tokens) — frontmatter fields for discovery and routing
  2. Instructions (<5,000 tokens) — the Markdown body injected into agent context
  3. Resources (as needed) — files in scripts/, references/, and assets/

Name Validation

The name field must:

Links