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 6 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-fit	“should we use ironflow”, “where can we use ironflow”, “ironflow fit”, “analyze my codebase”, “ironflow readiness”	Does it fit? Scans a codebase or a directory of projects — Java/Spring, C#/.NET, Python, Rust, Node/TypeScript, Go — scores event-driven readiness from evidence, ranks the places Ironflow helps with file:line citations, states the adoption path for the detected stack, and writes a self-contained HTML report. It can, and does, return “not a fit”.
/ironflow-start	“set up ironflow”, “install ironflow”, “add ironflow to”, “walk me through”, “push vs pull”, “entity streams vs events”	Adopt Ironflow. Project setup with framework detection (Next.js, Hono, Express, Remix, Go, Flask, FastAPI, Django) 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”, “package my app”	Operate Ironflow. Debug failed/stuck runs, wrong outputs, missing events, projection drift. Migrate SDK versions with upcasters. Run, monitor, troubleshoot, and back up a self-hosted Docker Compose stack. Package your app and the engine into one container, then deploy it to Fly or Railway.
/ironflow-docs	“how do I emit”, “CLI for X”, “MCP tool reference”, “SDK syntax”	Reference lookup. SDK reference (TypeScript, Go and Python), CLI command reference, MCP tool reference, canonical patterns, anti-patterns. It is a router: each topic maps to one hosted docs page, which the agent fetches as Markdown. Other skills delegate here when they need syntax.

Architecture

/ironflow         router (slim, classify → dispatch)
/ironflow-fit     does it fit? codebase analysis -> HTML report
/ironflow-start   setup + scaffold + architecture decisions
/ironflow-code    write code + tests + audit
/ironflow-ops     debug + migrate + deploy/scale
/ironflow-docs    SDK / CLI / MCP reference (router to docs.ironflow.run pages)

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 the pitfalls page for the full list.

Installation

The fastest route is one sentence. Paste it into your coding agent:

Read https://ironflow.run/start.md and set up Ironflow in this project.

That page tells the agent to install the engine if it is missing, install the skills from the binary, and show you each command first.

To install the skills yourself, there are two routes to the same six skills. Pick by whether you already run Ironflow:

	npx skills add	ironflow skills sync
Needs	Node — no Ironflow install	The ironflow binary
Version	Latest release	Exactly your binary’s
Wires your agent	Automatically, 75+ agents	--agent wires Claude Code, Codex or Gemini CLI; ironflow skills doctor prints the commands
Best for	Evaluating Ironflow before installing it	Building on Ironflow day to day

Without installing Ironflow

npx skills reads the skills from Ironflow’s public mirror and wires whichever coding agents it finds — Claude Code, Codex, Cursor, OpenCode, and 75+ others:

npx skills add sahina/ironflow-releases

It lists the six skills and asks which to install where. To skip the prompts:

# Every skill, every detected agent
npx skills add sahina/ironflow-releases --all

# Just the fit analysis, into Claude Code, for every project on this machine
npx skills add sahina/ironflow-releases -s ironflow-fit -a claude-code -g -y

-g installs to your home directory; the default is project-local, so you can commit the result and your team gets the same skills. Skills installed this way track the latest Ironflow release — re-run the command to update.

This is the shortest path to a real answer about Ironflow: install ironflow-fit, ask your agent “does Ironflow fit this codebase?”, and read the report before you install anything.

With the Ironflow binary

Skills ship inside the ironflow binary, so this route always matches your installed version — no separate download, nothing to keep in sync by hand.

After installing Ironflow, write the skills to disk from your project (sync finds the root: the nearest folder with .agents/skills or .git):

ironflow skills sync

In a terminal, sync asks where to write the skills: the project (./.agents/skills/, the default) or global (~/.agents/skills/, read in every project). Skip the question with --local or --global. Then it offers to symlink the skills into .claude/skills/ for Claude Code (with a flag, it skips that offer too). For other agents, run:

ironflow skills doctor            # add --global for a global install

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.

Verify installation:

ls .agents/skills/ironflow*/SKILL.md

You should see 6 files. Commit .agents/skills/ to pin the skill versions to your project.

Claude Code symlinks

Claude Code reads skills from .claude/skills/, not .agents/skills/. You do not need to wire this by hand: ironflow skills sync offers to create the symlinks. If you said no, passed a scope flag, or ran sync without a terminal, ironflow skills doctor prints the exact symlink command (add --global for a global install). 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 move my Docker Compose stack from Starter to Cluster
/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.

Direct Invocation (Recommended for power users)

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-fit
/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:

• “should we use ironflow”, “where can we use it” → ironflow-fit
• “set up ironflow”, “install ironflow” → 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:

ironflow skills sync    # add --global for a global install

If you installed with npx skills add, re-run that command instead — there is no binary to upgrade, and the mirror already carries the latest release.

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 --global 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.

If you have edited a bundled skill

Sync replaces each bundled skill directory it writes, so it refuses rather than discard your edits, and names what it would replace:

Error: these skills in /Users/you/.agents/skills have local edits, and syncing would replace them:
  - ironflow-code

Copy anything you want to keep, then re-run with --force.

Files you added beside a bundled skill count as edits, because sync removes them too. Your own skills — anything not in the bundled set — are never touched either way.

An upgrade on its own never triggers this. “Edited” means changed since the last sync wrote it, not different from what the new binary ships.

To keep an edited version and stay current, copy it to a new name before syncing. Then both exist, and the workspace copy takes precedence.

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:

ironflow skills sync           # project (./.agents/skills)
ironflow skills sync --global  # global (~/.agents/skills)

To name your agent and answer no prompts, pass --agent. claude also links the skills into .claude/skills:

ironflow skills sync --agent claude  # or codex, gemini

For a new project, ironflow init my-app --agent claude scaffolds it with the skills already in place.

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

Skills installed with npx are not bound to a binary — re-run the install command to pull the latest release:

npx skills add sahina/ironflow-releases

Troubleshooting

Skill doesn’t appear in autocomplete

• Verify the file exists: ls .agents/skills/ironflow-code/SKILL.md (or ~/.agents/skills/... for a global install)
• 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 --global for a global 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.