state-machine · owl-listener — Claude Code skill: what it does, how to install
Models UI component behavior as explicit states, events, and transitions. Useful when a component has multiple interacting states that must remain predictable.
npx skills add Owl-Listener/designer-skills --skill state-machine -a claude-codeWhat state-machine does
This skill structures complex UI components as finite state machines to prevent conflicting states like displaying loading and error indicators at the same time. It deconstructs an interface into five building blocks: distinct states, triggering events, transitions, side-effect actions, and guard conditions.
The workflow starts by mapping all possible states and events, then defines valid transitions and eliminates edge-case conflicts. It mandates starting with the happy path, avoiding dead-end states, and tying every state to a concrete visual presentation. For tactile feedback or single-interaction animations, this skill steps aside — use micro-interaction-spec instead.
What it helps with
- Eliminate impossible UI states
- Map transitions and guards for multi-step wizards
- Define predictable data fetching flows
- Align component logic between design and engineering
Example prompts for the agent
- Model a finite state machine for an authentication form with retries
- Define states, events, and transitions for a checkout wizard
- Review this data fetching component and eliminate impossible states
How to install state-machine
1Skills CLI (Vercel)
npx skills add Owl-Listener/designer-skills --skill state-machine -a claude-code2Manually: put the files in place
~/.claude/skills/state-machine/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/state-machine/
1Skills CLI (Vercel)
npx skills add Owl-Listener/designer-skills --skill state-machine -a codex2Manually: put the files in place
.agents/skills/state-machine/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add Owl-Listener/designer-skills --skill state-machine -a cursor2Manually: put the files in place
.cursor/skills/state-machine/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install Owl-Listener/designer-skills state-machine2Manually: put the files in place
.github/skills/state-machine/SKILL.md1Skills CLI (Vercel)
npx skills add Owl-Listener/designer-skills --skill state-machine -a gemini-cli2Platform CLI
gemini skills install https://github.com/Owl-Listener/designer-skills --path interaction-design/skills/state-machineManually: put the files in place
.devin/skills/state-machine/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add Owl-Listener/designer-skills --skill state-machine -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 state-machine
How to install state-machine in Claude Code?
Run npx skills add Owl-Listener/designer-skills --skill state-machine -a claude-code in your terminal. You can also add it manually at ~/.claude/skills/state-machine/SKILL.md.
What does state-machine do?
It guides the assistant to model interface behavior as formal finite state machines. This ensures every UI state has clear entry, exit, and transition rules.
When should you use micro-interaction-spec instead?
Use state-machine when component logic requires exhaustive states and transitions. For the feel, tactile feedback, and timing of an isolated interaction, use micro-interaction-spec.
Source text
SKILL.md · MIT
--- name: state-machine description: Model component behaviour as explicit states, events, and transitions. Use when a component has many interacting states that must be exhaustive. For the feel and feedback of a single interaction, use `micro-interaction-spec`. --- # State Machine You are an expert in modeling complex UI behavior as finite state machines. ## What You Do You model UI components and flows as state machines to eliminate impossible states and make behavior predictable. ## State Machine Components - **States**: Distinct modes the UI can be in (idle, loading, success, error) - **Events**: Things that cause transitions (click, submit, timeout, response) - **Transitions**: Rules for moving between states (on event X in state A, go to state B) - **Actions**: Side effects during transitions (fetch data, show toast, log event) - **Guards**: Conditions that must be true for a transition (isValid, hasPermission) ## Common UI State Machines ### Form idle -> editing -> validating -> submitting -> success/error -> idle ### Data Fetching idle -> loading -> success/error, error -> retrying -> success/error ### Authentication logged-out -> authenticating -> logged-in -> logging-out -> logged-out ### Multi-Step Wizard step1 -> step2 -> step3 -> review -> submitting -> complete ## Modeling Approach 1. List all possible states 2. List all events/triggers 3. Define valid transitions 4. Identify impossible states to prevent 5. Add guards for conditional transitions 6. Define entry/exit actions per state ## Benefits - Eliminates impossible states (no loading + error simultaneously) - Makes edge cases visible - Shared language between design and engineering - Testable behavior specification ## Best Practices - Start with the happy path, then add error states - Every state should have a way out (no dead ends) - Keep state machines focused (one per concern) - Document with visual diagrams - Map each state to a UI representation
© Owl-Listener · MIT · Owl-Listener/designer-skills
Similar skills
Everything for Design →state-machine by other authors comes first.
