# Proposal: a shared skill-catalog standard across the factory

**Status: proposal for the cross-repo parts only.** `common` itself now has a
real, implemented catalog (see below) — that part is no longer a proposal.
The cross-repo recommendations (hosting a shared schema in `actions`,
touching `bluefin-lts`/`testsuite`/`clankers`/`hive`) are still proposals and
require a human Design-gate decision (see
[`docs/skills/human-gates.md`](../skills/human-gates.md)) before any other
repo builds or changes anything described here. No sibling repo (`actions`,
`bluefin-lts`, `testsuite`, etc.) has been touched to produce this proposal.

## Why this exists

A 2026-07-29 audit of `common`'s `docs/skills/` system found the catalog
fields (`id`, `category`, `mcp_compliance_level`, `optimization_status`,
`dependencies`, `status`, `entry_point`, `one_line_purpose`) already present,
for real, on 6 of 38 skill files on `origin/main`
(`skill-improvement.md`, `hosted-hive.md`, `hosted-hive-clankers.md`,
`hive.md`, `hive-review.md`, `factory-onboarding.md`) — a partial,
in-progress, already-committed rollout, not the phantom local-only draft
this proposal originally described. (An unrelated, separate local `main`
branch with 3 unpushed commits carrying its own divergent `index.json`
implementation was also found and is *not* part of this work — see
"Explicitly out of scope" below.)

Given that partial rollout was already real and committed, `common` finished
it: all 39 skills (38 flat + `docs/skills/lab-testing/SKILL.md`) now carry
the same 8 catalog fields consistently, 13 files' corrupted `description`
front matter (a stray `" type: <word>` fragment leaking past the closing
quote — an artifact of whatever produced the partial rollout) was fixed, and
`scripts/generate_skill_index.py` compiles them into
[`docs/skills/index.json`](../skills/index.json) /
[`index.md`](../skills/index.md), validated against
[`docs/skills/index.schema.json`](../skills/index.schema.json) (JSON Schema
2020-12) and enforced by a `check-skill-catalog` pre-commit hook. See
[`write-a-skill.md`](../skills/write-a-skill.md) for the full field
reference.

While confirming that state, a survey of every sibling factory repo on disk
(`bluefin`, `bluefin-lts`, `dakota`, `knuckle`, `testsuite`, `actions`,
`bonedigger`, `clankers`, `hive`) found real, useful divergence worth
proposing a cross-repo standard for — summarized below.

## Current state (verified 2026-07-29)

| Repo | Router | Skill shape | Machine catalog | Validator |
|---|---|---|---|---|
| `common` | `docs/SKILL.md` | flat `docs/skills/*.md` (+ one migrated `docs/skills/lab-testing/SKILL.md`) | **implemented**: `docs/skills/index.json`/`index.md`, generated by `scripts/generate_skill_index.py`, validated against `docs/skills/index.schema.json` | `check-skill-frontmatter.sh`, `check-skill-index.sh`, `generate_skill_index.py --check` |
| `bluefin` | `docs/SKILL.md` | flat | none | none found |
| `bluefin-lts` | `docs/skills/INDEX.md` | per-skill directories, `name`+`description` only front matter | none (hand-maintained `INDEX.md`) | `scripts/check-skill-docs.py` — link-integrity + directory/name consistency + 500-line hard cap |
| `dakota` | `docs/SKILL.md` + `docs/skills/INDEX.md` | flat (~28 files) | none (the only `index.json` present is an unrelated OCI build artifact under `.build-out/`) | none found |
| `knuckle` | `docs/SKILL.md` | flat, smallest set | none | none found |
| `testsuite` | `docs/skills/index.md` | category-named subfolders (`ci-ops/`, `meta/`, `test-authoring/`, plus an ad hoc `flatpak-screenshots/`) | **design-only**: `docs/superpowers/specs/2026-07-28-skill-discovery-index-design.md` proposes a schema that closely mirrors `common`'s now-implemented catalog, unimplemented | none yet |
| `actions` | `docs/SKILL.md` | flat + two reference subfolders | none (has an unrelated `docs/schemas/release-state.schema.json`) | none |
| `bonedigger` | `agents.md` (no `SKILL.md`) | flat | none | none |
| `clankers` | none | none | none | none |
| `hive` | none | none | none | none |

## Confirmed, independent-of-this-proposal bug

`projectbluefin/actions`' `.github/workflows/skill-drift-check.yml` — the
reusable workflow every consumer repo's `skill-drift.yml` calls — is
currently a **no-op stub** (real logic removed in `actions@001ae97`, replaced
with a compatibility stub in `actions@a7c230c`). It always exits 0 without
inspecting any changed paths. Every repo above that has a `skill-drift.yml`
(bluefin, bluefin-lts, dakota, knuckle, testsuite) is getting a silent,
always-green result. `common` does not run it at all (see
[`ci-tooling.md`](../skills/ci-tooling/references/pre-commit-conventions.md#skill-drift-detection)). This is
already corrected in `common`'s own docs
([`skill-drift.md`](../skills/skill-drift.md),
[`factory-onboarding.md`](../skills/factory-onboarding.md)) as part of the
same PR that added this proposal — it is not itself a proposal, it is a
verified fact.

## Proposed direction (needs human sign-off before any *other* repo acts on it)

1. **Don't let each remaining repo reinvent a JSON catalog independently.**
   `common` now has a working, reviewed implementation
   (`index.schema.json` + `generate_skill_index.py` + `index.json`);
   `testsuite` has an unimplemented design that mirrors it closely. Use
   `common`'s implementation as the reference design for a shared schema
   rather than each repo drafting a similar-but-incompatible one.
2. **Host the canonical JSON Schema in `projectbluefin/actions`.** `actions`
   already hosts reusable workflows every repo consumes (including the
   skill-drift check); it's the natural place for one `skill-index.schema.json`
   referenced by every repo's generator, instead of drifting per-repo copies.
   `common`'s `docs/skills/index.schema.json` is offered as the starting
   point for that shared copy.
3. **Keep per-repo front matter minimal where a catalog isn't wanted.**
   `bluefin-lts` and `knuckle` currently ship minimal front matter (`name` +
   `description`) and neither needs a catalog to function. Any shared schema
   should make catalog-only fields (`category`/`mcp_compliance_level`/
   `optimization_status`/`dependencies`/`status`/`id`/`one_line_purpose`/
   `entry_point`) **optional and additive** so a repo can adopt the catalog
   without being forced to restructure front matter it doesn't use.
4. **~~Rebuild or remove `skill-drift-check.yml`.~~ RESOLVED — removed.** The
   factory chose removal: every consumer repo deleted its `skill-drift.yml`
   and the stub was deleted from `actions`. Leaving it as a silently-passing
   no-op was worse than having no check at all, because it looked like
   enforcement. Retirement record:
   [`skill-drift.md`](../skills/skill-drift.md).
5. **Genericize `bluefin-lts`'s `check-skill-docs.py`.** It's the only real
   link-integrity + directory/name-consistency validator anywhere in the
   factory. `common`'s own `check-skill-frontmatter.sh` /
   `check-skill-index.sh` only check front-matter shape and router-table
   presence, not that every relative link inside a skill body resolves
   (`common` separately gained a `check-doc-links.sh` hook that covers this
   for its own docs, but it isn't shared tooling). Consider porting
   `check-skill-docs.py`'s link-checking logic into a shared `actions`
   script/action all repos can call.
6. **Bootstrap `clankers` and `hive` with the minimal flat pattern**
   (`AGENTS.md` → `docs/SKILL.md` → `docs/skills/*.md`), not a per-skill-directory
   or JSON-catalog pattern — they have zero skill-system state today, so
   starting with `bluefin`/`knuckle`'s simplest shape is proportionate; a
   catalog can be added later if/when this proposal is adopted.
7. **If `testsuite` wants to proceed with its design doc**, coordinate first
   rather than building independently — their spec already assumes close to
   the same field set `common` now implements, so adopting a shared schema in
   `actions` (point 2) would let both repos consume the same contract instead
   of two hand-maintained copies drifting apart.

## Explicitly out of scope for this proposal

- No changes to `actions`, `bluefin`, `bluefin-lts`, `dakota`, `knuckle`,
  `testsuite`, `bonedigger`, `clankers`, or `hive`. Those require their own
  PRs, reviewed by their own maintainers, in their own repos.
- The separate, unrelated local `main` branch in this `common` checkout that
  carries 3 unpushed commits (`0e511f5`, `d5c90a7`, `74f9a42`) with its own
  divergent `index.json`/`index.schema.json`/`generate_skill_index.py` draft
  is not part of this work and was not merged, cherry-picked, or otherwise
  incorporated — the catalog built here was written fresh against
  `origin/main`, reconciling only the real, already-committed 6-file partial
  rollout described above. Whether to keep, rebase, or drop those 3 local
  commits is a decision for whoever authored them.

## Verification

- Dead workflow: `git -C <actions checkout> show
  a7c230c:.github/workflows/skill-drift-check.yml` — confirms the no-op stub
  body and the "restore ... as a no-op stub for consumer compat" commit
  message.
- Partial rollout on `origin/main`: `git show origin/main:docs/skills/hive.md
  | head -15` (and the other 5 files named above) — confirms the catalog
  fields were already real and committed before this proposal's changes.
- `common`'s implemented catalog: `python3 scripts/generate_skill_index.py
  --check` — regenerates and diffs `docs/skills/index.json`/`index.md`
  against the current front matter.
- Separate local-only commits (not part of this work): `git -C <common
  checkout> log --oneline origin/main..main` — lists the 3 unpushed commits
  not present on any remote branch.
- `testsuite` design doc: `docs/superpowers/specs/2026-07-28-skill-discovery-index-design.md`
  in the `testsuite` checkout.
- `bluefin-lts` validator: `scripts/check-skill-docs.py` in the `bluefin-lts`
  checkout.
