Skip to content
Ironflow

AI Skills

Ironflow ships a suite of AI skills — structured knowledge packs that teach AI coding agents (Claude Code, Codex CLI, Gemini CLI) how to write correct Ironflow code, debug failures, make architecture decisions, and operate infrastructure. Skills go beyond static context — they give your AI agent judgment about when to use which pattern.

Universal entry point. Don’t know which skill to use? Just type /ironflow and describe what you need. The router classifies your intent and dispatches to the right specialized skill.

Why Skills?

Without skills, AI agents make predictable Ironflow mistakes: side effects outside steps, duplicate step IDs, impure projections, wrong event matching. The Agent Template helps, but it’s static context you copy-paste. Skills are interactive — they activate automatically when relevant and guide the agent through a structured workflow.

Without skills With skills
AI guesses at patterns AI follows verified SDK patterns
Common mistakes on every project 20+ pitfall guardrails (mechanical + CQRS-semantic)
CRUD code in disguise Guides you to aggregates, commands, and invariant-enforcing deciders
Manual copy-paste of agent template Skills load automatically on trigger
No debugging guidance Systematic diagnostic flowchart
Single-format support Works across Claude Code, Codex CLI, Gemini CLI

Available Skills

The skill set is organized into 5 skills covering the full Ironflow lifecycle. Workflow skills handle process; the docs skill carries reference content; the router dispatches when intent is unclear.

Skill Trigger What it does
/ironflow Any Ironflow request without a sharper trigger Universal entry point. Classifies intent and dispatches to the right skill. Includes a daily check for newer Ironflow releases.
/ironflow-start “set up ironflow”, “where do I start”, “ironflow fit”, “push vs pull”, “CRUD or CQRS” Adopt Ironflow. Project setup with framework detection (Next.js, Hono, Express, Remix, Go), codebase fit analysis (scans for CQRS signals — status columns, multi-view reads, controllers with logic), and architecture decisions (CRUD vs CQRS, push vs pull, entity streams vs events, aggregate sizing, single vs multiple projections, sagas vs compensation).
/ironflow-code “write a function”, “create a projection”, “add tests for”, “write tests for”, “audit my code”, “review my ironflow” Build code. Write command handlers, aggregate deciders, projections, entity streams, workers, process managers, sagas, reactors, webhooks. Generate unit tests (Given/When/Then for aggregates, pure-reducer tests for projections) and integration tests for vitest, Jest, and Go. Audit existing code against 20+ anti-patterns (mechanical + CQRS-semantic).
/ironflow-ops “run failed”, “stuck workflow”, “scale cluster”, “upgrade SDK” Operate Ironflow. Debug failed/stuck runs, wrong outputs, missing events, projection drift. Migrate SDK versions with upcasters. Deploy, scale, monitor, troubleshoot, and recover clusters (k3d, Hetzner, Helm).
/ironflow-docs “how do I emit”, “CLI for X”, “MCP tool reference”, “SDK syntax” Reference lookup. SDK reference (TypeScript + Go), CLI command reference, MCP tool reference, canonical patterns, anti-patterns. Each topic carries a minimal inline example plus a URL to the hosted docs for depth. Other skills delegate here when they need syntax.

Architecture

/ironflow         router (slim, classify → dispatch)
/ironflow-start   setup + fit analysis + architecture decisions
/ironflow-code    write code + tests + audit
/ironflow-ops     debug + migrate + deploy/scale
/ironflow-docs    SDK / CLI / MCP reference (index + topic files)

Workflow skills (start, code, ops) delegate to docs when they need SDK syntax — reference content lives in one place.

CQRS & Event Sourcing Guidance

Ironflow is built on CQRS and event sourcing. Skills teach both the mechanics (pure projections, optimistic concurrency, upcasters) and the modeling layer (commands vs events, aggregate design, write/read separation) so your AI agent produces code that reflects the paradigm instead of CRUD-in-disguise.

What the skills enforce:

  • Commands vs events — imperative names for intent (PlaceOrder), past tense for facts (OrderPlaced); never CRUD (UserUpdated)
  • Aggregates — invariants live in a pure decider ((state, command) => events[] | error), not in reactors or projections
  • Write/read separation — entity streams serve appends with optimistic concurrency; projections serve reads with denormalized shapes
  • Function roles — command handler, process manager, saga, reactor, scheduler — each role carries an id prefix (cmd., pm., saga., react., cron.)
  • Ubiquitous language — one language per bounded context; a curated published language for cross-context integration
  • Eventual consistency — read-your-own-writes handled via subscribeToProjection, optimistic UI, or wait-for-projection where confirmations matter

Skills also help you decide when not to use CQRS. Simple form-and-table CRUD doesn’t need aggregates — /ironflow-start in architecture mode walks the CRUD-vs-CQRS tradeoff and picks per-entity, not per-app.

Anti-patterns the audit flags include: querying entity streams for display data, fat events carrying full entity state, anemic aggregates with rules leaking into reactors, CRUD-named events, and impure managed projections. See anti-patterns.md in the ironflow-docs skill for the full list.

Installation

Skills ship inside the ironflow binary, so they always match your installed version. There is no separate download and nothing to keep in sync by hand.

After installing Ironflow, write the skills to disk:

Terminal window
ironflow skills sync

This writes all 5 skills to ~/.agents/skills/ (the shared location every AI agent reads). Then wire your coding agent:

Terminal window
ironflow skills doctor

doctor detects your coding agents and prints the exact command to point each one at the skills. It makes no changes itself, so copy the command it shows. For Claude Code that links ~/.agents/skills/ironflow* into ~/.claude/skills/.

Verify installation:

Terminal window
ls ~/.agents/skills/ironflow*/SKILL.md

You should see 5 files.

Project-level (vendored)

To pin skills inside a project, write them locally and commit them:

Terminal window
ironflow skills sync --local      # writes ./.agents/skills/
ironflow skills doctor --local    # prints the project-local wiring command

Commit .agents/skills/ to pin the skill versions to your project.

Claude Code reads skills from .claude/skills/, not .agents/skills/. You do not need to wire this by hand: ironflow skills doctor detects Claude Code and prints the exact symlink command for your install (global or --local). Run it, copy the command it shows, then restart your Claude Code session to load the skills.

Usage

Universal Entry Point (Recommended for new users)

Use /ironflow for everything — it routes to the right skill:

/ironflow my order processing run failed at the payment step
/ironflow create a function that processes orders with payment and email
/ironflow set up ironflow in my Next.js app and write a hello function
/ironflow scale my Hetzner cluster to 5 replicas
/ironflow add a new tenant to my multi-tenant deployment

The router classifies your intent and dispatches automatically. If your request is ambiguous, you’ll see a numbered menu — pick a number, and the router will show you the trigger phrase to use next time so you can skip the menu.

If you know which skill you need, invoke it directly:

/ironflow-code create a function that processes orders
/ironflow-ops my run failed at the payment step
/ironflow-start set up ironflow in my Next.js app
/ironflow-docs what's the syntax for waitForEvent

Automatic Activation

Skills also activate automatically based on your prompt. For example:

  • “set up ironflow”, “where do I start” → ironflow-start
  • “add a projection for order stats”, “write tests for the order function” → ironflow-code
  • “why is my workflow stuck”, “scale my cluster” → ironflow-ops
  • “how do I emit an event from the CLI” → ironflow-docs

If the wrong skill activates, use /ironflow or the explicit /ironflow-{name} form.

Self-Updating

Skills ship inside the binary, so upgrading Ironflow upgrades your skills. After upgrading (brew upgrade ironflow, a new Docker image, or a new binary), re-run:

Terminal window
ironflow skills sync

Ironflow reminds you when this is needed. Any ironflow command prints a one-line notice when the skills on disk were written by an older binary than the one now running:

ironflow: AI skills in ~/.agents/skills are stale (synced v0.21.0, binary v0.22.9). Run ironflow skills sync to update.

Run ironflow skills doctor any time to check whether your on-disk skills match the binary.

Skills version-track the Ironflow project. Server, SDKs, and skills share a single version number.

How Skills Work with MCP

Skills and the MCP server are complementary:

MCP Server Skills
What Runtime tools to interact with Ironflow Knowledge about how to write/debug Ironflow code
Analogy The agent’s hands The agent’s brain
Example ironflow_list_runs returns data The ops skill knows what to do with that data
Setup .mcp.json in your project ~/.agents/skills/ironflow*/

Best experience: use both. Configure the MCP server for runtime access, and install skills for coding guidance. The ops skill automatically uses MCP tools when available and falls back to CLI commands when not.

Skills vs Agent Template

The Agent Template is a static markdown file you copy into your project as CLAUDE.md or .cursorrules. Skills are an upgrade:

Agent Template Skills
Static copy-paste Auto-discovers and loads on demand
One big file for everything Focused: one skill per task
No workflow guidance Step-by-step agent workflow
No debugging support Full diagnostic flowchart
Single format Works across Claude Code, Codex, Gemini

If you’re already using the agent template, skills are a strict upgrade — they include the same SDK reference plus interactive workflows. You can keep both; they don’t conflict.

Cross-Agent Support

Skills live in a single location — .agents/skills/ — used by all AI agents (Claude Code, Codex CLI, Gemini CLI). No generation step or separate copies needed. The router and workflow skills use only universal primitives (text output, file reads, shell commands) so they work identically across agents.

Updating Skills

After upgrading the ironflow binary, re-run:

Terminal window
ironflow skills sync          # global (~/.agents/skills)
ironflow skills sync --local  # project-vendored (./.agents/skills)

sync overwrites the on-disk skills with the versions bundled in the current binary, then stamps the version so the staleness notice clears.

Troubleshooting

Skill doesn’t appear in autocomplete

  • Verify the file exists: ls ~/.agents/skills/ironflow-code/SKILL.md
  • Restart your Claude Code session (skills load at session start)
  • Check the SKILL.md has valid YAML frontmatter
  • For Claude Code, verify the symlink in .claude/skills/ points to the right place

Wrong skill activates

Use explicit invocation: /ironflow-code or /ironflow-ops. The trigger descriptions are tuned to minimize overlap, but ambiguous prompts like “help with this code” may not route perfectly. Use /ironflow (the router) for ambiguous requests — it’ll show a menu.

Skill content seems outdated

Re-run ironflow skills sync (or --local for a vendored install). It overwrites the on-disk skills with the versions bundled in the current binary. If the content still looks old, confirm your binary is current with ironflow version.