Skip to content

docs: move web-sdk skills to the web-sdk repo - #16

Open
WiktorStarczewski wants to merge 1 commit into
mainfrom
docs/move-web-sdk-skills-to-web-sdk
Open

docs: move web-sdk skills to the web-sdk repo#16
WiktorStarczewski wants to merge 1 commit into
mainfrom
docs/move-web-sdk-skills-to-web-sdk

Conversation

@WiktorStarczewski

Copy link
Copy Markdown
Contributor

Companion to web-sdk#310, which is where these nine skills now live. Merge that one first — this PR only removes the copies once they have a home.

Moved to 0xMiden/web-sdk, shipped inside the npm packages they document:

Skill Now ships in
web-client-usage, frontend-pitfalls, signer-integration, frontend-source-guide @miden-sdk/miden-sdk
react-sdk-patterns, testing-patterns @miden-sdk/react
vite-wasm-setup @miden-sdk/vite-plugin
idxdb-patterns, wasm-bridge web-sdk's .claude/skills/ — internals, deliberately not published

Everything else stays: the MASM family, rust-sdk-*, rust-client-patterns, miden-concepts, local-node-validation, and all eight slash commands. None of them mentions @miden-sdk/*, which turns out to be a reliable test for where a skill belongs.

Why this content is moving, not disappearing

Two reasons, and the second is the one that motivated the change.

1. Keeping the guidance in sync with the code it describes

These skills document the @miden-sdk/* API. Kept in a separate repo, nothing
ties a skill to the API it describes, so an API change and its documentation
are always two PRs — and the second one is easy to skip. That is not
hypothetical here: every skill shared between agent-tools and
frontend-template had already drifted from its counterpart.

skill agent-tools frontend-template
react-sdk-patterns 386 560
testing-patterns 237 338
frontend-pitfalls 202 186
signer-integration 196 186
frontend-source-guide 174 165
vite-wasm-setup 140 134
miden-concepts 116 110

Living in web-sdk and shipping inside each npm tarball fixes both halves of
that. A change to the API and a change to its documentation become the same
PR, and consumers get guidance version-matched to the release in their
lockfile
— a project pinned to 0.15 reads 0.15 guidance, not whatever HEAD
happens to say. A stale skill is worse than no skill, because an agent will
follow it confidently.

The split is by what the knowledge is about, not by who consumes it:

  • web-sdk owns anything describing the @miden-sdk/* public API.
  • agent-tools stays canonical for everything cross-cutting — the MASM
    family, rust-sdk-*, miden-concepts, local-node-validation, and the
    slash commands.

2. Brownfield projects, which the template cannot reach

The template assumes a clean start: clone the repo, take its submodules, its
layout, its build pipeline. That is the right shape for a proof of concept, and
nothing here changes it.

But most people adding Miden are not starting from nothing. They already have a
codebase, or they are on a template of their own, or they simply would rather
not rebase their project onto someone else's scaffold to adopt one SDK. Total
greenfield is not usually achievable in real work, and it is not a reasonable
precondition for getting good agent guidance.

Shipping the skills through npm means those projects get the same content by
installing the SDK — no clone, no submodules, no adopting a foreign layout.
The template and npm create @miden-sdk then become two doors onto one
knowledge base rather than two competing sources of truth: greenfield keeps
the full scaffold, brownfield gets the guidance alone, and both read the same
files at the same version.

Nothing changes for people using the template

This is transparent for existing template users. Clone the template, run
setup.sh (or npm install directly), and .claude/skills/ is populated with
the same skills as before — the prepare script regenerates them from
node_modules as part of the install the template already runs.

The one difference is when the files appear: they are written during install
rather than arriving with the checkout, because they are now generated rather
than committed. Since setup.sh installs dependencies anyway, a normal setup
sees no difference at all.

Two things actually improve:

  • The skills now match the SDK the template pins. Previously they were a
    snapshot committed at some past point, which is how they drifted in the first
    place. Bump the SDK and re-run install, and the guidance follows.
  • The agent-tools skills stop needing a manual step. Today they are only
    available if the user separately clones agent-tools and symlinks it into
    ~/.claude/skills/ — a machine-global step that most people skip, and that
    the template's own instructions acknowledge much of its guidance depends on.
    Installing them project-locally means a plain clone-and-setup now gets the
    surface the template documents, instead of silently missing it.

What consumers do instead

npm create @miden-sdk@latest

That writes a pointer into the project's AGENTS.md, copies the skills out of node_modules into .claude/skills/, and adds a prepare script so they refresh on every install (web-sdk#311).

Test plan

  • web-sdk#310 merged and released first, so the skills are reachable from npm
  • README links resolve

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant