Quickstart

Scaffold, inspect, and advance a reactive skill in five minutes with local-first AXI or MCP runtime selection.

Prerequisites

Node.js 22 or newer required. Commands execute directly without global installation via npx, or install globally with npm i -g @reactive-skills/axi.

bash

node --version

Output

v22.13.0

Node 22.x or newer recommended.

1. Select a compatible local runtime

During INIT, Reactive Skills checks local MCP and AXI capabilities and versions, selects one compatible runtime, and reuses it for the run. AXI remains the runtime interface, and npx is its zero-install launcher when a direct command is not installed.

bash

npx -y @reactive-skills/axi

Output

bin: reactive-skills-axi
description: AXI-compliant CLI for Reactive Skills Architecture
count: 1 skill total
skills:
  tdd-refactor: state RED_SPEC (path: [RED_SPEC])
suggestions:
  emit: npx -y @reactive-skills/axi emit tdd-refactor TEST_RAN

Launches the AXI dashboard to inspect registered skills, active states, and recommended actions.

2. Scaffold and customize a reactive skill

Generate a modular reactive skill directory. The init command scaffolds a verified baseline containing runtime bootloader states (INIT, SETUP_MCP), a starter domain state, strict execution safeguards (BYPASS_DETECTED), and initial prompt templates.

bash

npx -y @reactive-skills/axi init my-feature-flow

Output

created skills/my-feature-flow
  manifest: skills/my-feature-flow/skill.yaml
  statechart: skills/my-feature-flow/STATECHART.md
  initial state: INIT

Initializes a new reactive skill in skills/my-feature-flow/.

Scaffolding gives you the execution harness; customization shapes your domain workflow. You replace the placeholder states in skill.yaml with your chronological phases (e.g. RED_SPEC → GREEN_CODE → REFACTOR), author isolated prompt slices in states/*.md, and attach deterministic guard expressions to gate progress.

Two customization approaches

You can edit skill.yaml and states/*.md directly in your editor, or use an agent equipped with skill-manager to conduct an interactive Socratic discovery interview and auto-generate verified states.

3. Inspect the statechart & guards

Inspect the state machine hierarchy, valid transition paths, and deterministic guard expressions in concise TOON format before executing.

bash

npx -y @reactive-skills/axi inspect skills/my-feature-flow

Output

skill: my-feature-flow
initial: INTAKE
states:
  INTAKE → [RUNTIME_READY] → RED_SPEC
  RED_SPEC → [TEST_RAN (exit_code != 0)] → GREEN_CODE
  GREEN_CODE → [TEST_RAN (exit_code == 0)] → REFACTOR

Outputs states, transitions, signals, and guard conditions.

4. Emit signals to advance state

Advance the state machine by dispatching typed signals. Deterministic guards evaluate context facts before transitions fire; rejected guards output immediate remediation actions.

bash

npx -y @reactive-skills/axi emit my-feature-flow RUNTIME_READY

Output

state: RED_SPEC
transition: INTAKE → RED_SPEC via RUNTIME_READY
guard: passed

Dispatches a signal into the event bus, advancing to the target state upon guard validation.

5. Tail the immutable event ledger

Every signal, guard evaluation, and state transition appends to the authoritative event store (.reactive/skills/<skill>/events.jsonl + SQLite).

bash

npx -y @reactive-skills/axi events my-feature-flow --last 5

Output

#1  SKILL_INITIALIZED   state: INTAKE
#2  SIGNAL_EMITTED      signal: RUNTIME_READY
#3  GUARD_EVALUATED     guard: true (passed)
#4  STATE_TRANSITION    INTAKE → RED_SPEC
#5  STATE_ENTRY_HOOK    state: RED_SPEC

Reads the append-only event ledger for audit and projection verification.

2. Connect MCP for host-integrated workflows

When the host uses MCP tool integration, run the stdio server from the same package. The MCP transport exposes the same reactive runtime through host-managed tools.

bash

npx -y @reactive-skills/axi mcp

Output

reactive-skills-axi mcp · listening on stdio
registered 9 tools · 3 resources
ready

Starts the stdio MCP server, exposing 9 tools and 3 resources to MCP clients.

Runtime selection

INIT selects a compatible local transport and persists it for the run. AXI provides token-lean shell output, while MCP provides host-integrated tools. The npx command launches AXI without a separate installation.

Keep reading

Authoring & customizing skills AXI CLI reference Connect a client with MCP Understand the concepts

Get started

Quickstart

Scaffold, inspect, and advance a reactive skill in five minutes with local-first AXI or MCP runtime selection.

Prerequisites

Node.js 22 or newer required. Commands execute directly without global installation via npx, or install globally with npm i -g @reactive-skills/axi.

bash

node --version

Output

v22.13.0

Node 22.x or newer recommended.

1. Select a compatible local runtime

bash

npx -y @reactive-skills/axi

Output

bin: reactive-skills-axi
description: AXI-compliant CLI for Reactive Skills Architecture
count: 1 skill total
skills:
  tdd-refactor: state RED_SPEC (path: [RED_SPEC])
suggestions:
  emit: npx -y @reactive-skills/axi emit tdd-refactor TEST_RAN

Launches the AXI dashboard to inspect registered skills, active states, and recommended actions.

2. Scaffold and customize a reactive skill

bash

npx -y @reactive-skills/axi init my-feature-flow

Output

created skills/my-feature-flow
  manifest: skills/my-feature-flow/skill.yaml
  statechart: skills/my-feature-flow/STATECHART.md
  initial state: INIT

Initializes a new reactive skill in skills/my-feature-flow/.

Two customization approaches

You can edit skill.yaml and states/*.md directly in your editor, or use an agent equipped with skill-manager to conduct an interactive Socratic discovery interview and auto-generate verified states.

3. Inspect the statechart & guards

Inspect the state machine hierarchy, valid transition paths, and deterministic guard expressions in concise TOON format before executing.

bash

npx -y @reactive-skills/axi inspect skills/my-feature-flow

Output

skill: my-feature-flow
initial: INTAKE
states:
  INTAKE → [RUNTIME_READY] → RED_SPEC
  RED_SPEC → [TEST_RAN (exit_code != 0)] → GREEN_CODE
  GREEN_CODE → [TEST_RAN (exit_code == 0)] → REFACTOR

Outputs states, transitions, signals, and guard conditions.

4. Emit signals to advance state

Advance the state machine by dispatching typed signals. Deterministic guards evaluate context facts before transitions fire; rejected guards output immediate remediation actions.

bash

npx -y @reactive-skills/axi emit my-feature-flow RUNTIME_READY

Output

state: RED_SPEC
transition: INTAKE → RED_SPEC via RUNTIME_READY
guard: passed

Dispatches a signal into the event bus, advancing to the target state upon guard validation.

5. Tail the immutable event ledger

Every signal, guard evaluation, and state transition appends to the authoritative event store (.reactive/skills/<skill>/events.jsonl + SQLite).

bash

npx -y @reactive-skills/axi events my-feature-flow --last 5

Output

#1  SKILL_INITIALIZED   state: INTAKE
#2  SIGNAL_EMITTED      signal: RUNTIME_READY
#3  GUARD_EVALUATED     guard: true (passed)
#4  STATE_TRANSITION    INTAKE → RED_SPEC
#5  STATE_ENTRY_HOOK    state: RED_SPEC

Reads the append-only event ledger for audit and projection verification.

2. Connect MCP for host-integrated workflows

When the host uses MCP tool integration, run the stdio server from the same package. The MCP transport exposes the same reactive runtime through host-managed tools.

bash

npx -y @reactive-skills/axi mcp

Output

reactive-skills-axi mcp · listening on stdio
registered 9 tools · 3 resources
ready

Starts the stdio MCP server, exposing 9 tools and 3 resources to MCP clients.

Runtime selection

Keep reading

Authoring & customizing skills AXI CLI reference Connect a client with MCP Understand the concepts