StoatFlow AI Assistant Skills: correct StoatFlow, not hallucinated Kafka Streams

TL;DR
What: a public, versioned pack — six task-cut skills (build, test, port, configure, set up, operate) plus a shared primer and editor rule files, all Apache-2.0.
Install (Claude Code): /plugin marketplace add stoatflow/skills, then /plugin install stoatflow@stoatflow.
Install (any agent): npx skills add stoatflow/skills, or copy AGENTS.md into your repo.
Pin the version: the pack ships in lockstep with StoatFlow releases — use the tag matching yours.
The catch: it documents StoatFlow; you still need customer credentials to resolve the library from maven.stoatflow.io.

We've published the StoatFlow AI Assistant Skills: a free, open pack of six task-cut skills and editor rule files that make Claude Code, Cursor, Copilot, and other coding assistants write correct StoatFlow instead of hallucinated Kafka Streams.

The pack exists because of a specific problem. StoatFlow is source-compatible with Kafka Streams — swap the import root and your topology compiles — and that same compatibility is why an AI assistant gets it confidently wrong.

Why your AI assistant writes Kafka Streams, not StoatFlow

StoatFlow ships the Kafka Streams DSL over a different engine. You swap org.apache.kafka.streams.* for io.stoatflow.core.*, recompile, and existing topology code runs. That drop-in compatibility is the whole point of the DSL — and it's exactly what trips an assistant up.

Every mainstream model trained on years of Kafka Streams code and documentation. Ask one for a StoatFlow topology and it reaches for what it already knows:

the wrong import root — org.apache.kafka.streams.* rather than io.stoatflow.core.*;
the Kafka Streams at_least_once default, where StoatFlow defaults to exactly-once;
replicas: N horizontal scaling, where StoatFlow runs one instance per app and scales up, not out;
Maven Central coordinates, where StoatFlow resolves only from the private maven.stoatflow.io;
Kafka Streams watermark and timestamp semantics, where StoatFlow follows Flink instead.

Every one of these compiles. Every one is wrong in a way you catch only if you already know StoatFlow — a default baked into a config, a scaling model that doesn't exist here, an exactly-once guarantee downgraded to at-least-once. Source-compatibility removes the friction that would otherwise flag the mismatch, so the assistant never gets the signal that it's on unfamiliar ground.

What's in the pack

The guidance is cut the way you actually work — one skill per task, so the relevant rules load when they matter instead of arriving as one wall of text. Each skill fires on what you're doing:

Skill	Loads when you're…
`stoatflow-build-topology`	writing topology code — DSL, Processor API, serdes, state stores, DLQ
`stoatflow-test`	writing tests — `TopologyTestDriver`, integration tests
`stoatflow-port-from-ks`	porting a Kafka Streams app — code and state
`stoatflow-configure`	configuring an app — `application.yaml`, guarantees, lanes, HA
`stoatflow-project-setup`	wiring the build — the private Maven repo, licence, JDK 25, Docker, native image
`stoatflow-operate`	deploying and running it — single-instance Kubernetes, HA, probes, metrics, tuning

Under the skills sits a shared primer — the identity and the hard rules every skill inherits — and a set of editor rule files generated from that same source: an AGENTS.md for Codex and the AGENTS.md-aware tools, plus Cursor, Copilot, and JetBrains variants. The same facts, whichever assistant reads them.

How it stays correct

Documentation that has drifted from the code is worse than none: it's wrong with authority, and an assistant repeats it without the hesitation a human reader might feel. The pack is built against that failure mode. On every StoatFlow release we drift-check it against the three sources it can't afford to lag — the porting guide, the compatibility matrix, and the configuration schema — and ship it with a version that is the StoatFlow version it targets. Each artefact prints a "Targets StoatFlow 1.0.0-beta.8" line. Pin the tag to your release, and the divergence rules and config reference match the library you're actually running.

Install it

The pack lives in the public repo stoatflow/skills. Install it the way your assistant expects:

Tool	Install
Claude Code	`/plugin marketplace add stoatflow/skills`, then `/plugin install stoatflow@stoatflow`
Any agent (skills CLI)	`npx skills add stoatflow/skills`
Codex / AGENTS.md tools	copy `AGENTS.md` into your app repo
Cursor	copy `cursor/rules/stoatflow.mdc` to `.cursor/rules/`
GitHub Copilot	copy `copilot/stoatflow.instructions.md` to `.github/instructions/`
JetBrains AI / Junie	copy `jetbrains/guidelines.md` to `.junie/guidelines.md`

What it doesn't do

A few boundaries worth stating plainly.

The pack teaches the public API and the concepts, and nothing below them. StoatFlow's engine internals are obfuscated in the shipped jar and off-limits by design; the pack holds the same line, so it won't explain — or invent — how the engine works inside.

A skill shifts what your assistant reaches for first. That's most of the battle, not a guarantee: a determined model can still produce Kafka Streams under a StoatFlow prompt. Read the output, especially around guarantees, scaling, and imports — the three it gets wrong most.

StoatFlow itself is commercial; the pack is free and Apache-2.0. Installing the skills documents the library, it doesn't unlock it — you still need customer credentials to resolve StoatFlow from maven.stoatflow.io.

And it's new. It shipped with this release and improves with each one, so pin the matching tag and expect the rules to sharpen release over release.

Where to go next

The pack, with every skill and rule file: stoatflow/skills.
The setup guide, including the per-editor install: AI assistants.
Found something the pack gets wrong? Reach out — it's maintained upstream, and a concrete miss is the most useful thing you can send.

For the running commentary on how StoatFlow gets built, follow along on LinkedIn.