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) 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-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 (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

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	`ironflow skills doctor` prints the command
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:

ironflow skills sync

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

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:

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

You should see 6 files.

Project-level (vendored)

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

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 symlinks

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.

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

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

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