Agent Flow: How KLIP-10 Turns Kimi CLI into a Script-Driven AI Director

Overview

Imagine sitting at a terminal late at night, but instead of writing code, you are directing an adventure play for an intelligent agent. Every node is a conversation, every branch is a fate choice. KLIP-10 introduces Agent Flow: Kimi CLI no longer just waits for single instructions — it can read a "script" drawn as a flow chart and perform it step by step until the curtain falls.

Why Agent Flow

Previously, Kimi CLI behaved like a faithful squire: one command, one action. Complex tasks meant repeated input and constant context re-explanation. Developers wanted agents that can read an entire script at once, move through nodes sequentially, and choose paths based on outcomes.

KLIP-10 extends Agent Skill with two types: standard and flow. A flow skill is fundamentally a flow chart in Mermaid or D2. BEGIN marks the start, END marks the finish, intermediate nodes hold prompts, and branch nodes use edge labels for choices.

Flow charts win over code because they are intuitive — "do A, then choose B or C" is clearer as a diagram than nested if-else blocks. Mermaid and D2 are declarative, render inline in Markdown, and have very low entry barriers while still expressing complex control flow.

Minimal but Elegant Syntax Subset

Agent Flow does not parse full Mermaid or D2 — that would bloat the implementation. It supports only the minimal subset needed for roughly 99% of real use cases.

In Mermaid, use flowchart TD (top-down) or LR (left-right). Nodes are written as [text], (text), or {text} — shape is cosmetic only. Edges use -->, and branch labels use -->|yes| or -- yes -->. Inline node definitions on edges are supported.

In D2, nodes are written as ID: label, edges use ->, and labels go on the last segment. Comments start with #. Node IDs allow letters, digits, underscores, dots, slashes, and hyphens.

These limits are deliberate. Full Mermaid supports subgraphs, styles, click events, and more — none of which an agent needs. Stripping them lowers parsing complexity and prevents users from authoring "fancy scripts" the agent cannot understand.

Example: an email-writing flow.

• BEGIN → Draft email → Need formal tone? {yes/no} → Polish / Send → END

The agent drafts, asks the user to pick yes or no, then follows the chosen path.

Data Structure and Strict Validation

At the code level, Agent Flow is an elegant Flow class containing a node dictionary, an outgoing-edge list, a start ID, and an end ID. Each node has id, label (plain text or rich content block), and kind (begin, end, task, decision). Edges record source, target, and optional label.

Validation rules act like a strict director:

• Exactly one BEGIN and one END (case-insensitive by node text).
• BEGIN must be reachable to END.
• Nodes with multiple outgoing edges must have non-empty, non-duplicate labels on every edge.
• Single-outgoing-edge nodes may omit labels (they are ignored).
• Undeclared nodes referenced by edges are auto-created with the ID as default label.

Violations raise dedicated exceptions: FlowParseError (syntax) or FlowValidationError (structure), with clear messages and line numbers for quick fixing.

Discovery and Loading: Dual Identity in the Skill Catalog

Agent Flow fully reuses the existing Agent Skill discovery mechanism. Built-in skills, user-home skills, and project-directory skills are all scanned. When SKILL.md declares type: flow and contains a mermaid or d2 code block, the parser builds a Flow object attached to Skill.flow.

If parsing fails or no valid flow chart is found, the system silently degrades to a standard skill and logs a message. This preserves backward compatibility and prevents one broken diagram from disabling an entire skill.

After loading, standard skills remain callable via /skill:<name>, while flow skills gain the dedicated entry /flow:<name>. During KimiSoul initialization, these commands are dynamically registered as instance-level slash commands alongside built-ins.

FlowRunner: The Engine That Brings Scripts to Life

The FlowRunner class is what makes a static diagram come alive. Acting as a director, it holds the script (Flow object) and guides the agent (KimiSoul) through each step.

For each node, the runner:

1. Checks the number of outgoing edges to decide whether branching is required. 2. Builds a dedicated prompt — for task nodes, the node label becomes a system prompt; for decision nodes, the prompt appends the list of available branches and instructs the model to emit a <choice> tag at the end of its reply. 3. Sends the prompt to KimiSoul and receives the reply. 4. For decision nodes, uses a regex to extract the last <choice>...</choice> content from the assistant's final message, trims it, and matches it against edge labels. 5. Jumps to the next node based on the match.

If the model forgets to output a choice or outputs the wrong one, FlowRunner automatically retries, appending a reminder like "please follow the required format" to the next prompt. To prevent infinite loops, a max_moves hard cap (default 1000 steps) is enforced; exceeding it raises an exception.

KimiSoul itself is refactored: slash commands are no longer globally registered but built per instance. Each conversation session now owns its own skill command set, and flow commands integrate naturally.

Ralph Mode: The Automatic Loop Easter Egg

Ralph mode is a hidden bonus. When launched with --max-ralph-iterations, KimiSoul auto-generates a special loop flow: starting from your initial instruction, it runs Execute → Decision (CONTINUE/STOP) → if CONTINUE, returns to the decision node → until STOP is chosen or the iteration limit is reached.

This loop is dynamically generated by the static method FlowRunner.ralph_loop, requiring no hand-authored flow chart. It is ideal for scenarios like iteratively polishing code or refining a design until it meets your standards. The name likely references a classic "retry until correct" meme.

CLI Integration and User Experience

No new commands are needed. Place a flow chart in SKILL.md, declare type: flow, restart Kimi CLI, and type /flow:<skill-name> in conversation to start the show. Everything still happens in the familiar shell UI: the agent outputs node results, you enter choices (or plain messages), and the agent advances automatically.

Error handling is humane: syntax errors point to specific line numbers; structural errors explain whether BEGIN is missing or branch labels collide; selection failures trigger automatic retry with a reminder. All key events are logged to aid debugging complex flows.

Boundaries and Compatibility: Graceful Trade-offs

KLIP-10 explicitly excludes advanced features such as subgraphs, styles, links, click events, and full Mermaid/D2 syntax. These trade-offs keep the implementation lightweight and reliable, and keep users focused on logic rather than decoration.

BEGIN and END must be those exact words (case-insensitive). Branch labels should be short, stable, and free of newlines or special characters. Cyclic graphs are allowed but bounded by max_moves, preventing accidental infinite loops.

Backward compatibility is watertight: legacy skills are unaffected, and failed flow parsing gracefully degrades to standard mode — quietly and elegantly.

Closing Thoughts

Watching a hand-drawn flow chart drive an agent step by step — drafting an email, asking about tone, polishing, finally "sending" — reveals a shift: we are no longer just using tools, we are collaborating with a script-reading intelligent partner. Agent Flow turns static prompts into dynamic journeys and one-way instructions into two-way dialogue. The future of AI agents may lie less in stronger models and more in more natural forms of control — like directing a film instead of feeding actors line by line.

---

References

1. KLIP-10 Proposal: Agent Flow (Agent Skill Extension). Author: @stdrc, Updated: 2026-01-20. 2. Kimi CLI official repository skill system implementation. https://github.com/MoonshotAI/kimi-cli/tree/main/src/kimi_cli/skill 3. Mermaid flowchart official documentation (subset reference). https://mermaid.js.org/syntax/flowchart.html 4. D2 declarative diagram language official documentation (subset reference). https://d2lang.com/tour 5. Agent Client Protocol and skill extension related discussions (background reference). https://github.com/agentclientprotocol/agent-client-protocol