# 02 — The shipped skills, and the conventions they encode The only part of the skills work that is `[S]`. Eight skills, 15,911 words of SKILL.md, two repos — and a set of authoring conventions that nobody has written down but every skill follows. **The site's `/authoring/` page falls straight out of this document.** --- ## 1. The catalogue | Skill | Words | What it does | Notes | |---|---:|---|---| | **`create-vault-apps`** | 4,907 | Build a self-contained HTML app inside a vault | The largest; 2 files; carries the `sg.llm.*` how-to | | **`create-vault-content`** | 2,993 | Author `_page.json` layouts and vault content | *"Does NOT require cloning the repo — the full schema reference is embedded"* | | **`create-infographics`** | 1,829 | Drive the SGraph infographic generator API | | | **`use_sgit-and-vaults`** | 1,580 | Clone, commit, push, share vaults via sgit | | | **`use-sg-playwright`** | 1,337 / **1,379** | Drive the browser-automation service over HTTP | ⚠️ **exists in both repos, diverging** — see §3 | | **`sg-playwright-capabilities`** | 1,145 | Read the service's live capability surface | sg-playwright only; carries the *"never the stale capabilities.json"* rule | | **`talk-to-team__send`** | 741 | Bootstrap the agentic team session | The smallest — a pointer skill | Plus the sg-playwright skills `README.md`, which is itself an artefact: *"**Empty today.** Candidates once the service is operational…"* — a skills backlog, written down, with four named candidates. That is skill *planning*, and it is rarer than skill writing. --- ## 2. The authoring conventions, extracted Every shipped skill follows these, and none of them is documented anywhere: **(a) The trigger-rich description.** The frontmatter `description` is not a summary — it is a **retrieval surface**. `create-infographics` names the exact phrases that should fire it (*"infographic", "slide deck", "visual summary", "deck from document"*), the adjacent hosts (*"dev.tools.sgraph.ai", "OpenRouter"*), and the fuzzy cases (*"even if the user just says 'make me a deck'"*). **(b) The do-NOT-use clause.** The same description ends: *"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."* **A skill that says when not to fire is a skill that plays well with siblings** — because skills compete for triggering (§4). **(c) Self-containedness as a feature.** `create-vault-content` embeds the full schema *"so it does not require cloning the repo."* The skill is a package: it carries its dependencies. **(d) Cross-references to canonical contracts, never copies.** `create-vault-apps` *"cross-references the canonical `window.sg` API reference (`AUTHORING.md`)"* rather than duplicating it — the same no-second-source-of-truth rule the `sg.llm` decision applied (§4). **(e) Named-trigger vocabulary.** `talk-to-team__send` enumerates the agent role names that should fire it — "Conductor", "Sherpa", "Librarian" — turning the team's own vocabulary into the trigger set. **Publish these five as the house authoring guide.** They were learned by writing eight skills; a visitor gets them in a page. --- ## 3. ⚠️ The diverging duplicate — exhibit A for the thesis `use-sg-playwright` exists in both repos: **1,337 words in `__Send`, 1,379 in sg-playwright.** Same skill, two copies, already 42 words apart — and one of them carries an auth claim the code contradicts (the `sg-compute` pack, `01__` §4, found the *"401 at the proxy"* sentence is wrong). **This is the skills-are-packages thesis demonstrated on the estate's own skills.** No registry, no single source, no version pin — so the copies drift, and one of them is now wrong. The site should publish this as its opening exhibit: the theory (`03__`) predicts exactly this failure, and here it is, measured, in the estate's own two repos. --- ## 4. When NOT to make a skill — the governance rules The corpus's one worked decision, from the `sg.llm` capability brief, generalises into three rules: 1. **Skills compete for triggering.** *"A separate `sg.llm` skill would compete for triggering with `vault-html-app` **on the same intent**."* Two skills matching one intent is worse than one skill, because the dispatcher must now guess. 2. **A skill must not become a second source of truth.** *"…and split the authoring contract across two files."* If a canonical contract exists, the skill points at it. 3. **Skills earn their keep on distinct tasks.** *"Skills earn their keep when they cover a **distinct task**; this is one capability inside an existing one."* These three rules, plus the five conventions in §2, are the complete authoring guide the estate has been operating with implicitly. **`/authoring/` writes them down.** --- ## 5. The security precedent In **February 2026** — before any of the June theory — the file-transfer skill got a full review trio: an AppSec threat model, a DPO data-flow analysis, and a GRC risk register, all dated 26–27 Feb. That is the *"every analogy we have with code, we need with skills"* discipline actually practised: a skill treated as software, reviewed as software. **Once.** No skill since has had the same treatment, which belongs on `/shipped/` as both the precedent and the lapse. --- This document is released under the Creative Commons Attribution 4.0 International licence (CC BY 4.0).