Skill authoring
A skill is a folder under skills/ with one SKILL.md and, optionally, references/,
scripts/, assets/ and evals/. The validator enforces the contract in
references/skill-contract.md; read it once, then follow the
steps below.
Steps
- Scaffold:
pnpm new-skill mass-<slug>. The name equals the folder, is kebab-case, starts withmass-and has at most 64 characters. - Write the
descriptionwith the formula and nothing else:[What it does]. Use when "a", "b" or "c". Do NOT use for X (use mass-y).The "Use when" quotes are the phrases a user would actually type. The "Do NOT use for" clause names the neighbouring skill so the two never overlap. - Keep
SKILL.mdunder 80 lines for example skills and under 500 lines for any skill. Move long material toreferences/and link it with a relative path. - Put executable code in
scripts/with a#!first line and the executable bit set (chmod +x). Put templates inassets/. - Fill
metadata:author,version(semver),category(an id fromskills/_categories.json),tags(comma-separated string) andreviewed(today, asYYYY-MM-DD). Every value is a string. - Optionally add
evals/triggers.jsonwithshouldandshouldNotprompt lists to record what must and must not trigger the skill. - Run
pnpm check. Fix every reported<rule> <path>:<line>before opening a PR.
Review checklist
- The description answers "what", "when" and "not when" in one paragraph.
- No secrets, no binaries, no downloads piped into a shell, no instructions that ask the agent to hide information from the user.
- Every relative link in
SKILL.mdresolves to a file inside the skill. metadata.reviewedwas updated in this change.