Install from the generated bundle. Individual procedure directories include their required references, including voice architecture and ADRs. The authored GitHub tree uses a different shared-reference layout.
For only debugging, replace --skill '*' with --skill maelstrom maelstrom-debugging. Keep the entry skill so the same starting request still works. Copy whole directories for a manual installation.
Verify discovery
List the installation for your selected agent. Replace pi with opencode or claude-code when needed.
bunx skills@1.7.0 list --agent pi
Expect maelstrom and seven procedure names. Restart or reload an already running coding agent so it discovers the new files.
Show the Maelstrom skills available in this project. Read the maelstrom entry skill and report its task procedures. Do not edit files or install packages.
Check that the agent reads this project's installed files. An installer listing proves files are present; it does not prove the agent loaded or followed them. Automatic selection depends on the agent. Explicitly request maelstrom when needed.
Run a safe first task
Plan a first integration
Use the maelstrom skill to inspect this app and plan one bounded Maelstrom integration. Report the selected capability, installed SDK versions, verification plan, and rollback. Do not edit files or install packages.
Expect one selected procedure, evidence from your app, a bounded pilot, and a verification/rollback plan. With no SDK installed, expect the agent to say which API details remain unverified.
Authorize a bounded implementation
Use the maelstrom skill to implement only the approved integration described below. Preserve application data, authorization, and the legacy path. Run the relevant typecheck, tests, and lint. Report live Engine checks separately. Approved goal: [describe the bounded capability].
Use this only after you approve the goal. Implementation must preserve application-owned data and authorization. Local tests and typechecks do not establish live Engine or microphone success.
Prefer a one-off instruction? The standalone prompt library needs no skill installation. Its onboarding prompt defaults to planning unless implementation authority is explicit.
Choose your task
The entry skill routes by the primary outcome. Use one procedure at a time; voice is optional.
Plan a first integration
Inspect an existing app and choose one useful pilot.
Procedure: maelstrom-project-onboarding
Installation: included in the complete bundle above.
Install only this procedure and the entry skill
bunx skills@1.7.0 add https://docs.maelstrom-ai.co/agents/skills/bundle.zip --skill maelstrom maelstrom-project-onboarding --agent pi --copy
Replace pi with your selected agent target. Choose Project at the scope prompt.
Use the maelstrom skill to inspect this app and plan one bounded Maelstrom integration. Report the selected capability, installed SDK versions, verification plan, and rollback. Do not edit files or install packages.
Expected evidence: An observed capability, exact installed versions or their absence, and a plan with no edits.
Model a capability
Decide which user-visible capability should become a Vessel.
Procedure: maelstrom-vessel-modeling
Installation: included in the complete bundle above.
Install only this procedure and the entry skill
bunx skills@1.7.0 add https://docs.maelstrom-ai.co/agents/skills/bundle.zip --skill maelstrom maelstrom-vessel-modeling --agent pi --copy
Replace pi with your selected agent target. Choose Project at the scope prompt.
Use the maelstrom skill to plan a Vessel for [existing capability]. Derive Variants and Actions only from observed behavior. Explain the Engine value and application ownership. Do not edit files.
Expected evidence: Source-backed Variants and Actions; incidental controls stay inside the capability.
Migrate a React capability
Keep the legacy behavior while moving one bounded slice.
Procedure: maelstrom-react-migration
Installation: included in the complete bundle above.
Install only this procedure and the entry skill
bunx skills@1.7.0 add https://docs.maelstrom-ai.co/agents/skills/bundle.zip --skill maelstrom maelstrom-react-migration --agent pi --copy
Replace pi with your selected agent target. Choose Project at the scope prompt.
Use the maelstrom skill to plan migrating [React capability] behind its existing route or flag. Preserve application-owned data and effects. Report parity tests and rollback. Do not edit files.
Expected evidence: Installed React API evidence, a reversible boundary, and parity tests to run.
Diagnose a failure
Find the failure layer from code and redacted observations.
Procedure: maelstrom-debugging
Installation: included in the complete bundle above.
Install only this procedure and the entry skill
bunx skills@1.7.0 add https://docs.maelstrom-ai.co/agents/skills/bundle.zip --skill maelstrom maelstrom-debugging --agent pi --copy
Replace pi with your selected agent target. Choose Project at the scope prompt.
Use the maelstrom skill to diagnose [symptom] from the installed SDK, code, and redacted evidence. Separate observations from hypotheses. Do not implement a fix yet.
Expected evidence: A supported diagnosis or the missing observation; local checks are distinct from live Engine checks.
Add observability
Select the events needed to explain one production behavior.
Procedure: maelstrom-observability
Installation: included in the complete bundle above.
Install only this procedure and the entry skill
bunx skills@1.7.0 add https://docs.maelstrom-ai.co/agents/skills/bundle.zip --skill maelstrom maelstrom-observability --agent pi --copy
Replace pi with your selected agent target. Choose Project at the scope prompt.
Use the maelstrom skill to plan observability for [behavior]. Verify installed event APIs and choose bounded, redacted payloads. Do not edit files or log credentials or user content.
Expected evidence: Verified event names, payload boundaries, and privacy-safe verification.
Synchronize state
Update a Vessel definition or Instance without losing application state.
Procedure: maelstrom-state-sync
Installation: included in the complete bundle above.
Install only this procedure and the entry skill
bunx skills@1.7.0 add https://docs.maelstrom-ai.co/agents/skills/bundle.zip --skill maelstrom maelstrom-state-sync --agent pi --copy
Replace pi with your selected agent target. Choose Project at the scope prompt.
Use the maelstrom skill to plan synchronizing [external change] with this Vessel. Inspect registration, live Instances, and update conflicts. Preserve application-owned state. Do not edit files.
Expected evidence: The supported update path, complete definition preservation, and an explicit conflict policy.
Plan optional voice
Add voice only when the product goal requires it.
Procedure: maelstrom-voice-integration
Installation: included in the complete bundle above.
Install only this procedure and the entry skill
bunx skills@1.7.0 add https://docs.maelstrom-ai.co/agents/skills/bundle.zip --skill maelstrom maelstrom-voice-integration --agent pi --copy
Replace pi with your selected agent target. Choose Project at the scope prompt.
Use the maelstrom skill to plan optional voice for [intent]. Provider and deployment are undecided. Keep those choices open, inspect the bundled architecture and ADRs, and make no edits or installations.
Expected evidence: Browser/server/worker boundaries, unresolved choices, and untested microphone/provider scenarios.
Load installed SDK guidance
The workflow bundle is independent of SDK dependencies. Package API guides live under node_modules/@maelstrom-co/<package>/skills/. The installed package's manifest is the version authority.
After SDK installation, add a reviewed Intent development dependency and commit the lockfile. Intent setup is optional for the first planning task.
bun add --dev --exact @tanstack/intent@0.5.3
Run setup in an interactive terminal. Review the permitted package sources and generated guidance before confirming. It writes package permissions and agent instructions; it does not install a Maelstrom SDK.
./node_modules/.bin/intent install
Use the pinned local CLI to inspect available guides and load the React guide:
./node_modules/.bin/intent list --json
./node_modules/.bin/intent load @maelstrom-co/react#maelstrom-react-sdk --json
Expect the installed package version and readable guide path. Review generated commands if they use @latest instead of the lockfile version. Intent discovery, permission, loading, and correct application are separate checks. See the Intent consumer guide.
Update and remove
For a Vercel Skills installation, rerun the original add command to refresh from the current docs bundle. To remove only Maelstrom skills, use their names and the original agent target:
Replace the agent target as needed. Keep unrelated skills. SDK updates use your project's package manager and update their packaged API guides independently.
Other installation owners
For a manual install, replace the Maelstrom directories with a newer bundle. Remove only those directories when uninstalling.
For a Maelstrom repository checkout, use bun run --cwd apps/docs skills:install, skills:update, or skills:remove. These scripts manage .agents/skills/ and should not update a Vercel Skills installation.
Troubleshoot discovery
The installer lists the skill, but the agent does not
Check the selected agent, project directory, trust/skill permissions, and reload behavior. Ask it to read the installed entry file. Do not treat a global installation as a project installation.
A referenced file is missing
Refresh from the generated ZIP and copy the complete procedure directory. A copied SKILL.md from GitHub does not include build-generated references.
Intent finds no guides
Check that the SDK is installed, run from the owning workspace, and review intent.skills/intent.exclude. Planning can continue without SDK APIs.
A guide disagrees with an API
Check the installed package manifest, exported declarations, and runtime entrypoint. Runtime JavaScript can be bundled in dist/index.js; declaration subpaths do not imply matching JavaScript files.
The agent loads the wrong workflow
State the primary outcome and authority explicitly. Ask it to load maelstrom, select one procedure, and report which installed guide supports its API claims.
The bundle cannot be downloaded
Check the download response and docs deployment. Use the manual download only from a build with the required references. SDK package access is a separate private beta setup.