From 0c6e79e6f0033dfd78c82c7604cf0ebcd3f8cced Mon Sep 17 00:00:00 2001 From: "Carlos D. Escobar-Valbuena" Date: Fri, 26 Jun 2026 22:51:57 -0500 Subject: [PATCH] docs(roster): add skill-publishing layout standard (BRO-1561) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A skill must live in skills// — a top-level SKILL.md + sibling scripts/ at a repo root installs only SKILL.md via remote `npx skills add` (CLI repo-root special-case), yielding a non-functional skill. Document the standard, the why, the keep-your-repo-name fix, and the validation discipline (--list is necessary not sufficient; runnable clean-room install is the gate; skillify enforces it). BRO-1561 Co-Authored-By: Claude Opus 4.8 (1M context) --- references/skills-roster.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/references/skills-roster.md b/references/skills-roster.md index 1d952b5..7213617 100644 --- a/references/skills-roster.md +++ b/references/skills-roster.md @@ -2,6 +2,19 @@ 28 curated skills across 7 layers. The Broomva Stack. +## Publishing standard (skill layout) — required for installability + +A skill is a **folder**, per the [Agent Skills standard](https://agentskills.io) — `SKILL.md` + optional `scripts/` / `references/` / `assets/`. **Publish every multi-file skill in a `skills//` subdirectory of its repo — never as a bare top-level `SKILL.md` at the repo root.** + +| Layout | Remote `npx skills add` | | +|---|---|---| +| `skills//{SKILL.md, scripts/…}` | installs the **full** skill | ✅ standard | +| top-level `SKILL.md` + sibling `scripts/` at repo root | installs **only `SKILL.md`** — scripts dropped → non-functional | 🔴 broken (BRO-1561) | + +**Why:** the vercel-labs/skills CLI special-cases a repo-root `SKILL.md` and copies only that file (a repo root carries `README`/`LICENSE`/`.github` — not a clean skill folder). A `skills//` subdir is a clean folder and is fully copied. A repo can keep its name and still be standard: `git mv SKILL.md scripts/ → skills//`; `npx skills add broomva/` still works (the CLI's `skills/` priority-search finds the subdir). + +**Validation:** `--list` is **necessary but not sufficient** — it only parses frontmatter, never the file-copy path, so it passes even when the install drops `scripts/`. The real gate is a **clean-room install that yields a *runnable* skill** (bundled files land + the skill's own test passes). The `skillify` skill machine-enforces this (`skillify_check.py` step 1 FAILs a repo-root-with-bundled-dirs layout). Full proof + root cause: `research/entities/tool/skills-sh.md`. + ## Foundation — Control & Governance | # | Skill | Install | Description |