skill-authoringlisted

# 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. ## What this skill reads, runs and writes It ships one script, `scripts/names.py`, which reads skill directories and queries a public search endpoint. Everything else it touches, it touches through the commands it tells you to run. - **Reads**: `scripts/names.py` reads the `SK