The Agent Skills open standard is the shared format for agent skills: a folder with a SKILL.md file whose YAML front matter gives a name and a description, followed by instructions. Anthropic first built it and released it at agentskills.io. Of 1,966 public skills we checked on November 11, 2026, 927 pass every rule of its reference validator.
The standard is short. It fixes six front matter fields, a few length and naming limits, and a recommended folder layout. Most of what agents do with skills beyond that, such as when a skill may run on its own or which tools it may use without asking, is left to each product.
How many real skills follow the standard?
Use This Skill lists every skill folder it finds in public GitHub repositories. On November 11, 2026, we cloned all 47 repositories in the November 9 crawl (data/skills.json: 1,966 skills) and checked each SKILL.md against the rules in the reference validator, skills-ref, from the agentskills/agentskills repository.
| What we checked | Skills | Repositories |
|---|---|---|
| SKILL.md files read | 1,966 | 47 |
| Pass every validator rule | 927 | 37 |
| Fail at least one rule | 1,039 | 25 |
| Top-level field outside the six in the spec | 1,030 | 21 |
name differs from the folder name |
74 | 7 |
name has uppercase letters |
65 | 2 |
name has characters other than letters, digits and hyphens |
90 | 1 |
name starts or ends with a hyphen |
2 | 1 |
description over 1,024 characters |
1 | 1 |
compatibility over 500 characters |
0 | 0 |
SKILL.md files read on November 11, 2026 from each repository's default branch, at the path recorded in the November 9, 2026 crawl. Rules re-implemented from skills-ref's validator.py (agentskills/agentskills, commit 83021e2, November 4, 2026); we read that code but did not run it. A skill can fail more than one rule.
Twenty-two repositories pass on every skill they hold (575 skills between them), and ten fail on every skill. The failures are concentrated: one collection, ComposioHQ/awesome-claude-skills, holds 864 of the 1,966 skills and 833 of the 1,039 failures. Outside it, 896 of 1,102 skills pass, or 81 percent.
What does the specification require?
The specification on agentskills.io, read on November 11, 2026, defines these fields:
| Field | Required | Limit in the spec |
|---|---|---|
name |
Yes | 1 to 64 characters; lowercase letters, numbers and hyphens; no hyphen at the start or end, no --; must match the parent folder |
description |
Yes | 1 to 1,024 characters; should say what the skill does and when to use it |
license |
No | A license name or the name of a bundled license file |
compatibility |
No | 1 to 500 characters; only for real environment needs |
metadata |
No | A map from string keys to string values |
allowed-tools |
No | A space-separated string of pre-approved tools; marked experimental, and support varies by agent |
Beyond the fields, the spec recommends scripts/, references/ and assets/ folders, relative file paths from the skill root, references no more than one level deep, and a SKILL.md under 500 lines and under about 5,000 tokens. It describes three loading stages: name and description at startup, the full SKILL.md when a task matches, other files only when needed. Progressive disclosure in agent skills compares how each product handles those stages.
The recommendations are not validator rules, but we counted them too: 15 skills in 7 repositories have a SKILL.md over 500 lines, and 52 in 16 repositories have instructions over about 5,000 tokens (estimated at four characters per token).
Why do most failing skills fail?
Almost always because of an extra field. Of the 1,039 failing skills, 936 fail for that reason alone; their name and description are within the rules. The most common extra fields:
| Field | Skills | Repositories | Where it comes from |
|---|---|---|---|
requires |
833 | 2 | One collection's template (832 of the 833) |
argument-hint |
107 | 7 | Claude Code |
user-invocable |
80 | 3 | Claude Code |
model |
77 | 1 | Claude Code |
version |
36 | 6 | Authors' own field |
disable-model-invocation |
36 | 5 | Claude Code (Cursor reads it too) |
Claude Code's documentation says it "extends the standard with additional features like invocation control, subagent execution, and dynamic context injection," and those features live in front matter fields the spec does not have. Of the 936 skills that fail only on extra fields, 134 carry nothing but Claude Code fields. A version or category field is a different case: the spec's answer is to move it under metadata.
The naming failures come mostly from the same large collection: it holds 64 of the 65 names with uppercase letters and all 90 with other characters, such as "Ahrefs Automation" or an underscore, and 65 of the 74 names that differ from the folder. The other nine mismatches are in six repositories, often a longer form of the folder name, such as vercel-react-best-practices in a folder called react-best-practices.
Two smaller departures do not fail the validator, because it does not test them. 87 skills in 6 repositories write allowed-tools as a comma-separated list rather than the space-separated string the spec describes, and 4 write it as a YAML list. 42 skills in 8 repositories put numbers, lists or nested maps under metadata, where the spec asks for string values.
Does failing the validator stop a skill from working?
It depends on where the skill runs.
| Where | Extra top-level field | name different from folder |
|---|---|---|
| Claude Code | Accepted if it is in Claude Code's front matter table | Allowed; name sets the / command and the folder still invokes the skill |
claude.ai upload, Skills API, Anthropic's package_skill.py |
Hard error naming the field | Not stated on the page we read |
Reference validator (skills-ref validate) |
Error | Error |
Claude Code and Claude platform behavior from code.claude.com/docs/en/skills, read November 11, 2026.
Claude Code's documentation gives the exact error a claude.ai upload or the Skills API returns for an unknown field: "Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, name." So a skill full of Claude Code fields works in Claude Code and fails when someone uploads it to claude.ai.
Anthropic's skill authoring best practices for the Claude platform add two rules the spec does not have: name and description cannot contain XML tags, and name cannot contain the reserved words "anthropic" or "claude." Seven skills in four repositories have one of those words in their name, and six descriptions in six repositories contain something shaped like an XML tag.
Codex, Cursor and Gemini CLI each have their own folder and naming rules on top of the standard. Do agent skills work in Codex, Cursor and Gemini CLI? compares them with counts from the same directory.
Does following the standard make a skill safe?
No. The standard checks the shape of the front matter, not what the instructions say or what the scripts do. We compared today's results with the November 9, 2026 safety scan (data/scan.json): 9 of the 14 flagged skills and 40 of the 47 that need a review pass every validator rule. Claude API, from Anthropic's own repository, fails only because its description runs to 1,068 characters, 44 over the limit.
Before installing any skill, run it through the free skill check, which reads every text file in the folder for nine risky patterns and shows the file and line of each finding. What a malicious skill can do explains which patterns matter most.
How do I check my own skill against the standard?
- Run the reference validator. The spec's own instruction is
skills-ref validate ./my-skill, after installingskills-reffrom the agentskills/agentskills repository. Its README says the library is "intended for demonstration purposes only," so treat it as a format check, not a guarantee. - Keep top-level fields to the six. Move anything else, such as
versionorauthor, undermetadatawith string values. - Name it like the folder. Lowercase letters, numbers and single hyphens, identical to the folder name, with no "anthropic" or "claude" if it may go to the Claude platform.
- Keep the description under 1,024 characters and say when to use the skill; how to write a skill description covers the wording.
- Decide about Claude Code fields. If the skill is only for Claude Code, fields such as
argument-hintordisable-model-invocationare useful. If it is meant for claude.ai or the API as well, ship a copy without them.
How we counted
The skill list and paths come from data/skills.json (crawl of November 9, 2026). Each of the 47 repositories was cloned at depth 1 from its default branch on November 11, 2026; every skill's SKILL.md was found at its recorded path. For the one skill that sits at a repository's root, the folder name is taken as the repository name. Front matter was parsed with strictyaml, as skills-ref does, and again with PyYAML for the field counts; the 781 files strictyaml could not parse all carry an extra field, so they fail either way. The rules applied are the ones in validator.py at commit 83021e2: allowed fields; name present, at most 64 characters after NFKC normalization, lowercase, letters, digits and hyphens only, no leading, trailing or double hyphen, equal to the folder name; description present, non-empty and at most 1,024 characters; compatibility a string of at most 500 characters. The safety status of each skill comes from data/scan.json (November 9, 2026). We did not run the skills in any agent.