SKILL.md
XState
Use XState when the domain has meaningful modes, transitions, async lifecycle, cancellation, guards, delays, or actor boundaries. The goal is not "state management"; the goal is to make the process explicit, typed, inspectable, and hard to misuse.
Core Standard
- Prefer
setup({ types, actors, actions, guards, delays }).createMachine(...)for typed machines with named implementations. - Put finite modes in states.
- Put durable facts in context.
- Put side effects behind actors, actions, guards, and delays.
- Put request data in
invoke.input. - Put UI decisions on snapshots:
matches,hasTag,can, and selected context. - Initialize each actor instance with
input. - Define default implementations in
setup(...); replace runtime implementations with.provide(...). - Model later external changes as keyed remounts, domain events, or subscription actors.
Reading Guide
Read only the references needed for the task:
- [Modeling](references/modeling.md): states, state types, context, events, guards, tags, delays.
- [Transitions](references/transitions.md): guarded, eventless, delayed, and pure transitions.
- [Actors](references/actors.md): async work, actor choice, invocation, outputs, cancellation.
- [Promises](references/promises.md):
fromPromise, request input, output, errors, abort signals. - [Callbacks](references/callbacks.md): subscriptions, imperative APIs,
sendBack,receive, cleanup. - [Observables](references/observables.md): observable snapshots and observable event streams.
- [Child Actors](references/child-actors.md):
invoke,spawn,spawnChild, child ownership, inspection. - [React](references/react.md):
@xstate/react,.provide(...), actor input, selectors. - [Testing](references/testing.md): actor tests,
waitFor, provided implementations, timing.
Working Loop
- Name the process and its legal modes.
- Define the domain events.
- Decide what data survives transitions.
- Move effects into actors or named implementations.
- Connect UI through actor hooks and snapshot reads.
- Test behavior at the actor boundary.