Authoring & Customizing Skills

Beyond the basic scaffold

Running axi init generates a runnable skeleton containing runtime verification (INIT, SETUP_MCP), a generic START state, and execution boundaries (BYPASS_DETECTED). However, production skills represent domain workflows with custom macro-phases, deterministic gating, and scoped prompt slices.

Anatomy of a reactive skill

A customized reactive skill is organized into isolated, single-responsibility files under skills/<skill-name>/:

Two customization workflows

You can customize reactive skills either through an interactive agent session or by editing the manifest and state slices directly.

1. 1

   Agent-Guided Discovery (Recommended)

   Invoke an agent with the skill-manager or reactive-skill-creator skill. The agent conducts a Socratic interview to extract domain phases, guard conditions, and projections, then synthesizes and tests the complete statechart.

2. 2

   Direct CLI & File Customization

   Run npx -y @reactive-skills/axi init <name>, then edit skill.yaml to define domain states, author corresponding prompt files under states/, wire guard expressions, and inspect with axi inspect.

1. The Agent-Guided workflow (Recommended)

When designing a skill with an agent, the agent runs a five-dimension discovery interview to prevent underspecified states or brittle transitions:

• Workflow Identity & Context: Defines the single objective and required initial variables (e.g. repo_path, branch, pr_id).
• State Taxonomy: Identifies chronological macro-phases (e.g. INTAKE → PLAN → EXECUTE → VERIFY → COMPLETE).
• Transition Signals & Guards: Names the signals that trigger progress and the exact facts required to advance.
• Failure Modes & Rollbacks: Maps where execution returns if tests fail, builds break, or invariants reject.
• Deliverable Sinks: Specifies the Handlebars templates folded from event history into .docs/ reports.

2. Customizing skill.yaml (Topology & Guards)

Replace the default START state in skill.yaml with your domain workflow phases. Each state declares its prompt template, tool restrictions, and valid transition paths.

# skills/tdd-flow/skill.yaml
schema_version: "2.1.0"
name: "tdd-flow"
description: "Red-Green-Refactor test-driven development workflow"
initial_state: "INIT"
strict_execution: true
context_keys: ["target_module", "test_file"]

states:
  INIT:
    prompt_template: "states/init.md"
    transitions:
      RUNTIME_READY: { target: "RED_SPEC" }

  RED_SPEC:
    description: "Write failing test specification"
    prompt_template: "states/red_spec.md"
    model:
      tier: "fast"
      suggested: "gemini-2.5-flash / haiku"
    tools: ["view_file", "write_to_file", "run_command"]
    transitions:
      TEST_RAN:
        target: "GREEN_CODE"
        guard: "payload.exit_code != 0"

  GREEN_CODE:
    description: "Implement minimal code to pass test"
    prompt_template: "states/green_code.md"
    model:
      tier: "balanced"
      suggested: "claude-3-7-sonnet"
    tools: ["view_file", "replace_file_content", "run_command"]
    transitions:
      TEST_RAN:
        target: "REFACTOR"
        guard: "payload.exit_code == 0"

  REFACTOR:
    description: "Clean implementation while tests stay green"
    prompt_template: "states/refactor.md"
    model:
      tier: "reasoning"
      suggested: "claude-3-7-sonnet / o3-mini"
    tools: ["view_file", "replace_file_content", "run_command"]
    transitions:
      TEST_RAN:
        target: "COMPLETE"
        guard: "payload.exit_code == 0"
        judgment:
          type: "predicate"
          criterion: "Did the refactoring maintain public APIs without introducing regressions?"
          min_confidence: 0.85
          fallback_target: "GREEN_CODE"
      REGRESSION:
        target: "GREEN_CODE"
        guard: "payload.exit_code != 0"

  COMPLETE:
    description: "TDD cycle verified and closed"
    prompt_template: "states/complete.md"

3. Authoring scoped state prompt slices (states/*.md)

Each state prompt file contains instructions strictly relevant to that state. Do not include instructions for previous or future phases. The agent receives only the active slice when entering the state.

<!-- skills/tdd-flow/states/red_spec.md -->
# TDD Flow — RED_SPEC

Write a failing test specification for `{{context.target_module}}`.

## Current Objective
1. Inspect `{{context.target_module}}` using `view_file`.
2. Author unit test cases in `{{context.test_file}}`.
3. Run test runner using `run_command`.

## Stop Criteria & Signal Contract
When the test suite runs and fails as expected (failing assertion, not compilation crash):
- Emit signal: `TEST_RAN`
- Payload facts: `{"exit_code": 1, "failing_tests": 1}`

Do NOT attempt to write application logic or make the test pass in this state.

4. Deterministic guards, semantic judgments & deliverables

Guards prevent subjective completion claims. Transitions require verified facts, code assertions, or semantic verification:

• Inline expressions: Written in standard JavaScript (e.g. payload.exit_code == 0 && payload.coverage >= 80).
• Semantic judgments: Declared via judgment: { type, criterion, min_confidence, fallback_target }. Evaluated via the decoupled Judgment Engine (built-in sandbox or optional @typesafe-ai/sdk-backed Jev System One decisions).
• Circuit breaker fallback routing: If a model judgment fails, times out, or trips, the FSM transitions directly to a declared fallback_target state and logs GUARD_FALLBACK_TRIGGERED.
• Model capability tiers: Declared via model: { tier: fast | balanced | reasoning | decision } to guide multi-model routing across states.
• Custom guard scripts: Placed in guards/<guard_name>.js for complex validation like AST checks or git status verifications.
• Deliverable projections: Configured via deliverable_projections in skill.yaml. Handlebars templates (templates/*.hbs) automatically fold the event log into deliverables (.docs/*.md) without requiring manual agent summarization.

5. Inspect and verify your customized skill

After updating your manifest and state prompt files, verify the skill topology and transition paths before executing:

npx -y @reactive-skills/axi inspect skills/tdd-flow

skill: tdd-flow
initial: INIT
states:
  INIT → [RUNTIME_READY] → RED_SPEC
  RED_SPEC → [TEST_RAN (guard: payload.exit_code != 0)] → GREEN_CODE
  GREEN_CODE → [TEST_RAN (guard: payload.exit_code == 0)] → REFACTOR
  REFACTOR → [TEST_RAN (guard: payload.exit_code == 0)] → COMPLETE
  REFACTOR → [REGRESSION (guard: payload.exit_code != 0)] → GREEN_CODE

6. Distribute to agent satellites with axi sync

Once your skill validates cleanly, synchronize it across all local agent harnesses (Claude, Gemini, Codex, Devin, Cline, Copilot) using zero-drift directory junctions:

npx -y @reactive-skills/axi sync tdd-flow