How to use the State Machine Workbench agent skill

What the skill makes the agent do

The skill builds a scratch route inside your app. The route holds the real component, imported from your project and left untouched, and renders it in each state the code can reach. Mock data feeds each state, and a grouped switcher lets you flip between states by clicking a link or changing a URL parameter.

The page is a workbench, not a review. It is meant for working on the visuals of one component while every other state stays one keypress away. It is not for reviewing finished work or auditing a whole page; the skill says other skills handle those jobs.

• States are the branches the component already has, found by reading the component and its data hooks.
• States are grouped by kind, such as Data, Account or Feature, and named the way the product names them.
• When you are finished, the page folder can be deleted in one step.

Install the State Machine skill

Download the ZIP for the skill from our page. The ZIP contains agents/openai.yaml, SKILL.md and switcher.md.

You can install it in one of two ways. For a personal install, unzip it into ~/.claude/skills/. For a single project, unzip it into the project's .claude/skills/ folder. Alternatively, upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

• Personal install: ~/.claude/skills/
• Project install: the project's .claude/skills/ folder
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Check what the skill needs

The skill needs a project with a component framework the agent can read. The skill gives Next.js and client/server component splits as examples. A browser the agent can use is optional. If the agent has no browser, the skill tells it to hand the URL to you so you can check each state yourself.

The skill runs no scripts and uses no network access, according to its source.

• Required: a project with a component framework the agent can read
• Optional: a browser the agent can use to load the page and check each state
• Runs scripts: no
• Uses network: no

Trigger the skill with a natural request

The SKILL.md is marked disable-model-invocation, so the agent is not set up to pick it up on its own. Name the skill and the component in your request. The agent asks you to scope one component per run, so a request about a whole page will get a question back about which component to use.

Mention the states you care about if you have them in mind. The agent will still read the code to find the states that actually exist.

• Use the state-machine skill to show every state of the billing card.
• Use the state-machine skill on the audit log table so I can see loading, empty and error.
• Use the state-machine skill to show the network panel for a member with no access and for an owner.

Review the states, the switcher and the mock data

The agent lists the states it found, grouped under headings such as Data, Account or Feature. It also says which kinds it dropped and why. Mock data is shaped like your product, with realistic names, timestamps, amounts and item counts. Loading and pending states stay pending until you move the switcher, rather than resolving after a timeout.

The switcher is a grouped list beside the component, or a select above it when there is no room. It is deliberately styled outside your design system so it does not look like part of the product. When the agent is done, it hands over the URL, the state list and the switcher keys, then waits for your next request.

• The switcher sets a __state search param, so each state has its own URL.
• The double underscore keeps the switcher clear of any parameter your layout reads.
• Ask for visual changes as a new request; the skill does not change how a state looks on its own.

Remove the page when you are done

Removal happens on your word, not automatically. The skill deletes the page folder, such as /states/audit-log, and any data seam you approved. It then searches the codebase for the route and fixture names and checks that the diff touches nothing else of the setup.

• Ask the agent to remove the states page for the component.
• Ask the agent to search for the route and fixture names after removal.