Agent Skill

If a skill declares allowed-tools, it must be an array of tool names so its capability surface is explicit and auditable.

Skill bodies should stay focused — very long instructions degrade agent performance. Keep the body under ~5000 words.

A skill must have body content, not just frontmatter — the body is the instruction set the agent actually follows.

A skill must declare a description — it is the primary signal an agent uses to decide when to invoke the skill.

Skill descriptions should be specific enough to drive good selection — at least 40 characters of meaningful intent.

A skill description should be a single line (no embedded line breaks) so it renders cleanly in pickers.

A skill body should show concrete examples under an Examples section so agents and humans can see how it is meant to be invoked.

A skill body should document how to use it under a Usage section, so both humans and agents can see how it is meant to be invoked.

A skill should declare a license so consumers know the terms under which they can reuse and redistribute it.

If a skill declares metadata, it should be an object of key/value pairs.

A skill must declare a name in its frontmatter — it identifies the skill to agents and tooling.

Skill name should be lower kebab-case so it matches the skill directory name and stays portable.

A skill name should be concise (64 characters or fewer).

agent-skill document should declare a `allowed-tools` property.

agent-skill document should declare a `metadata` property.

agent-skill document should declare a `version` property.

A skill body should have at most one level-1 heading — the frontmatter name is the title, and sections should use level-2 headings.

If a skill declares a version, it should be semantic (e.g. 1.0.0) so consumers can reason about changes between releases.