Agent Skills schema

Built-in id: agentskills:skill:1.0

Published at: https://hawkeyexl.github.io/manni/schemas/agent-skills/1.0.json

The front matter of a SKILL.md file under the Agent Skills open standard, the portable format many agents read. Run it over skills you intend to package, upload or publish. The Agent Skills schemas overview explains how it pairs with anthropic:claude-skill:2.1.

Use it

Scope it to the skills that have to travel, not to the ones that live in .claude/skills/:

manni.config.yaml

meta:
  overrides:
    - files: "skills-to-publish/**/SKILL.md"
      schemas:
        - agentskills:skill:1.0

To try it once without config:

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

Fields

The whole standard. Six fields, two required.

Field	Type	Notes
name	string	Required. 1–64 characters, a-z, 0-9 and - only, no leading, trailing or doubled hyphen.
description	string	Required. 1–1024 characters. What the skill does and when to use it.
license	string	A license name, or a pointer to a bundled license file.
compatibility	string	Up to 500 characters of environment requirements. Most skills need none.
metadata	object	A map of string keys to string values.
allowed-tools	string	Space-separated pre-approved tools. Experimental in the standard.

Two rules deserve a note.

metadata takes strings, and only strings. The standard’s own example quotes the value, as in version: "1.0". Unquoted, YAML reads that as a float, and the map is defined as string to string:

metadata:
  author: example-org
  version: 1.0        # fails: must be string

name also has to match the directory. The standard requires the name field to equal the name of the folder that holds the SKILL.md file. That is a fact about the path rather than about the front matter, so no metadata check can see it. manni meta validates the character rules and the length, and the directory match is on you.

Additional properties

Rejected. This is the one built-in that forbids them.

agentskills:skill:1.0 is the only built-in that sets additionalProperties: false. Every other schema manni meta ships tolerates keys it does not know, because the tools they model do.

The Agent Skills distribution path does not. Packaging with package_skill.py, uploading a skill to claude.ai, and the Skills API all accept exactly six fields and refuse the rest outright:

Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are:
allowed-tools, compatibility, description, license, metadata, name

A permissive schema would report that file as clean. So the strictness is not an editorial opinion. It is the same rule the upload enforces, moved earlier.

Example

---
name: fetch-issue
description: Fetch a GitHub issue and summarize it. Use when the user names an issue number.
license: Apache-2.0
metadata:
  author: example-org
  version: "1.0"
---

A common mistake

A Claude Code key in a skill meant to travel fails here, before the upload does:

✗ skills/fetch-issue/SKILL.md
    (root)  must NOT have additional property 'argument-hint'  (line 1)  [agentskills:skill:1.0]