Adopt the two-layer skills model as an explicit rule (CLI owns pre-scaffold, theme owns in-project)

[Schmandarine]

brmbh has two distinct kinds of agent skill. The distinction is already implemented and already documented — but only inside one file, in the wrong repo, in a copy that exists twice. Writing it down as an architectural rule resolves #5, sharpens #3, and gives us a test for where future work belongs.

The two layers

Layer 1 — pre-scaffold (global, one skill). Runs on a machine where no brmbh theme exists yet. Its job: know brmbh exists, check prerequisites (Node 18+, git, wp-cli, SCF), run create in the right directory, interpret doctor --json, hand off. Has no project to read, so it must be installed user-level (~/.claude/skills/, or as a plugin), not into a project.

Today this is skills/wordpress/SKILL.md + skills.sh.json.

Layer 2 — in-project (ships with the theme, currently 10 skills). create-block, edit-block, list-blocks, delete-block, sync-tokens, deploy, sync-db, sync-plugins, sync-uploads, check-versions. Every one of them operates on an existing theme — useless without a project. Canonical source is the theme's AGENTS/*.md; generateSkillWrappers() (src/commands/add.js:199) emits the per-agent wrappers.

The handoff between layers is already written: skills/wordpress/SKILL.md has a "Handoff to in-theme skills" section that says in-theme skills take over once doctor reports ready. The model is sound. It's the ownership that was never settled.

The rule to adopt

The CLI owns Layer 1. The theme owns Layer 2. Neither layer is duplicated across repos.

Rationale: Layer 1 documents how to install and drive the CLI — its skills.sh.json manifest even declares "name": "@brmbh/cli". Layer 2 describes operations on theme files and must travel with the theme it targets.

What follows from it

• skills.sh.json and skills/wordpress/SKILL.md are duplicated across both repos with no sync #5 is decided: skills.sh.json and skills/wordpress/SKILL.md live in this repo only. brmbh/wordpress deletes its copies and links here instead. (Tracked on the theme side at Remove the duplicated pre-scaffold skill files (CLI owns Layer 1) wordpress#2.)
• No way to pull improved agent skills into an already-scaffolded site #3 is scoped: "updating skills" only ever means Layer 2 — pulling fresh AGENTS/*.md from the theme repo into an existing site. Layer 1 updates by updating the CLI, which npm already handles. No new mechanism needed there.
• New work has a home: anything needing a project → Layer 2, in the theme. Anything about getting brmbh onto a machine → Layer 1, here.

Tasks

• Write the rule into this repo's README (a short "Skills: two layers" section)
• Mirror it in the theme's AGENTS.md, which already documents Layer 2 but never names Layer 1
• Close out skills.sh.json and skills/wordpress/SKILL.md are duplicated across both repos with no sync #5 by deleting the theme-side copies (Remove the duplicated pre-scaffold skill files (CLI owns Layer 1) wordpress#2)
• Retitle/rescope No way to pull improved agent skills into an already-scaffolded site #3 to "update in-project (Layer 2) skills"

Open question

Does Layer 1 stay a single skill? It currently covers scaffold + doctor + troubleshooting + a full CLI reference in one file. That is fine while it is one document, but if it grows, splitting by task (install / diagnose) is likely better than one long file the agent reads in full every time.

Related: #1, #3, #4, #5 · brmbh/wordpress#2

[Schmandarine]

Correction — I had the ownership backwards.

The body concludes "the CLI owns Layer 1". That is wrong, because of how the skill is actually distributed:

npx skills add brmbh/wordpress     # ← resolves against the THEME repo

This is the verified-working install path (confirmed live 2026-07-13). npx skills add clones github.com/brmbh/wordpress and reads its skills.sh.json to resolve the skill. So the theme repo's copy of skills.sh.json + skills/wordpress/SKILL.md is load-bearing — it is what makes the documented install command work at all.

The redundant copy is the one in this repo.

That inverts #5 and brmbh/wordpress#2: the theme keeps both files, this repo drops them (or keeps them only if npx skills add @brmbh/cli is meant to stay a supported second channel — currently documented in the vault dashboard as working).

The two-layer model still holds — a pre-scaffold skill and in-project skills are genuinely different things. Only the ownership conclusion was wrong.

Superseded in part by #8: if the CLI is retired, the theme owns both layers by default and this issue reduces to writing the distinction into AGENTS.md.

[Schmandarine]

Resolved structurally by brmbh/wordpress#8 rather than by documentation. The two layers become physically distinct:

• Layer 1 (pre-scaffold) — skills/wordpress/SKILL.md + skills.sh.json at the root of brmbh/wordpress, installed via npx skills add brmbh/wordpress
• Layer 2 (in-project) — AGENTS/*.md inside the @brmbh/cli package, consumed by each theme as a devDependency

Ownership is no longer ambiguous because there is one repo. The remaining task — stating the distinction in AGENTS.md — carries over to brmbh/wordpress#8.