create-skill
Creating Skills
Read 1–2 neighboring skills first to match conventions. Draft SKILL.md, review it with the user against the checklist at the end.
Layout
skill-name/SKILL.md is the entry point and the only required file. Push long-form docs to references/<topic>.md (linked, loaded on demand), deterministic helpers to scripts/, output templates to assets/. Split when SKILL.md passes ~150 lines or content has distinct domains (e.g. one variant per reference file so the agent loads only the relevant one).
Three disclosure levels: name + description (always in context — the sole routing signal) → SKILL.md body (loaded on trigger) → bundled resources (loaded on demand).
Body shape
A body is steps (ordered actions), reference (rules and definitions consulted on demand), or both — let the content pick the shape. Don't force Workflow / Rules / Error Handling headings onto a skill that doesn't need them; empty scaffolding is a no-op.
Every step ends on a completion criterion the agent can check ("every error path returns a typed result", not "handle the errors") and that is exhaustive where it matters ("every modified file has a test"). A vague criterion invites premature completion.