# 00 — The Brief: `skills.sgit.ai` **Version** v0.33.62 · 24 August 2026 **From** Dinis Cruz, via the SG/Send Librarian **To** the agent commissioned to build `skills.sgit.ai` **Licence** CC BY 4.0 --- ## 1. The commission > *"a pack around the work we have done around skills, for the `skills.sgit.ai` website."* The work splits cleanly in two, and the site should be built around that split: - **Skills shipped** — 8 real skills on disk, plus a set of authoring conventions nobody has written down. `02__`. - **Skills thought** — **25 dedicated briefs, 60,782 words**, almost all written in one extraordinary week (1–4 June 2026), forming the most complete theory of agent skills in the estate. `01__`, `03__`, `04__`, `05__`. The gap between them is the honesty constraint: **the theory is far ahead of the practice**, and the site must say which is which. --- ## 2. The thesis Stated plainly in the 4 June brief, in the lead's own words: > ***"Skills are code and need to be version-controlled, and need to be treated like software. Skills are a software package, that is the best analogy. Skills are not just a bit of code; skills are like a dependency, and need to be managed just like a dependency. The same way we have npm and pip for managing dependencies, we need a way to manage skills like that."*** And its consequence, which generates most of the site's pages: > *"treat skills the same way you treat code, the same way you version-control it, with **vulnerabilities management, documentation, integration, wrappers, code reviews, deployment, CI pipelines, distribution reviews** — every analogy we have with code, we need with skills."* Plus the sharper claim that makes it more than an analogy: > **Skills are the evolution of code packages, because they describe *intent*, in English, not just capability.** --- ## 3. The four ideas that are original here | # | Idea | The claim | Source | |---|---|---|---| | **1** | **A skill is a projection of a graph** | *"a skill is a projection of a semantic knowledge graph, where **today's skills are static photographs** of what they should be."* Decomposes into typed primitives — principles, concepts, facts, knowledge, actions — and the projection is *"created in the context of use (multilingual, cultural, situational)"* | 4 Jun · 2,993 w | | **2** | **A skill comes with its identity and permission set** | The skills series meets the NHI series: a skill *"must come with the identity and permission set needed to execute it."* Joiner-mover-leaver as the use case; *"a role's needed resources **are** the skill"* | 4 Jun | | **3** | **The OAuth critique, via skills** | *"skills are becoming crazy powerful because they are code, **English is code now**, so they must come with a definition of the permissions they need or they run riot"* — and OAuth *"grants in absolutes, the union of all privileges… forces you to grant a hundred percent when you need ten percent"* | 18 Jun | | **4** | **The base vault and the customisation cascade** | The creator's skill is a **base vault** — *"far more than a SKILL.md, all the materials that make the skill explainable, trustworthy, and executable"* — which forks into branded, certified and customised versions: *"the customised version… is fundamentally what you sell, you maintain it, and that is the one that has the intellectual property element"* | 1 Jun · 2,966 w | And one already claimed elsewhere: **the skill lifecycle** — *"start as massive LLM, held together with string and gum… all the way to code, and it almost becomes a commodity"* with the quotable consequence *"anybody who spends a lot of money on tokens has an engineering problem."* **That is owned by `wardley-maps.sgit.ai`** (`02__` there); this site states it in three lines and links out. `07__` §5. --- ## 4. What is actually shipped — and the honest gap **Eight skills exist on disk:** | Skill | Words | Repo | |---|---:|---| | `create-vault-apps` | 4,907 | `__Send` | | `create-vault-content` | 2,993 | `__Send` | | `create-infographics` | 1,829 | `__Send` | | `use_sgit-and-vaults` | 1,580 | `__Send` | | `use-sg-playwright` | 1,337 / 1,379 | **both repos — divergent copies** | | `talk-to-team__send` | 741 | `__Send` | | `sg-playwright-capabilities` | 1,145 | sg-playwright | **And the theory is unimplemented.** Measured against the June briefs: - **No skill registry, no package manager, no versioned distribution.** The npm-for-skills that the thesis demands does not exist; skills live as folders in two repos, and the sg-playwright skills README says plainly: *"Empty today."* - **No skill has a declared identity or permission set** — idea 2 has zero implementations. - **No skill is a graph projection** — every shipped skill is exactly the *"static photograph"* the theory criticises. - **No marketplace, no scoring, no evals.** The marketplace research is done (2,734 words, with the finding that *"update cadence ranks skills higher in most storefronts than star ratings"*); nothing is built. - **One skill exists in two diverging copies** (`use-sg-playwright`, 1,337 vs 1,379 words) — which is the exact failure mode the skills-are-packages thesis predicts, happening to the estate's own skills. **Publish that; it is the best possible argument for the thesis.** --- ## 5. The one decision with reasons already written The corpus contains a worked example of **when NOT to make a skill**, and it is the best skill-governance artefact in the estate (from the `sg.llm` capability brief): > *"**No — and deliberately.**… A separate `sg.llm` skill would **compete for triggering** with `vault-html-app` on the same intent… and **split the authoring contract across two files. Skills earn their keep when they cover a distinct task**; this is one capability inside an existing one."* Two principles fall out, and both belong on the site as rules: **skills compete for triggering, so overlapping skills are worse than fewer skills**; and **a skill must not become a second source of truth for a contract that lives elsewhere.** --- ## 6. The numbers | | | |---|---| | **Shipped** | **8 skills** · 16,338 words of SKILL.md · 2 repos · 1 divergent duplicate | | **Thought** | **25 dedicated briefs · 60,782 words** · the core written 1–4 June 2026 | | **The June week** | 1 Jun: base vaults, marketplace, opinionated expertise, semantic graphs, CLI comparison · 2 Jun: business knowledge, finance cascade, Tessl monetisation · 3 Jun: provenance · 4 Jun: **six briefs in one day** — packages, graph projection, lifecycle, business capture, OWASP experts, identity | | **Validation** | External, dated: *"one of the feedbacks I got today at the conference is how it's a powerful workflow… the vaults are perfect for capturing skills, version-controlling skills, and customising and selling skills"* | | **Security review** | A skill has been threat-modelled: the Feb 2026 AppSec + DPO + GRC trio on the file-transfer skill — **evidence the "skills are software" discipline was practised, once** | | **This pack** | 9 documents · skill catalogue as JSON · manifest of 30 rows | --- ## 7. Build order 1. **`/catalogue/`** — the 8 shipped skills, generated from their SKILL.md frontmatter. `02__`. Real before theoretical. 2. **`/thesis/`** — skills are software packages, with the full lifecycle list. `03__`. 3. **`/authoring/`** — the conventions extracted from the 8 that exist: the trigger-rich description style, the do-NOT-use clauses, the when-not-to-make-a-skill rules. `02__` §4. **This is the page a visitor can use the same day.** 4. **`/graph/`** — the projection paradigm and typed primitives. `03__` §4. Label it as design, not shipped. 5. **`/identity/`** — a skill comes with its permission set, and the OAuth critique. `05__`. 6. **`/economy/`** — base vaults, the customisation cascade, the marketplace research, Tessl, OWASP experts. `04__`. 7. **`/shipped/`** — §4's gap list, unsoftened, with the diverging duplicate as exhibit A. Publish the build order unresolved with `08__`'s open questions and tensions visible. --- This document is released under the Creative Commons Attribution 4.0 International licence (CC BY 4.0).