Turn a flow into a reliable agent tool.

01 / THE ARCHITECTURE

Keep orchestration and instructions separate

The Knodr flow is the executable graph. MCP is the control plane an AI client uses to author, validate, start, and inspect it. A client-side skill is the operating procedure that tells the AI when and how to use those tools.

02 / BUILD THE FLOW

Two inputs, one agent, one result

1. 01
   Add two Manual Input nodes

   Label them Task and Working directory. Leave their saved values empty so callers must supply them.

2. 02
   Add Agent CLI

   Select codex, set the timeout to 600 seconds, and enter --sandbox and read-only as separate extra-argument lines.

3. 03
   Wire the inputs

   Connect Task value to Agent CLI task, and Working directory value to workingDirectory.

4. 04
   Expose the result

   Connect Agent CLI stdout to Preview value, then save as flows/agent-task.knodrflow.

03 / AUTHOR WITH MCP

Let an AI client build the same graph

First call list_nodes, then get_node_schema for input.manual, agent.cli, and output.preview. That confirms the installed parameters and port names before any write.

Call scaffold_flow to create flows/agent-task.knodrflow, then make one atomic apply_flow call with this shape. Omitting coordinates lets Knodr arrange the graph left to right.

{
  "path": "flows/agent-task.knodrflow",
  "nodes": [
    {
      "id": "task",
      "typeId": "input.manual",
      "parameters": { "label": "Task" }
    },
    {
      "id": "working_dir",
      "typeId": "input.manual",
      "parameters": { "label": "Working directory" }
    },
    {
      "id": "agent_runner",
      "typeId": "agent.cli",
      "parameters": {
        "tool": "codex",
        "extraArgs": "--sandbox\nread-only",
        "timeoutSeconds": "600",
        "failOnNonZeroExit": "true"
      }
    },
    { "id": "result", "typeId": "output.preview" }
  ],
  "connections": [
    {
      "fromNode": "task", "fromPort": "value",
      "toNode": "agent_runner", "toPort": "task"
    },
    {
      "fromNode": "working_dir", "fromPort": "value",
      "toNode": "agent_runner", "toPort": "workingDirectory"
    },
    {
      "fromNode": "agent_runner", "fromPort": "stdout",
      "toNode": "result", "toPort": "value"
    }
  ]
}

Finish authoring with validate_flow. Treat an ok: false result as a hard stop; fix the graph before starting a run. apply_flow is atomic, so an invalid authoring request does not leave a half-built graph behind.

04 / RUN & OBSERVE

Use a run ID, not hope

Call start_run with values keyed by Manual Input node ID. Capture the returned runId immediately.

{
  "path": "flows/agent-task.knodrflow",
  "inputs": {
    "task": "Review the current changes for correctness.",
    "working_dir": "C:\\work\\my-project"
  },
  "timeoutSeconds": 660
}

Poll until state is success, failed, or cancelled. On failure, call get_run_snapshot for the failed node and port values, then get_run_logs for the execution trail. Report the runId so another operator can inspect the same durable run.

05 / CREATE AN AI-AGENT SKILL

Encode the operating procedure

A good skill defines when to use the flow, verifies prerequisites, resolves inputs explicitly, owns the complete run lifecycle, and returns durable evidence. The exact skill directory depends on your AI client; the example below shows the portable instruction pattern.

---
name: review-with-knodr
description: Review a project with the Knodr agent-task flow.
---

# Review with Knodr

Use this skill when the user asks for an independent code review.

## Preconditions

- Require the Knodr MCP tools.
- Require `flows/agent-task.knodrflow`.
- Require the selected agent CLI to be authenticated.

## Procedure

1. Resolve the absolute project root. Do not guess.
2. Call `validate_flow` for the flow path. Stop on errors.
3. Call `start_run` with:
   - `task`: a precise, read-only review request
   - `working_dir`: the resolved project root
   - `timeoutSeconds`: 660
4. Save the returned `runId`.
5. Poll `get_run_status` until `success`, `failed`, or
   `cancelled`.
6. On success, call `get_run_snapshot` and read the result.
7. On failure, call `get_run_snapshot` and `get_run_logs`;
   report the failed node and actionable error.

## Response

Report findings first, then the flow path, agent used, and runId.

Why each part matters

06 / GROW TO MULTI-AGENT REVIEW

Scale the graph, preserve the contract

The multi-agent review reference follows the same lifecycle at a larger scale: prepare one diff, fan the review prompt out to several agent.cli nodes, tolerate individual reviewer failures through explicit error outputs, aggregate the surviving reviews, then ask a final consensus agent to write the report.

Do not start with that full graph. First make this single-agent flow reliable. Then add parallel branches, explicit fallback paths, and a final artifact. The skill still performs the same five duties: preflight, resolve inputs, start, poll, and report.