Skip to content
SkDD logo Skills-Driven Development

Agent Skills Specification (vendored snapshot)

This is a dated snapshot of the Agent Skills specification, vendored locally so that SkDD documentation, CLI, and CI can reference a stable copy and keep working when the canonical site is offline, slow, or has changed underneath us.

  • Canonical source: https://agentskills.io/specification.md
  • Fetched: 2026-04-13
  • Upstream last modified: 2026-04-11T22:03:14Z
  • Upstream repo: https://github.com/agentskills/agentskills
  • Upstream license: Apache-2.0
  • SkDD filename convention: this file is named agent-skills-v1.md. The “v1” is a SkDD-local label for snapshot generations — the upstream spec is unversioned (there is no explicit version number anywhere on the canonical page). Future snapshots will live at agent-skills-v2.md, agent-skills-v3.md, etc. as upstream evolves.

When to use the snapshot vs. the canonical URL

  • Prefer this snapshot for: CI validation, offline work, citing specific rules in docs, pinning the skdd validate behavior against a known-good spec version.
  • Prefer the canonical URL for: first-time readers who want the latest wording, or when you suspect SkDD’s behavior has drifted from upstream.

When the two diverge, open an issue and re-snapshot.

Attribution

The content below the --- line is a verbatim copy of the Agent Skills specification, originally published at https://agentskills.io/specification.md and maintained at https://github.com/agentskills/agentskills under the Apache License 2.0. All credit for the specification text belongs to the Agent Skills maintainers; SkDD’s vendoring does not alter the underlying license or authorship.

The upstream spec uses Mintlify-flavored markdown (<Card>, <Note> JSX-like components and theme={null} code-fence annotations). These are preserved verbatim for fidelity — they render as literal tags in plain-CommonMark viewers, which is fine for a reference snapshot.

Specification

The complete format specification for Agent Skills.

Directory structure

A skill is a directory containing, at minimum, a SKILL.md file:

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

SKILL.md format

The SKILL.md file must contain YAML frontmatter followed by Markdown content.

Frontmatter

FieldRequiredConstraints
nameYesMax 64 characters. Lowercase letters, numbers, and hyphens only. Must not start or end with a hyphen.
descriptionYesMax 1024 characters. Non-empty. Describes what the skill does and when to use it.
licenseNoLicense name or reference to a bundled license file.
compatibilityNoMax 500 characters. Indicates environment requirements (intended product, system packages, network access, etc.).
metadataNoArbitrary key-value mapping for additional metadata.
allowed-toolsNoSpace-separated string of pre-approved tools the skill may use. (Experimental)
**Minimal example:** 
---
name: skill-name
description: A description of what this skill does and when to use it.
---

Example with optional fields:

---
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"
---

name field

The required name field:

  • Must be 1-64 characters
  • May only contain unicode lowercase alphanumeric characters (a-z) and hyphens (-)
  • Must not start or end with a hyphen (-)
  • Must not contain consecutive hyphens (--)
  • Must match the parent directory name
**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

The required description field:

  • Must be 1-1024 characters
  • Should describe both what the skill does and when to use it
  • Should 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.

license field

The optional license field:

  • Specifies the license applied to the skill
  • We recommend keeping it short (either the name of a license or the name of a bundled license file)
**Example:** 
license: Proprietary. LICENSE.txt has complete terms

compatibility field

The optional compatibility field:

  • Must be 1-500 characters if provided
  • Should only be included if your skill has specific environment requirements
  • Can indicate intended product, required system packages, network access needs, etc.
**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 the `compatibility` field.

metadata field

The optional metadata field:

  • A map from string keys to string values
  • Clients can use this to store additional properties not defined by the Agent Skills spec
  • We recommend making your key names reasonably unique to avoid accidental conflicts
**Example:** 
metadata:
  author: example-org
  version: "1.0"

allowed-tools field

The optional allowed-tools field:

  • A space-separated string of tools that are pre-approved to run
  • Experimental. Support for this field may vary between agent implementations
**Example:** 
allowed-tools: Bash(git:*) Bash(jq:*) Read

Body content

The Markdown body after the frontmatter contains the skill instructions. There are no format restrictions. Write whatever helps agents perform the task effectively.

Recommended sections:

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

Note that the agent will load this entire file once it’s decided to activate a skill. Consider splitting longer SKILL.md content into referenced files.

Optional directories

scripts/

Contains executable code that 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 options include Python, Bash, and JavaScript.

references/

Contains additional documentation that agents can read when needed:

  • 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, so smaller files mean less use of context.

assets/

Contains static resources:

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

Progressive disclosure

Skills should be structured for efficient use of context:

  1. Metadata (~100 tokens): The name and description fields are loaded at startup for all skills
  2. Instructions (< 5000 tokens recommended): The full SKILL.md body is loaded when the skill is activated
  3. Resources (as needed): Files (e.g. those in scripts/, references/, or assets/) are loaded only when required

Keep your main SKILL.md under 500 lines. Move detailed reference material to separate files.

File references

When referencing other files in your skill, use relative paths from the skill root:

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


Run the extraction script:
scripts/extract.py

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

Validation

Use the skills-ref reference library to validate your skills:

Terminal window
skills-ref validate ./my-skill

This checks that your SKILL.md frontmatter is valid and follows all naming conventions.