Skip to content
Ironflow Docs

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 skillsWith skills
AI guesses at patternsAI follows verified SDK patterns
Common mistakes on every project20+ pitfall guardrails (mechanical + CQRS-semantic)
CRUD code in disguiseGuides you to aggregates, commands, and invariant-enforcing deciders
Manual copy-paste of agent templateSkills load automatically on trigger
No debugging guidanceSystematic diagnostic flowchart
Single-format supportWorks 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.

SkillTriggerWhat it does
/ironflowAny Ironflow request without a sharper triggerUniversal 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

Install all 5 skills globally from the Ironflow repo:

Terminal window
curl -fsSL https://raw.githubusercontent.com/sahina/ironflow/main/install-skills.sh | bash

This installs skills to ~/.agents/skills/ironflow*/. All AI agents (Claude Code, Codex CLI, Gemini CLI) read from the same location.

If you previously installed the older 11-skill structure, the installer will detect the old directories and prompt before replacing them with the new 5-skill structure. Reply y to upgrade.

Verify installation:

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

You should see 5 files.

Project-Level (Vendored)

Install skills into your current project for version-pinned availability:

Terminal window
curl -fsSL https://raw.githubusercontent.com/sahina/ironflow/main/install-skills.sh | bash -s -- --local

Skills install to .agents/skills/ironflow*/ in the current directory. Commit these to pin skill versions to your project.

The installer auto-appends .agents/skills/**/.last_checked (the version-check cache stamp) to your project’s .gitignore if it exists.

Claude Code reads skills from .claude/skills/, not .agents/skills/. After a project-level install, create symlinks so Claude Code finds them:

Terminal window
mkdir -p .claude/skills
# Remove stale ironflow* symlinks left over from previous installs
find .claude/skills -maxdepth 1 -name 'ironflow*' -type l -delete
for skill in .agents/skills/ironflow*; do
  ln -sf "../../$skill" ".claude/skills/$(basename "$skill")"
done

Verify with ls -la .claude/skills/ — each entry should point to its .agents/skills/ counterpart. If you see stale symlinks from an older install, re-run the symlink loop above — it cleans them before recreating. Restart your Claude Code session to load the new 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

The router checks for new Ironflow releases once per 24 hours (cached check, network failures silent). When a newer version is detected, it surfaces a notification:

“Heads up: Ironflow v0.18.0 is available (you have v0.17.0). Run /ironflow update to install the latest skills.”

You can either run /ironflow update (router will confirm before overwriting) or paste the install command yourself.

Skills version-track the Ironflow project — server, SDKs, and skills share a single version number. When you upgrade Ironflow, your skills update with it.

How Skills Work with MCP

Skills and the MCP server are complementary:

MCP ServerSkills
WhatRuntime tools to interact with IronflowKnowledge about how to write/debug Ironflow code
AnalogyThe agent’s handsThe agent’s brain
Exampleironflow_list_runs returns dataThe 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 TemplateSkills
Static copy-pasteAuto-discovers and loads on demand
One big file for everythingFocused: one skill per task
No workflow guidanceStep-by-step agent workflow
No debugging supportFull diagnostic flowchart
Single formatWorks 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

Re-run the install command. The script is idempotent — it overwrites existing skill files with the latest from the repo.

Terminal window
curl -fsSL https://raw.githubusercontent.com/sahina/ironflow/main/install-skills.sh | bash

Or if your skills are vendored locally (--local install):

Terminal window
curl -fsSL https://raw.githubusercontent.com/sahina/ironflow/main/install-skills.sh | bash -s -- --local

The router’s daily check will surface the new version automatically. Type /ironflow update to trigger the update from inside your AI session.

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

Run /ironflow update from your AI session, or re-run the install command. The router’s version check caches for 24 hours; if you suspect stale cache, delete ~/.agents/skills/ironflow/.last_checked and trigger any Ironflow skill again.