Agent Skills schemas

A skill is a directory with a SKILL.md in it: YAML front matter, then the instructions an agent follows. The front matter is the part that has a contract, and there are two of them.

Id	Describes	Requires	Unknown keys
agentskills:skill:1.0	the Agent Skills open standard	name, description	rejected
anthropic:claude-skill:2.1	what Claude Code 2.1 accepts	nothing	tolerated

They are a pair, not alternatives. The second is a superset of the first, and the gap between them is a real failure you can hit:

manni meta validate .claude/skills/**/SKILL.md -s anthropic:claude-skill:2.1
manni meta validate skills-to-publish/**/SKILL.md -s agentskills:skill:1.0

Why one of them is strict

agentskills:skill:1.0 rejects any key outside the standard’s six. The packaging and upload tools refuse such a file outright, so a permissive schema would pass exactly the skill that cannot ship. Its page quotes the upload error.

Do not point the spec schema at your local skills

A working Claude Code skill that uses disable-model-invocation, paths or allowed-tools as a list is correct, and it fails agentskills:skill:1.0 on every one of those keys. Run the spec schema over skills you intend to distribute; run anthropic:claude-skill:2.1 over the ones that live in .claude/skills/.

The two schemas

Each has a page of its own, with its full field table, an example SKILL.md, and the finding a common mistake produces.

• agentskills:skill:1.0 is the whole open standard. Six fields, two required, nothing else allowed.
• anthropic:claude-skill:2.1 adds the fourteen fields Claude Code reads, and requires none of the twenty.

Validate both at once

Nothing stops you stacking them, and for a skill that has to work locally and publish, that is the right run. Each failure is attributed to the schema that raised it:

manni meta validate skills/**/SKILL.md \
  -s anthropic:claude-skill:2.1 \
  -s agentskills:skill:1.0

The two agree on every field they share, so a spec-conformant SKILL.md passes both. What the pair reports is the Claude Code-only keys, which is the list of things to remove before you package.

The other file in .claude/

A subagent definition is a different contract, not a third skill schema. It lives under .claude/agents/, and it requires name and description. It spells its tool grants tools and disallowedTools rather than allowed-tools and disallowed-tools. Validating one against a SKILL.md schema passes it while every key it set does nothing. See Claude Code subagent schema.