The authoring guide
The only page on this site whose content is fully shipped, because none of it was invented: every rule here was extracted from the eight skills that already exist, and every one of those skills already follows it. Nobody wrote these down until this site did.
description is not documentation about the skill — it is what a caller’s retrieval matches against. Get it wrong and the skill either never fires or fires on the wrong intent. These five conventions are what the estate learned by writing eight of them.
The five conventions
A — The trigger-rich description
The frontmatter description is not a summary — it is a retrieval surface. Name the exact phrases that should fire the skill, the adjacent hosts and tools it touches, and the fuzzy cases where a user won’t use your vocabulary at all.
# create-infographics/SKILL.md description: Use this skill whenever the user wants to create infographics, slide decks, visual presentations, or image-based content using the SGraph infographic generator API. Triggers include: any mention of 'infographic', 'slide deck', 'visual summary', 'deck from document'… Also triggers when the user mentions 'dev.tools.sgraph.ai'… Use this skill even if the user just says 'make me a deck'.
B — The do-NOT-use clause
The same description ends by saying when not to fire. A skill that names its own boundary is a skill that plays well with siblings — because skills compete for triggering (below), and the dispatcher has to guess less when the skill itself narrows the guess.
description: … Do NOT use for standard PowerPoint (.pptx) creation without AI image generation, or for diagrams/charts that can be handled by code-based visualisation tools.
C — Self-containedness as a feature
create-vault-content embeds its full schema reference so it “does not require cloning the repo.” A skill is a package: it carries its dependencies rather than assuming the caller already has the context.
D — Cross-reference canonical contracts, never copy them
create-vault-apps “cross-references the canonical window.sg API reference (AUTHORING.md)” rather than duplicating it. This is the same no-second-source-of-truth rule the sg.llm governance decision applies (see when not to make a skill) — a skill that copies a contract instead of pointing at it will drift from that contract the same way the two copies of one skill drifted from each other.
E — Named-trigger vocabulary
talk-to-team__send enumerates the exact role names that should fire it — “Conductor”, “Sherpa”, “Librarian” — turning the team’s own vocabulary into the trigger set, rather than describing the skill in the abstract and hoping the vocabulary lines up.
Coverage across the eight
How many of the eight shipped skills follow each convention, measured from the survey (not every description survived intact — see the catalogue’s coverage table):
| Convention | Followed by | |
|---|---|---|
| A | The trigger-rich description | 5 of 8 captured cleanly in the survey |
| B | The do-NOT-use clause | 1 of 8 captured — the reference case is create-infographics |
| C | Self-containedness | create-vault-content, sg-playwright-capabilities |
| D | Cross-reference, never copy | create-vault-apps, sg-playwright-capabilities |
| E | Named-trigger vocabulary | talk-to-team__send, use_sgit-and-vaults, both use-sg-playwright copies |
Next: when not to make a skill
The five conventions say how to write a skill well. The estate also has one worked example of the harder decision — when the right skill is no skill — and it generalises into three governance rules.