Agent Skills Open Standard reference (agentskills.io). Use when creating portable skills for Claude Code, Cursor, Gemini CLI, OpenAI Codex, VS Code, Roo Code, and 20+ compatible agents. Covers frontmatter schema, naming rules, directory structure, progressive disclosure, validation, and authoring. Load before creating cross-agent skills.
Scanned 6/1/2026
Install via CLI
Skills Directoryopenskills install tools-only/X-Skills---
name: agentskills
description: Agent Skills Open Standard reference (agentskills.io). Use when creating portable skills for Claude Code, Cursor, Gemini CLI, OpenAI Codex, VS Code, Roo Code, and 20+ compatible agents. Covers frontmatter schema, naming rules, directory structure, progressive disclosure, validation, and authoring. Load before creating cross-agent skills.
user-invocable: true
---
# 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](../claude-skills-overview-2026/SKILL.md) 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
```yaml
---
name: skill-name
description: What this skill does and when to use it.
---
```
### Optional Frontmatter Fields
```yaml
---
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
| Field | Required | Max Length | Constraints |
| --------------- | -------- | ---------- | ---------------------------------------------------------------- |
| `name` | Yes | 64 chars | Lowercase alphanumeric + hyphens. No leading/trailing/consecutive hyphens. Must match directory name. |
| `description` | Yes | 1024 chars | Non-empty. Describe what + when to use. Include trigger keywords. |
| `license` | No | — | License name or reference to bundled file. |
| `compatibility` | No | 500 chars | Environment requirements (products, packages, network). |
| `metadata` | No | — | Arbitrary string key-value pairs. |
| `allowed-tools` | No | — | Space-delimited pre-approved tools. Experimental. |
### 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.
```yaml
# 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:**
```markdown
# 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:**
```markdown
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](./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:
```bash
# 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:**
```python
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](https://github.com/agentskills/agentskills/tree/main/skills-ref) directory.
---
## Portable vs Claude Code-Specific
The open standard defines a **portable subset**. Claude Code extends it with additional frontmatter fields.
| Feature | Open Standard | Claude Code Extension |
| ------------------------ | ------------- | --------------------- |
| `name` | Yes | Yes |
| `description` | Yes | Yes |
| `license` | Yes | Yes |
| `compatibility` | Yes | Yes |
| `metadata` | Yes | Yes |
| `allowed-tools` | Yes (experimental) | Yes (extended syntax) |
| `argument-hint` | No | Yes |
| `model` | No | Yes |
| `context: fork` | No | Yes |
| `agent` | No | Yes |
| `user-invocable` | No | Yes |
| `disable-model-invocation` | No | Yes |
| `hooks` | No | Yes |
**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](../claude-skills-overview-2026/SKILL.md) for the full extended schema.
---
## Detailed References
- **Full specification details**: See [references/specification.md](./references/specification.md)
- **Authoring best practices**: See [references/best-practices.md](./references/best-practices.md)
- **Agent integration guide**: See [references/integration.md](./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>
No comments yet. Be the first to comment!
