tools-only Agent Skills Specification — Full Reference
This document is the complete format specification for Agent Skills.
Contents
- Directory structure
- SKILL.md format
- 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
| Field | Required | Constraints |
|---|---|---|
name |
Yes | Max 64 chars. Lowercase letters, numbers, hyphens only. No leading/trailing/consecutive hyphens. Must match directory name. |
description |
Yes | Max 1024 chars. Non-empty. Describes what + when to use. |
license |
No | License name or reference to bundled file. |
compatibility |
No | Max 500 chars. Environment requirements. |
metadata |
No | Arbitrary string key-value mapping. |
allowed-tools |
No | Space-delimited pre-approved tools. Experimental. |
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 referenceFORMS.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:
- Metadata (~100 tokens): The
nameanddescriptionfields are loaded at startup for all skills - Instructions (<5000 tokens recommended): The full SKILL.md body is loaded when the skill is activated
- 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>