Authoring and updating Agent Skills

A skill is a directory with a SKILL.md at its root: YAML frontmatter and markdown instructions. references/ holds anything read on demand, scripts/ anything the skill runs. That is the whole format, and it is read by every agent that speaks the Agent Skills convention.

The frontmatter is the specification's six keys and no others: name and description, which every agent matches on; license; compatibility, up to 500 characters of environment requirements — the product a skill is meant for, the system packages it needs, whether it reaches the network; metadata, a string-to-string map for what the spec does not define; and the experimental allowed-tools. Use compatibility on any skill that ships a script or instructs a write outside the session's repo, and leave it off a pure convention skill — the spec's own note is that most skills do not need it. A key under metadata is yours to explain, so it is a decision recorded in the repo's instructions first; metadata: family: was added in passing here, read by nothing, and removed.

This skill covers writing one and — the part that actually goes wrong — getting a change to one to take effect.