Skip to content

Agent Skills Specification

Condensed from the Agent Skills specification. Load this when checking layout, frontmatter, progressive disclosure, or validation.

Directory

Minimum: a folder containing SKILL.md. Recommended optional children:

Path Role
scripts/ Executable code the agent can run
references/ On-demand documentation
assets/ Templates, images, data files

Other files are allowed. Clients that understand the format treat the directory as the skill unit.

SKILL.md

YAML frontmatter, then Markdown body. The body has no required sections. Recommended content: procedures, input/output examples, and edge cases.

The whole body enters context on activation. Long material belongs in supporting files.

Required fields

name

  • 1–64 characters
  • Unicode lowercase alphanumeric (a-z, 0-9) and hyphen (-) only
  • Must not start or end with -
  • Must not contain --
  • Must equal the parent directory name

Valid: pdf-processing, data-analysis, code-review.

Invalid: PDF-Processing, -pdf, pdf--processing.

description

  • 1–1024 characters, non-empty
  • States both what the skill does and when to use it
  • Includes keywords an agent can match against user tasks

Good: "Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction."

Poor: "Helps with PDFs."

Optional fields

Field Constraint Use
license Short license name or bundled license filename Legal terms
compatibility 1–500 characters Product, packages, network, runtime needs. Omit unless required.
metadata Map of string keys to string values Client-specific extras; use unique key names
allowed-tools Space-separated tool names Experimental pre-approval. Support varies.

This repository currently publishes only name and description. See the Frontmatter Contract.

Minimal:

---
name: skill-name
description: A description of what this skill does and when to use it.
---

With optional fields (spec-legal, not used in this repo):

---
name: pdf-processing
description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
license: Apache-2.0
metadata:
  author: example-org
  version: "1.0"
---

Progressive Disclosure

  1. Metadata (~100 tokens): name and description for every installed skill.
  2. Instructions (< 5,000 tokens recommended): full SKILL.md after activation.
  3. Resources: scripts/, references/, assets/ only when required.

Keep SKILL.md under 500 lines.

File References

Use paths relative to the skill root:

See [the reference guide](references/REFERENCE.md) for details.

Run the extraction script:
scripts/extract.py

Keep references one level deep from SKILL.md. Nested chains waste turns and hide the useful file.

Keep each reference file focused. Smaller files load cheaper.

Optional Directory Conventions

scripts/: self-contained or documented dependencies; useful errors; graceful edge cases. Language support depends on the agent.

references/: detailed technical notes, forms, domain files. Load on demand.

assets/: templates, images, lookup tables, schemas. Static; not instructions.

Validation

skills-ref validate ./my-skill

skills-ref checks frontmatter validity and naming conventions. Repository tests additionally enforce directory/name parity and reject extra skill frontmatter fields.