xstate-v5 — Claude Code skill: XState state machines
Guides an agent through building, reviewing and porting XState v5 machines and statecharts in TypeScript. Useful once screen or process logic outgrows a couple of booleans.
npx skills add statelyai/skills --skill xstate-v5 -a claude-codeWhat xstate-v5 does
The skill puts machine engineering first and API correctness second. The agent picks between xstate and @xstate/store, turns messy requirements into a model, writes v5-style code, and works over what already exists. Old examples and v4-flavoured code get translated instead of copied.
What sits inside is a set of rules, not a code generator. The agent starts from package.json and imports, reads nearby machines and adapters, then decides how opinionated to be. New code gets setup({...}).createMachine({...}) with named actions, guards, actors and delays. Edits to an existing file keep the local structure. Migration is the smallest safe translation to v5, without dragging setup(...) and tags into places that do not need them.
This is v5 only. The agent will not mix versions in one file, so a codebase with machines still on v4 means a gradual port rather than one large commit. When a problem is too small for a machine, the agent says so and points to @xstate/store.
What it helps with
- turn vague requirements into a state machine design
- port a v4 machine to v5 without changing semantics
- split an async workflow into actors with cancellation
- replace redundant context booleans with tags
- wire a machine into
@xstate/reactor@xstate/vue
Example prompts for the agent
- Design a checkout state machine: states, events, actors
- Port this machine to XState v5 and keep the structure
- Review
checkoutMachine.ts— should some context move into tags?
How to install xstate-v5
1Skills CLI (Vercel)
npx skills add statelyai/skills --skill xstate-v5 -a claude-code2Manually: put the files in place
~/.claude/skills/xstate-v5/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/xstate-v5/
1Skills CLI (Vercel)
npx skills add statelyai/skills --skill xstate-v5 -a codex2Manually: put the files in place
.agents/skills/xstate-v5/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add statelyai/skills --skill xstate-v5 -a cursor2Manually: put the files in place
.cursor/skills/xstate-v5/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install statelyai/skills xstate-v52Manually: put the files in place
.github/skills/xstate-v5/SKILL.md1Skills CLI (Vercel)
npx skills add statelyai/skills --skill xstate-v5 -a gemini-cli2Platform CLI
gemini skills install https://github.com/statelyai/skills --path skills/xstate-v5Manually: put the files in place
.devin/skills/xstate-v5/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add statelyai/skills --skill xstate-v5 -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about xstate-v5
How do I install xstate-v5 in Claude Code?
Run npx skills add statelyai/skills --skill xstate-v5 -a claude-code. The skill file lands at ~/.claude/skills/xstate-v5/SKILL.md.
What does xstate-v5 do?
It steers the agent through designing, writing, reviewing and porting XState v5 machines and statecharts in TypeScript. It also tells you when a machine is overkill and @xstate/store fits better.
Does the skill handle legacy XState v4 code?
Yes, through a migration mode. The agent makes the smallest safe translation to v5 and keeps the existing structure unless you ask for a broader rewrite.
