Workflow Skills

Workflow skills are AI-assisted commands that guide you through creating durable workflows. Start from a specific problem with a scenario command, or use the two-stage loop to capture your project context once and build correct workflows interactively.

Scenario Commands: Start from What You're Building

If you know what kind of workflow you need, start here:

Scenario commands reuse .workflow.md when present and fall back to a focused context capture when not. They apply domain-specific guardrails and terminate with the same verification_plan_ready contract as /workflow-build.

Example Prompts

/workflow-saga reserve inventory, charge payment, compensate on shipping failure

/workflow-timeout wait 24h for approval, then expire

/workflow-idempotency make duplicate webhook delivery safe

/workflow-observe stream operator progress and final status

Review Existing Workflows

When you already have workflow code and need to assess correctness before changing it, run:

/workflow-audit

For example:

Audit our purchase approval workflow for timeout holes, replay safety, and missing suspension tests.

The audit skill reads .workflow.md when present, inspects the workflow code and tests, scores 12 durable-workflow checks, tags issues P0-P3, and recommends the single best next skill.

The Manual Path: Teach, Then Build

For workflows that don't fit a scenario command, use the two-stage loop:

Two-Stage Loop: Teach, Then Build

The workflow skill is an always-on API reference available at any point.

cp -r node_modules/workflow/dist/workflow-skills/claude-code/.claude/skills/* .claude/skills/

cp -r node_modules/workflow/dist/workflow-skills/cursor/.cursor/skills/* .cursor/skills/

/workflow-teach

/workflow-build

Persisted Artifacts

The skill loop produces two categories of artifacts:

Skill-managed: .workflow.md

Written directly by workflow-teach. A plain-English markdown file containing project context, business rules, failure expectations, and approved patterns. This is the primary bridge between teach and build — workflow-build reads this file to inform step boundaries, failure modes, and test coverage.

Host-managed: .workflow-skills/*.json

The .workflow-skills/ directory contains machine-readable companion artifacts managed by the host runtime or persistence layer — not by the skill prompts themselves. The skill text never references these JSON paths directly; instead, the host extracts structured data from the skill conversation and persists it for agent consumption. This separation keeps the skill prompts focused on human-readable guidance while enabling programmatic queries against the JSON artifacts.

• context.json — structured project context derived from workflow-teach
• blueprints/<name>.json — workflow blueprint with step boundaries, suspension points, and trap analysis
• verification/<name>.json — verification plan with files, test matrix, runtime commands, and implementation notes

The files array must list only files that are actually produced. Add the route entry only when a route file is generated.

Example verification plan:

{
  "contractVersion": "1",
  "blueprintName": "approval-expiry-escalation",
  "files": [
    { "kind": "workflow", "path": "workflows/approval-expiry-escalation.ts" },
    { "kind": "test", "path": "workflows/approval-expiry-escalation.integration.test.ts" }
  ],
  "testMatrix": [
    {
      "name": "happy-path",
      "helpers": [],
      "expects": "Workflow completes successfully"
    },
    {
      "name": "hook-suspension",
      "helpers": ["waitForHook", "resumeHook"],
      "expects": "Workflow resumes from hook"
    },
    {
      "name": "sleep-suspension",
      "helpers": ["waitForSleep", "wakeUp"],
      "expects": "Workflow resumes after sleep"
    }
  ],
  "runtimeCommands": [
    {
      "name": "typecheck",
      "command": "pnpm typecheck",
      "expects": "No TypeScript errors"
    },
    {
      "name": "test",
      "command": "pnpm test",
      "expects": "All repository tests pass"
    },
    {
      "name": "focused-workflow-test",
      "command": "pnpm vitest run workflows/approval-expiry-escalation.integration.test.ts",
      "expects": "approval-expiry-escalation integration tests pass"
    }
  ],
  "implementationNotes": [
    "Invariant: A purchase order must receive exactly one final decision: approved, rejected, or auto-rejected",
    "Invariant: Escalation must only trigger after the primary approval window expires",
    "Operator signal: Log approval.requested with PO number and assigned manager",
    "Operator signal: Log approval.escalated with PO number and director"
  ]
}

The .workflow.md Bridge

Written by workflow-teach, read by workflow-build, .workflow.md contains:

Hero Scenario: Approval Expiry Escalation

The approval-expiry-escalation scenario is the recommended first workflow to build with the skill loop. It exercises the hardest patterns in a single flow:

Run /workflow-teach first, then /workflow-build with the approval scenario prompt to walk through the full loop.

Stress Checklist

The build skill runs this 12-point checklist twice — once against your proposed design and once against the generated code:

1. Determinism boundary
2. Step granularity
3. Pass-by-value / serialization
4. Hook token strategy
5. Webhook response mode
6. start() placement
7. Stream I/O placement
8. Idempotency keys
9. Retry semantics
10. Rollback / compensation
11. Observability streams
12. Integration test coverage

Inspect Build Output

The workflow-skills builder emits structured JSON logs on stderr and a JSON manifest on stdout. Redirect them to inspect build state programmatically:

pnpm build:workflow-skills > /tmp/workflow-skills-manifest.json 2> /tmp/workflow-skills-build.log

echo 'manifest summary'
cat /tmp/workflow-skills-manifest.json | jq '{providers, totalOutputs}'

echo 'first 3 structured log events'
head -n 3 /tmp/workflow-skills-build.log | jq

Expected output shape:

{ "providers": ["claude-code", "cursor"], "totalOutputs": 52 }

{"event":"start","ts":"2026-03-27T16:41:23.035Z","mode":"build"}
{"event":"skills_discovered","ts":"2026-03-27T16:41:23.120Z","count":11,"scenarioCount":6}
{"event":"plan_computed","ts":"2026-03-27T16:41:23.240Z","totalOutputs":52,"providerCount":2,"skillCount":11,"scenarioCount":6,"goldensPerProvider":15,"outputsPerProvider":26}

Verification commands

node scripts/build-workflow-skills.mjs --check | jq '{skillSurface, totalOutputs}'
pnpm vitest run workbench/vitest/test/workflow-skill-bundle-parity.test.ts
pnpm vitest run workbench/vitest/test/workflow-skills-docs-contract.test.ts

Expected summary

{
  "skillSurface": {
    "counts": {
      "skills": 11,
      "scenarios": 6,
      "goldensPerProvider": 15,
      "providers": 2,
      "outputsPerProvider": 26,
      "totalOutputs": 52
    }
  },
  "totalOutputs": 52
}

Inspect Validation Output

The validator emits structured JSON logs on stderr and a machine-readable result on stdout, even when validation fails.

node scripts/validate-workflow-skill-files.mjs > /tmp/workflow-skills-validate.json 2> /tmp/workflow-skills-validate.log || true

echo 'validation summary'
cat /tmp/workflow-skills-validate.json | jq '{ok, checked, summary}'

echo 'last 3 validator events'
tail -n 3 /tmp/workflow-skills-validate.log | jq

Next Steps

• Read the Workflows and Steps guide to understand the runtime model
• See the Testing guide for writing workflow tests by hand
• Check the @workflow/vitest API reference for the full list of test helpers