Agent Skills Specification Reference

Agent Skills Specification Reference

Source: agentskills.io - Official Agent Skills specification maintained by Anthropic

This reference document is a consolidated guide for skill development in this repository. For the latest specification, visit the official documentation.

What Are Agent Skills?

Agent Skills are folders of instructions, scripts, and resources that agents can discover and use to perform tasks more accurately and efficiently. They use progressive disclosure to manage context efficiently:

1. Discovery: At startup, agents load only the name and description of each available skill
2. Activation: When a task matches a skill's description, the agent reads the full SKILL.md instructions
3. Execution: The agent follows instructions, optionally loading referenced files or executing scripts as needed

Directory Structure

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

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

SKILL.md Format

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

Required Frontmatter

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

Optional Frontmatter 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
metadata:
  author: example-org
  version: "1.0"
allowed-tools: Bash(git:*) Bash(jq:*) Read
---

Field Reference

Name Field Rules

The name field:

• Must be 1-64 characters
• May only contain 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 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 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
• Must be written in third person (not "I can help" or "You can use")

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.

Body Content

The Markdown body after the frontmatter contains the skill instructions. There are no format restrictions. Recommended sections:

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

Optional Directories

scripts/

Contains executable code that agents can run:

• Should be self-contained or document dependencies
• Include helpful error messages
• Handle edge cases gracefully

references/

Contains additional documentation loaded on demand:

• REFERENCE.md - Detailed technical reference
• Domain-specific files (finance.md, legal.md, etc.)
• Keep individual files focused for efficient context usage

assets/

Contains static resources:

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

Progressive Disclosure

Skills should be structured for efficient use of context:

1. Metadata (~100 tokens): name and description loaded at startup for all skills
2. Instructions (< 5000 tokens recommended): Full SKILL.md body loaded when activated
3. Resources (as needed): Files in scripts/, references/, assets/ loaded only when required

Key Guidelines:

• Keep main SKILL.md under 500 lines
• Move detailed reference material to separate files
• Keep file references one level deep from SKILL.md
• Avoid deeply nested reference chains

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

Validation

Use the skills-ref reference library to validate skills:

skills-ref validate ./my-skill

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

Additional Resources

• Official Documentation: agentskills.io
• Specification: agentskills.io/specification
• Example Skills: github.com/anthropics/skills
• Reference Library: github.com/agentskills/agentskills/tree/main/skills-ref
• Best Practices: See agentskills-best-practices.md