The skills-first install flow is undocumented — nothing tells users how to install the brmbh skill

[Schmandarine]

The whole point of the pre-scaffold skill (see #6, Layer 1) is that a user says "create a brmbh theme" to their agent and it happens. Nothing in either repo tells anyone how to get that skill onto their machine.

What's missing

Neither README mentions installing a skill at all:

brmbh/cli       README.md → grep "skills.sh|install.*skill" → no hits
brmbh/wordpress README.md → grep "skills.sh|install.*skill" → no hits

skills.sh.json sits in the repo root, unreferenced by any documentation. So the flow the product is designed around is invisible, and the only documented entry point is the command you'd type if you already knew about brmbh:

npm create brmbh@latest my-site

That is the fallback path, not the intended one.

Why this matters more than it looks

Someone who already knows the command does not need brmbh's agentic pitch — they can read a README. The skills-first flow is what makes brmbh different from every other WP starter: the user does not need to know the CLI exists, the agent does. Leaving it undocumented means the differentiator never reaches anyone.

It also makes the CLI's ergonomics ("~5 verbs, --json on everything") pay off, since the agent is the one driving those verbs.

What to add

1. Decide the distribution channel. skills.sh is already set up for it. Claude Code plugins/marketplace is another. Possibly both — they are not exclusive. Whatever is chosen, the skill must land user-level, since at install time there is no project (Adopt the two-layer skills model as an explicit rule (CLI owns pre-scaffold, theme owns in-project) #6).

2. Lead the README with it. Something like:

   ## Install
   
   Give your agent the brmbh skill:
   
       <install command>
   
   Then just ask: "create a brmbh theme in this WordPress install"
   
   Prefer to drive it yourself? `npm create brmbh@latest my-site`

3. Same section in the theme's README, pointing here rather than repeating it (Adopt the two-layer skills model as an explicit rule (CLI owns pre-scaffold, theme owns in-project) #6 rule: no duplication).

4. Verify it end-to-end on a machine with no prior brmbh install: fresh agent session, install the skill, ask in plain language, confirm a working theme comes out.

Acceptance

A person who has never heard of brmbh can, from the README alone, get the skill installed and scaffold a theme by asking their agent in natural language — without ever being told the create command.

Related: #6, #4 (the README URLs are wrong anyway, worth fixing in the same pass)

[Schmandarine]

Scope confirmed: there are two supported install paths, and the README must document both.

1. Skill-first — install the global brmbh skill, ask the agent in plain language, it runs brmbh create. This is the differentiator and currently undocumented (the body of this issue).

2. Theme-first — clone brmbh/wordpress directly, run npm install, work in it. Tracked at brmbh/wordpress#6.

Worth knowing for path 2: the in-theme skills do not invoke this CLI. They call the theme's own tools/*.sh and its wp brmbh WP-CLI subcommand, so a direct clone works without @brmbh/cli installed at all. The plan there is to add @brmbh/cli as a devDependency of the theme rather than having an agent run npm install -g — the CLI then appears via the npm install the setup already performs, pinned per project, nothing installed globally.

That has a consequence for this repo: the README should present the CLI as something users mostly get automatically (via the skill, or via the theme's devDependency), with a global install as the explicit opt-in rather than the headline instruction.

[Schmandarine]

Carries over to brmbh/wordpress — this repo is being archived per brmbh/wordpress#8. The work is still valid; it just lands in packages/cli/ there rather than here. Tracked in the migration checklist on brmbh/wordpress#8.