xstate-v5 Codex Skill

This repository contains a Codex skill for implementing, refactoring, and reviewing XState v5 machines (TypeScript + React) with a strict ruleset and a design-the-statechart-first workflow.

What The Installer Expects (Structural Requirements)

The skill installer copies a directory out of a GitHub repo and only requires:

• A folder that contains SKILL.md
• SKILL.md must start with YAML frontmatter (--- ... ---) and include:
  • name: (hyphen-case, e.g. xstate-v5)
  • description:

Recommended (but not required by the installer):

• agents/openai.yaml for UI display metadata (chips/listing)
• references/ for large docs that should not live in SKILL.md

Notes:

• If your GitHub repo root is the skill folder, you can install with --path . but you must also pass --name (because the installer would otherwise derive the invalid name .).
• If your GitHub repo contains the skill in a subfolder (recommended), you can install with --path <folder-name> and omit --name.

Repo Layout

.
├── SKILL.md                      # Required (with YAML frontmatter)
├── agents/
│   └── openai.yaml               # Recommended UI metadata
├── references/
│   └── xstate-v5-rules.md        # Source-of-truth rules doc (loaded on demand)
└── AGENTS.md                     # Workspace guidance for agents (design-first workflow)

Note: agents/openai.yaml is UI metadata; AGENTS.md is agent workflow guidance for this workspace. They serve different purposes.

Install (GitHub)

Codex installs skills via the system skill-installer script:

export CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
python3 "$CODEX_HOME/skills/.system/skill-installer/scripts/install-skill-from-github.py" \
  --repo <owner>/<repo> \
  --path . \
  --name xstate-v5

If you vend this skill under a subfolder (recommended), install it like:

python3 "$CODEX_HOME/skills/.system/skill-installer/scripts/install-skill-from-github.py" \
  --repo <owner>/<repo> \
  --path xstate-v5

After installing, restart Codex so the new skill is picked up.

Usage

This skill is intended to trigger when working with:

• XState v5 machines/actors (xstate, @xstate/react)
• TypeScript-first patterns (setup().createMachine(), typed params, createActorContext)
• Planning/designing statecharts prior to implementation

The rules source of truth is references/xstate-v5-rules.md.