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, released as an open standard, and adopted by a growing number of 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), use the plugin-creator:claude-skills-overview-2026 skill 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, and ideally under 500 lines): 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 uvx skilllint@latest check <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

For quick complexity and frontmatter checks, uvx skilllint@latest check <skill-path> is available via uvx (resolves the package from PyPI on first run — needs network access, is not bundled with this skill) and is faster than installing skills-ref.

For deeper agentskills.io open-standard compliance checks not covered by skilllint (e.g. cross-client portability rules), use the skills-ref reference library:

# 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.

Note: skills-ref is intended for demonstration purposes only and is not meant to be used in production — treat it as a reference implementation, not a hardened validation gate.

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.

Claude Code-specific validation: Claude Code additionally rejects name or description values containing XML tags, and rejects name values containing the reserved words anthropic or claude — a stricter check than the open standard's own name/description rules above. This constraint is Claude Code-specific and not part of the agentskills.io specification.

For Claude Code skills: Use the plugin-creator:claude-skills-overview-2026 skill 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 (accessed 2026-08-24)
• Best practices: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices (accessed 2026-08-24)
• Example skills: https://github.com/anthropics/skills (accessed 2026-08-24)
• Reference library: https://github.com/agentskills/agentskills/tree/main/skills-ref (accessed 2026-08-24)
• GitHub org: https://github.com/agentskills/agentskills (accessed 2026-08-24) — Apache-2.0 (code) + CC-BY-4.0 (spec text)