docs: move web-sdk skills to the web-sdk repo - #16
Open
WiktorStarczewski wants to merge 1 commit into
Open
Conversation
2 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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:web-client-usage,frontend-pitfalls,signer-integration,frontend-source-guide@miden-sdk/miden-sdkreact-sdk-patterns,testing-patterns@miden-sdk/reactvite-wasm-setup@miden-sdk/vite-pluginidxdb-patterns,wasm-bridge.claude/skills/— internals, deliberately not publishedEverything 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, nothingties 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-toolsandfrontend-templatehad already drifted from its counterpart.Living in
web-sdkand shipping inside each npm tarball fixes both halves ofthat. 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:
@miden-sdk/*public API.family,
rust-sdk-*,miden-concepts,local-node-validation, and theslash 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-sdkthen become two doors onto oneknowledge 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(ornpm installdirectly), and.claude/skills/is populated withthe same skills as before — the
preparescript regenerates them fromnode_modulesas 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.shinstalls dependencies anyway, a normal setupsees no difference at all.
Two things actually improve:
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.
agent-toolsskills stop needing a manual step. Today they are onlyavailable if the user separately clones
agent-toolsand symlinks it into~/.claude/skills/— a machine-global step that most people skip, and thatthe 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
That writes a pointer into the project's
AGENTS.md, copies the skills out ofnode_modulesinto.claude/skills/, and adds apreparescript so they refresh on every install (web-sdk#311).Test plan