Agent Skills Specification

What It Does

This repository is the official home of the Agent Skills open standard, originally developed by Anthropic and now governed as a community specification. It defines the SKILL.md file format: YAML frontmatter (name, description, and optional fields like license, compatibility, metadata, allowed-tools) plus a Markdown body containing instructions for AI agents. The repo contains the full specification document, a documentation site (built with Mintlify) covering skill creation, best practices, evaluation, description optimization, script bundling, and client implementation, plus a Python reference library called skills-ref that validates, parses, and generates skill metadata. The clients showcase lists 41 agent products that support the format, including Claude Code, GitHub Copilot, Cursor, Gemini CLI, OpenAI Codex, and many more.

The Good

The documentation is best-in-class for a specification repo. Most specs give you a format reference and call it done. This one ships five dedicated guides: a quickstart (80 lines, walk through creating a roll-dice skill), best practices (275 lines, with concrete examples of what to write and what to cut), description optimization (193 lines, with a full eval loop and train/validation split methodology), skill evaluation (298 lines, covering test cases, assertions, grading, benchmarking, and iteration), and using scripts (298 lines, covering Python, Deno, Bun, Ruby, and Go with inline dependency management). That last guide alone is worth reading even if you never touch the spec itself.

The skills-ref library is clean, well-tested, and works as advertised. The validator correctly accepts valid skills and rejects invalid ones (missing name, uppercase characters, consecutive hyphens, directory name mismatches). The read-properties command outputs clean JSON. The to-prompt command generates the XML block used in agent system prompts. All 40 tests pass in 0.26 seconds. The code is 1,085 lines of Python across 11 files: small enough to audit in an afternoon, large enough to be useful.

The progressive disclosure design is the right abstraction. Three tiers (metadata at session start, instructions on activation, resources on demand) solve the real problem: agents with dozens of skills need to keep context overhead low. The spec documents the token budget for each tier (~100 tokens per skill for discovery, under 5,000 for activation). The client implementation guide (335 lines) explains how to build a skills-compatible agent end to end, including edge cases like name collisions, trust checks for untrusted repos, and context compaction.

The Bad

The skills-ref library requires Python 3.11+, which creates friction on macOS. macOS 12 and 13 ship Python 3.9.6 by default. Anyone trying to run the validator on a stock Mac will hit ERROR: Package 'skills-ref' requires a different Python: 3.9.6 not in '>=3.11' with no guidance on how to get a newer Python. The README mentions python -m venv without specifying the version requirement. A note like "requires Python 3.11 or later; install via brew install python@3.11 on macOS" would save first-time users a confusing error.

The reference library is explicitly labeled "demonstration purposes only." The README states: "This library is intended for demonstration purposes only. It is not meant to be used in production." This is fair for a spec repo, but it means nobody should rely on skills-ref as their production validator. The CONTRIBUTING.md also notes they are "not accepting code contributions to it at this time," which limits community involvement in the reference implementation.

No versioned releases or changelog. The spec has no version tags, no CHANGELOG.md, and no release process documented. The skills-ref pyproject.toml is at 0.1.0. For a specification that 41+ products depend on, the lack of versioning makes it hard to pin compatibility. When the spec changes, there is no way to say "this skill targets Agent Skills spec v1.2" because no v1.2 exists.

Smoke Test Results

We ran structural validation and functional tests on the cloned repository. The structural checks verify repo completeness, documentation, and spec quality. The functional tests install the skills-ref Python library and exercise its CLI commands and test suite.

Structural validation with $ verify

$ ls /tmp/agentskills/docs/specification.mdx
✅ PASS: specification.mdx exists

$ wc -l /tmp/agentskills/README.md
✅ PASS: README.md has 59 lines

$ wc -l /tmp/agentskills/CONTRIBUTING.md
✅ PASS: CONTRIBUTING.md exists (114 lines)

$ ls /tmp/agentskills/skills-ref/pyproject.toml
✅ PASS: skills-ref pyproject.toml exists

$ ls /tmp/agentskills/skills-ref/tests/
✅ PASS: 3 test files found

$ cat /tmp/agentskills/docs/docs.json | python3 -c 'import json; d=json.load(sys.stdin); print(len(d["navigation"]["pages"]))'
✅ PASS: docs.json has 5 top-level pages

$ ls /tmp/agentskills/docs/skill-creation/quickstart.mdx
✅ PASS: quickstart guide exists

$ ls /tmp/agentskills/docs/skill-creation/best-practices.mdx
✅ PASS: best-practices guide exists

$ ls /tmp/agentskills/docs/client-implementation/adding-skills-support.mdx
✅ PASS: client implementation guide exists

$ grep -c 'name:' /tmp/agentskills/docs/snippets/clients.jsx
✅ PASS: 41 clients listed in showcase

$ grep -c 'Required' /tmp/agentskills/docs/specification.mdx
✅ PASS: specification has 2 references to required fields

$ head -1 /tmp/agentskills/LICENSE
✅ PASS: Apache license file present

Pass rate: 12 of 12. All structural checks pass.

Full structural log →

Run B. Functional verification (does the reference library work?)

$ cd skills-ref && python3.11 -m venv .venv && source .venv/bin/activate && pip install -e . 2>&1 | tail -5
Successfully built skills-ref
Installing collected packages: six, click, python-dateutil, strictyaml, skills-ref
Successfully installed click-8.4.0 python-dateutil-2.9.0 strictyaml-1.7.3 skills-ref-0.1.0
✅ PASS: skills-ref CLI installed

$ skills-ref validate /tmp/test-skill
Valid skill: /tmp/test-skill
✅ PASS: valid skill passes validation

$ skills-ref validate /tmp/bad-skill
Validation failed for /tmp/bad-skill:
 - Missing required field in frontmatter: name
✅ PASS: invalid skill correctly rejected

$ skills-ref read-properties /tmp/test-skill
{
 "name": "test-skill",
 "description": "A test skill for validation."
}
✅ PASS: read-properties returns correct JSON

$ skills-ref to-prompt /tmp/test-skill | head -5
<available_skills>
<skill>
<name>test-skill</name>
<description>A test skill for validation.</description>
✅ PASS: to-prompt generates XML block

$ cd skills-ref && python3.11 -m pytest tests/ -v 2>&1 | tail -5
tests/test_description_too_long PASSED
tests/test_valid_compatibility PASSED
tests/test_compatibility_too_long PASSED
tests/test_nfkc_normalization PASSED
============================== 40 passed in 0.26s ================================
✅ PASS: 40 tests passed in 0.26s

Functional pass rate: 6 of 6. The reference library installs, validates, rejects bad input, reads properties, generates prompts, and passes its full test suite.

Full functional log →

What the runs tell you

The structural validation confirms the repo is well-organized with complete documentation, a working spec, and broad client adoption (41 listed products). The functional tests confirm the skills-ref Python library does what it claims: validates, parses, and generates skill metadata, with a test suite that covers edge cases including i18n (Chinese and Russian names), NFKC normalization, and field length limits. The only friction point is the Python 3.11+ requirement on macOS systems that ship 3.9.6.

Setup Walkthrough

1. Clone the repository:

git clone --depth 1 https://github.com/agentskills/agentskills
cd agentskills

1. Browse the specification and documentation at docs/specification.mdx and the docs/skill-creation/ directory. The docs site is also hosted at agentskills.io.

1. Install the skills-ref reference library (requires Python 3.11+):

cd skills-ref
python3.11 -m venv .venv
source .venv/bin/activate
pip install -e .

1. Validate a skill:

skills-ref validate path/to/my-skill

1. Read skill properties as JSON:

skills-ref read-properties path/to/my-skill

1. Generate the XML for your agent prompt:

skills-ref to-prompt path/to/skill-a path/to/skill-b

Note: On macOS, if python3 is 3.9.x, install Python 3.11+ first via brew install python@3.11 or download from python.org.

Alternatives

1. anthropics/skills - Anthropic's official collection of example skills. Ships working skills you can install, rather than the spec itself. Complementary: use agentskills/agentskills for the format definition, anthropics/skills for example implementations.
2. agent-sh/agnix - A dedicated linter and LSP for SKILL.md files, built in Rust with IDE plugins. Goes beyond skills-ref validation with autofixes and real-time checking. Better suited for CI/CD pipelines.
3. sickn33/antigravity-awesome-skills - A library of 1,400+ installable agent skills across multiple platforms. If you want to consume skills rather than understand the spec, start here.