Agentskills

Agent Skills Open Standard

The Agent Skills format is an open standard for extending AI agent capabilities with specialized knowledge and workflows. Originally developed by Anthropic, adopted by 25+ agent products.

Source: https://agentskills.io

When to use this skill: Before creating any skill that should be portable across multiple agent products. For Claude Code-specific features (hooks, context fork, model selection, invocation control), see claude-skills-overview-2026 instead.

SKILL.md Format

Every skill is a directory containing a SKILL.md file with YAML frontmatter and Markdown body:

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

Required Frontmatter

---
name: skill-name
description: 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, and access to the internet
metadata:
  author: example-org
  version: "1.0"
allowed-tools: Bash(git:*) Bash(jq:*) Read
---

Field Reference

Name Validation Rules

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

Valid: pdf-processing, data-analysis, code-review Invalid: PDF-Processing (uppercase), -pdf (leading hyphen), pdf--processing (consecutive)

Description Guidelines

Write in third person. Include both what the skill does and when to use it.

# Good — specific, includes triggers
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.

# Weak — vague, no triggers
description: Helps with PDFs.

Preferred patterns: Use gerund form (processing-pdfs) or noun phrases (pdf-processing). Prefer descriptive names like pdf-processing over generic names like helper or utils.

Progressive Disclosure

Skills use three-level loading to manage context efficiently:

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

Keep SKILL.md body 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.

Disclosure Patterns

Pattern 1 — High-level guide with references:

# PDF Processing

## Quick start
[core example]

## Advanced features
- **Form filling**: See [references/forms.md](references/forms.md)
- **API reference**: See [references/api.md](references/api.md)

Pattern 2 — Domain-specific organization:

bigquery-skill/
├── SKILL.md (overview + navigation)
└── references/
    ├── finance.md
    ├── sales.md
    └── product.md

Pattern 3 — Conditional details:

For simple edits, modify XML directly.
**For tracked changes**: See [references/redlining.md](references/redlining.md)

Rules:

• Keep file references one level deep from SKILL.md — link directly from SKILL.md so the agent can discover content without following long chains
• For files >100 lines, include a table of contents at the top

Directory Contents

scripts/

Executable code agents can run. Should be self-contained, include helpful error messages, handle edge cases. Scripts save tokens (no code generation needed) and ensure consistency.

Make execution intent clear:

• "Run scripts/extract.py to extract fields" (execute)
• "See scripts/extract.py for the algorithm" (read as reference)

references/

Documentation loaded on demand. Keep individual files focused — smaller files mean less context usage. Structure files >100 lines with a table of contents.

assets/

Static resources used in output (templates, images, data files). Not loaded into context — used by the agent in its output.

Authoring Best Practices

For the complete Anthropic authoring guide, see references/best-practices.md.

Key principles:

1. Concise is key — Reason: Claude is already smart. Include only context it doesn't have. Prefer concise examples over verbose explanations to keep the skill discoverable and efficient.
2. Set appropriate degrees of freedom — Reason: Match specificity to task fragility. High freedom for open-ended tasks; low freedom for fragile operations.
3. Use workflows for complex tasks — Reason: Clear sequential steps with checklists help agents track progress and complete multi-step work reliably.
4. Implement feedback loops — Reason: Run validator, fix errors, repeat. Validators surface issues early so agents correct before proceeding.
5. Test with all target models — Reason: Haiku may need more detail than Opus; testing across models ensures the skill works for all targets.
6. Build evaluations first — Reason: Evaluations identify real gaps before documentation. Create them before writing extensively so the skill addresses actual failures.

What to Include

Focus skill content on:

• Instructions the agent needs to perform the task
• Step-by-step workflows, examples, and edge cases
• References to scripts/, references/, and assets/ for details

Place user-facing docs (README, CHANGELOG, INSTALLATION_GUIDE), setup procedures, and time-sensitive details in a separate "Legacy patterns" section or external docs. Claude already knows general concepts — include only skill-specific information.

Validation

Use the skills-ref reference library to validate:

# Validate a skill directory
skills-ref validate ./my-skill

# Read skill properties as JSON
skills-ref read-properties ./my-skill

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

Python API:

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

problems = validate(Path("my-skill"))
props = read_properties(Path("my-skill"))
prompt = to_prompt([Path("skill-a"), Path("skill-b")])

Install: pip install -e . from the skills-ref directory.

Portable vs Claude Code-Specific

The open standard defines a portable subset. Claude Code extends it with additional frontmatter fields.

For portable skills: Use only the open standard fields. Other agents will ignore unknown fields, but keeping frontmatter clean improves compatibility.

For Claude Code skills: See claude-skills-overview-2026 for the full extended schema.

Detailed References

• Full specification details: See references/specification.md
• Authoring best practices: See references/best-practices.md
• Agent integration guide: See references/integration.md

External Links

• Specification: https://agentskills.io/specification
• Best practices: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices
• Example skills: https://github.com/anthropics/skills
• Reference library: https://github.com/agentskills/agentskills/tree/main/skills-ref
• GitHub org: https://github.com/agentskills/agentskills