No way to pull improved agent skills into an already-scaffolded site

[Schmandarine]

The agent skills are the product. Today they can only ever be as good as they were on the day a site was scaffolded — there is no path for an improved skill to reach an existing site other than manual copy-paste between projects.

Orientation — how skills currently work

The starter theme carries a canonical AGENTS/ folder. As of writing it holds 10 skills:

check-versions.md  create-block.md  delete-block.md  deploy.md      edit-block.md
list-blocks.md     sync-db.md       sync-plugins.md  sync-tokens.md sync-uploads.md

generateSkillWrappers(themeDir) (src/commands/add.js:199) reads those AGENTS/*.md files and writes one thin wrapper per skill per agent — .claude/commands/<name>.md, .cursor/rules/<name>.mdc, .windsurf/rules/<name>.md. Each wrapper is three lines: frontmatter with a description derived from the skill's first prose line (deriveDescription(), src/commands/add.js:228) plus "Read AGENTS/<name>.md and execute the skill defined there."

So AGENTS/ is the single source of truth and the wrappers are disposable. That design is right — it's the refresh path that's missing.

It runs in two places: create step 4 (src/commands/create.js:73-77) and brmbh add skills (src/commands/add.js:180).

The problem

Both call sites pass the local theme directory. brmbh add skills therefore regenerates wrappers from the site's own AGENTS/ folder — a copy made at scaffold time and never refreshed since. The command re-derives wrappers from stale source and reports success.

When a skill is improved in the starter repo, no existing site sees it. With multiple client sites in flight, they silently drift to different skill versions, and nothing in the CLI reports which version a site is on.

Proposal

brmbh skills update (or add skills --from-upstream — naming worth deciding; add skills currently means "regenerate wrappers", which is a different verb).

1. Fetch AGENTS/ from the starter repo. Reuse materializeTheme()'s source resolution (src/registry.js) so --from <local-checkout> and --ref <branch> work the same as in create.
2. Diff against the local AGENTS/. Show added / changed / removed skills by name.
3. Prompt before writing (or require --yes for non-interactive and --json use).
4. Overwrite the changed skill sources, then call the existing generateSkillWrappers() to rebuild wrappers.

Deliberately narrow: AGENTS/ only. Not inc/, not webpack.config.js, not blocks. Agent instructions are not project code, so refreshing them is safe. Refreshing anything else risks clobbering client work and needs its own design — do not let this issue grow into "upgrade the theme".

Note that skills/wordpress/SKILL.md and skills.sh.json also exist in both repos and are a separate distribution mechanism. Worth checking whether they need the same treatment or are already generated.

Prerequisite: record where a scaffold came from

materializeTheme() returns { source: 'git', repo, ref: ref ?? 'default' } (src/registry.js:53) — no commit SHA. create puts that in its result envelope but writes nothing to disk, so a scaffolded site has no record of which starter version it came from. Without that, the update command can only diff file contents, and can never say "you are 3 commits behind".

Resolve the actual SHA at scaffold time (git ls-remote <repo> <ref> before cloning, or git rev-parse HEAD inside the clone before .git is deleted) and write it into the scaffold.

Do not use .brmbh-config.json — it is gitignored in the theme repo and holds Figma API tokens. Provenance needs to be committed and non-secret. Options: a new .brmbh-scaffold.json, or a "brmbh" key inside the theme's package.json. Suggested shape:

{ "starter": { "repo": "…", "ref": "main", "commit": "abc1234", "scaffoldedAt": "2026-07-29" } }

This also makes scaffolds reproducible, which is worth having on its own.

Open questions

• Should a site be able to keep local edits to a skill? Simplest v1: overwrite and rely on git for recovery. Worth confirming that is acceptable before building anything cleverer.
• What happens to a skill that was removed upstream — delete the local copy and its three wrappers, or leave it?
• Should doctor (src/commands/doctor.js) grow a check that reports when a site's skills are behind upstream?

[Schmandarine]

Dissolved by brmbh/wordpress#8. The AGENTS/*.md skills move into the @brmbh/cli npm package, and the theme carries it as a devDependency — so npm update @brmbh/cli refreshes the skills. No bespoke update command, no provenance SHA needed for this purpose; npm is the mechanism.

The one idea worth keeping: a project-local AGENTS/ override that wins over the package copy, so a customized skill does not cost you updates to the others. Captured in brmbh/wordpress#8.