Agent Skills Specification — Full Reference

Agent Skills Specification — Full Reference

Source: https://agentskills.io/specification

This document is the complete format specification for Agent Skills.

Contents

• Directory structure
• SKILL.md format
  • Frontmatter fields
  • Name field rules
  • Description field rules
  • License field
  • Compatibility field
  • Metadata field
  • Allowed-tools field
• Body content
• Optional directories
• Progressive disclosure
• File references
• Validation

Directory Structure

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

skill-name/
└── SKILL.md          # Required

Optionally include scripts/, references/, and assets/ directories.

SKILL.md Format

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

Frontmatter (Required)

Minimal:

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

With all optional fields:

---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents.
license: Apache-2.0
compatibility: Requires git, docker, jq, and access to the internet
metadata:
  author: example-org
  version: "1.0"
allowed-tools: Bash(git:*) Bash(jq:*) Read
---

Field Summary

Name Field

The required name field:

• Must be 1-64 characters
• May only contain unicode lowercase alphanumeric characters and hyphens (a-z, 0-9, -)
• Must not start or end with -
• Must not contain consecutive hyphens (--)
• Must match the parent directory name

Valid:

name: pdf-processing
name: data-analysis
name: code-review
name: my-tool-v2

Invalid:

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

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
• Write in third person (not "I can help" or "You can use this")

Good:

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:

description: Helps with PDFs.

Naming convention recommendation: Use gerund form (processing-pdfs, analyzing-spreadsheets) or noun phrases (pdf-processing, spreadsheet-analysis). Prefer descriptive names over vague ones (helper, utils, tools).

License Field

The optional license field:

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

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

Compatibility Field

The optional compatibility field:

• Must be 1-500 characters if provided
• Only include if the skill has specific environment requirements
• Can indicate intended product, required system packages, network access needs

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

Most skills do not need this 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 spec
• Make key names reasonably unique to avoid conflicts

metadata:
  author: example-org
  version: "1.0"
  category: document-processing

Allowed-Tools Field

The optional allowed-tools field:

• A space-delimited list of tools that are pre-approved to run
• Experimental — support varies between agent implementations

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

Body Content

The Markdown body after the frontmatter contains the skill instructions. Structure body content for best agent performance:

• Step-by-step instructions — Clear sequential guidance agents can follow
• Input/output examples — Concrete patterns that show expected behavior
• Common edge cases — Situations that require special handling

The agent loads this entire file once it decides to activate the skill. Keep the main SKILL.md lean; split content into referenced files when the validator warns. Run uv run plugins/plugin-creator/scripts/plugin_validator.py <skill-path> after writing and follow its guidance on token-based sizing.

Optional Directories

scripts/

Contains executable code that agents can run:

• Be self-contained or clearly document dependencies
• Include helpful error messages
• Handle edge cases gracefully
• Supported languages depend on the agent implementation (commonly Python, Bash, JavaScript)

references/

Contains additional documentation 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 context usage.

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 in scripts/, references/, assets/ are loaded only when required

Keep your main SKILL.md lean. Move detailed reference material to separate files. Run uv run plugins/plugin-creator/scripts/plugin_validator.py <skill-path> after writing and follow its guidance on token-based sizing.

File References

When referencing other files in your skill, 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 — each reference file should link directly from SKILL.md so the agent can discover content without following long chains.

Validation

Use the skills-ref reference library:

skills-ref validate ./my-skill

Why validate: Validation catches frontmatter and naming errors before distribution and prevents agents from loading malformed skills. Run it before publishing or sharing skills.

CLI commands:

# Validate a skill directory
skills-ref validate path/to/skill

# Read skill properties (outputs JSON)
skills-ref read-properties path/to/skill

# Generate <available_skills> XML for agent prompts
skills-ref to-prompt path/to/skill-a path/to/skill-b

Python API:

from pathlib import Path
from skills_ref import validate, read_properties, to_prompt

problems = validate(Path("my-skill"))
if problems:
    print("Validation errors:", problems)

props = read_properties(Path("my-skill"))
print(f"Skill: {props.name} - {props.description}")

prompt = to_prompt([Path("skill-a"), Path("skill-b")])
print(prompt)

Generated XML format:

<available_skills>
  <skill>
    <name>pdf-processing</name>
    <description>Extracts text and tables from PDF files, fills forms, merges documents.</description>
    <location>/path/to/skills/pdf-processing/SKILL.md</location>
  </skill>
</available_skills>