skill-manager/references/specification.md

Agent Skills — Full Specification Reference

Source: https://agentskills.io/specification

Directory structure

skill-name/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation loaded on demand
├── assets/           # Optional: templates, resources
└── ...               # Any additional files or directories

SKILL.md format

The file must contain YAML frontmatter followed by Markdown content.

---

Frontmatter fields

Field	Required	Constraints
name	Yes	Max 64 chars. Lowercase letters, numbers, hyphens only. No leading/trailing/consecutive hyphens. Must match the parent directory name.
description	Yes	Max 1024 chars. Non-empty. Describes what the skill does and when to use it.
license	No	License name or reference to a bundled license file.
compatibility	No	Max 500 chars. Indicates environment requirements (product, packages, network, etc.).
metadata	No	Arbitrary key-value mapping (string → string) for additional metadata.
allowed-tools	No	Space-separated string of pre-approved tools. (Experimental)

---

name field

Rules:

• 1–64 characters
• Only: lowercase letters a-z, digits 0-9, hyphens -
• Must not start or end with a hyphen
• Must not contain consecutive hyphens --
• Must match the parent directory name exactly

Valid examples:

name: pdf-processing
name: data-analysis
name: code-review

Invalid examples:

name: PDF-Processing    # uppercase not allowed
name: -pdf              # cannot start with hyphen
name: pdf--processing   # consecutive hyphens not allowed

---

description field

Rules:

• 1–1024 characters
• Should describe both what the skill does and when to use it
• Include specific keywords that help agents identify relevant tasks

Good example:

description: >
  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 example:

description: Helps with PDFs.

Principles for effective descriptions:

• Use imperative phrasing: "Use this skill when…" not "This skill does…"
• Focus on user intent, not internal mechanics
• Be explicit about indirect triggers: "even if they don't explicitly mention 'CSV'"
• Err on the side of being specific and slightly pushy
• Keep it concise — a few sentences to a short paragraph

---

license field

• Specifies the license applied to the skill
• Keep it short — either the name of a license or the name of a bundled license file

Example:

license: Apache-2.0
license: Proprietary. LICENSE.txt has complete terms.

---

compatibility field

• 1–500 characters if provided
• Only include if your skill has specific environment requirements
• Can indicate: intended product, required system packages, network access

Examples:

compatibility: Designed for Claude Code (or similar products)
compatibility: Requires git, docker, jq, and access to the internet
compatibility: Requires Python 3.14+ and uv

Most skills do not need this field.

---

metadata field

• A map from string keys to string values
• Use for storing additional properties not defined by the spec
• Make key names reasonably unique to avoid conflicts

Example:

metadata:
  author: example-org
  version: "1.0"

---

allowed-tools field

• A space-separated string of tools pre-approved to run
• Experimental — support varies between agent implementations

Example:

allowed-tools: Bash(git:*) Bash(jq:*) Read

---

Body content

The Markdown body after the frontmatter contains the skill instructions.

Recommended sections:

• Step-by-step instructions
• Examples of inputs and outputs
• Common edge cases

The agent loads the entire body when the skill activates. Keep it under 500 lines. Move longer reference material to separate files.

---

Progressive disclosure

Skills are loaded in three stages:

Stage	Content	Size
Startup	name + description only	~100 tokens
Activation	Full SKILL.md body	< 5,000 tokens recommended
On demand	Files in scripts/, references/, assets/	As needed

Keep SKILL.md under 500 lines. Move detailed reference material to separate files and tell the agent when to load them — not just "see references/ for details."

---

File references

Use relative paths from the skill root:

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

Run the extraction script:
scripts/extract.py

Keep file references one level deep from SKILL.md. Avoid deeply nested reference chains.

---

Optional directories

scripts/

Contains executable code agents can run. Scripts should:

• Be self-contained or clearly document dependencies
• Include helpful error messages
• Handle edge cases gracefully

Supported languages depend on the agent implementation. Common: Python, Bash, JavaScript.

references/

Contains documentation agents read on demand:

• REFERENCE.md — Detailed technical reference
• FORMS.md — Form templates or structured data formats
• Domain-specific files (finance.md, legal.md, etc.)

Keep individual reference files focused. Agents load these on demand — smaller files = less context used.

assets/

Contains static resources:

• Templates (document, configuration)
• Images (diagrams, examples)
• Data files (lookup tables, schemas)