agentsclimarketplace
Sign in

State machine design

Skill segunadebayo/design-eng-skills/skills/state-machine-design

Use when a feature involves multiple states or transitions. Recognizes the shape, names states and events, designs guards, actions, and hierarchy, and visualizes or simulates the result.From its SKILL.md

Install
npx -y skills add segunadebayo/design-eng-skills --skill state-machine-design

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 6 stars6 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

3.5 KB, 776 tokens by cl100k_base, as published. Nobody here has run it

State Machine Design

A framework-agnostic methodology for designing state machines. Built from Harel's foundational statecharts papers, the W3C SCXML spec, and how XState, Spring Statemachine, Stateless, python-statemachine, and Erlang's gen_statem actually get used. Not any single one of them. Use GLOSSARY.md's terms exactly. See SOURCES.md for what this is built on, and where the sources disagree with each other.

1. Recognize the shape

Is this actually a state machine? Here's the tell: the same event gets handled differently depending on a finite, countable mode. It's often hiding as a pile of booleans where most combinations never actually occur, the boolean-soup smell. See METHODOLOGY.md.

2. Determine scope and elicit the behavior

Model one component, one process, one lifecycle. Not a whole application. Find out what actually happens before you design anything: ask "what happens when...?" for every event, in every candidate state, including the cases nobody thought to mention. See METHODOLOGY.md and #3.

3. Name states and events

Write down the finite state and event set, using GLOSSARY.md's terms only. No loose synonyms. Different behavior on the same event means a different state. Identical behavior means the same state.

4. Design the machine

Flat happy path first. Then the rest of the workflow: errors, retries, timeouts. Then guards, pure, no side effects. Then hierarchy, only once duplication actually shows up, scavenge for reuse, don't nest ahead of time. Then parallel regions, only for concerns that are genuinely independent. Then history, only for a real "resume where I left off" need. Full detail in METHODOLOGY.md, including exactly where the sources disagree: transition-priority direction, guard order across regions.

5. Choose a representation

Pick whatever's idiomatic where this machine will actually live. An XState-style config or a reducer for UI and component behavior. A flat machine with a rich context for a backend process or actor, hierarchy and parallel regions come from the UI-statechart lineage, they are not universal, don't force them onto an actor-model design. See METHODOLOGY.md.

6. Visualize

Never end on prose alone. Three tiers, and you only climb as far as the machine actually demands. A Mermaid diagram by default. A state-machine-cat-rendered static SVG once there's a history state (Mermaid cannot render one at all) or the layout has gotten genuinely hard to read. A self-contained interactive HTML/JS simulator once the point is to explore the machine, or guards are crowding one event. Full decision rule, syntax, and the fill-in template in VISUALIZATION-FORMAT.md and assets/simulator-template.html.

7. Deliver

Try the Artifact tool first. Fall back to writing the file to the OS temp directory and opening it. Tell the user exactly what got produced and where. The visualization is this skill's deliverable, not something to mention in passing.

What ships with it: 6 files

57.0 KB alongside SKILL.md

agents/

assets/

references/

Gives 0 of the 12 instructions most design frontend skills give in 776 tokens

Counted across 1,179 of the 2,086 authors here whose files we hold, read 2026-09-06

  • Commit to a bold aesthetic directionin 31 of 1179, across 24 files
  • Prefer component composition over inheritancein 28 of 1179, across 14 files
  • Animate only transform and opacity propertiesin 27 of 1179, across 22 files
  • Memoize expensive computations with useMemoin 26 of 1179, across 13 files
  • Use semantic HTML elementsin 24 of 1179, across 23 files
  • Virtualize long lists for performancein 21 of 1179, across 10 files
  • Use CSS variables for design tokensin 20 of 1179, across 14 files
  • Implement loading, empty, and error statesin 20 of 1179
  • Lazy load heavy components with Suspensein 19 of 1179, across 8 files
  • Respect prefers-reduced-motion media queriesin 18 of 1179, across 10 files
  • Prioritize CSS-only animations for HTMLin 18 of 1179, across 16 files
  • Use compound components for related UI elementsin 18 of 1179, across 7 files

Said here and by no other author read

  • Identify if the feature involves finite modes
  • Model one component or process at a time
  • Use glossary terms for states and events
  • Design flat happy paths first
  • Implement guards as pure functions
  • Add hierarchy only to reduce duplication

Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once. Length counted with cl100k_base; the agent that loads this file may tokenize it differently.

Keep looking

Skills are one crate of 325,949. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.