How to use the Graph Pipeline Runner agent skill

What the graph skill makes the agent do

Normally an agent decides its next move as it goes. This skill does the opposite for a multi-step job: the sequence, dependencies and commands are written down in a JSON descriptor first, then executed by the runtime rather than re-planned mid-run.

Progress is streamed as lines tagged [run], [node], [ok], [fail], [join] and [done]. The skill is aimed at repeatable build, test or check sequences and at runs that must survive interruption.

• Good fit: repeatable multi-step pipelines with explicit dependencies
• Good fit: work that must survive a kill or restart
• Good fit: runs that need an audit trail under .omc/graph-runs/<run_id>/
• Poor fit: exploratory one-off work, where ordinary conversation or /team is more suitable
• Poor fit: anything that needs re-planning during the run, because graphs are deterministic

How to install the graph skill

Download the ZIP file from this page. Then choose one of two routes.

For Claude Code, unzip the download into ~/.claude/skills/ to make it available everywhere, or into a project's .claude/skills/ folder to limit it to that project.

In the Claude apps, open Settings, go to Capabilities, then Skills, and upload the ZIP there.

• Personal install: ~/.claude/skills/
• Project install: .claude/skills/ inside your project
• Claude apps: Settings → Capabilities → Skills

Check the requirements before you run anything

The skill depends on oh-my-claudecode being installed, with the omc command line tool available in your shell. It also needs a Node.js environment for the graph runtime. Agent-type nodes need Claude Agent SDK access.

The skill runs scripts and uses the network, so plan for both. The command the skill uses is the CLI subcommand below; the optional --runs-root flag sets where run data is written.

• oh-my-claudecode installed, with omc available
• Node.js environment for the graph runtime
• Claude Agent SDK access for agent-type nodes
• The skill runs scripts: yes. It uses the network: yes.

How to trigger the skill with a request

You can invoke the skill directly with its slash command, passing either a descriptor file or a plain-language description of the pipeline. If you describe a pipeline, the skill authors the descriptor JSON first, writes it into your project (the suggested location is .omc/graphs/<name>.json), and shows it to you before anything runs.

A request such as 'build, then test, then ask me before deploy' is the kind of description the skill is designed to turn into a descriptor. Review the file before running it.

• Direct: /oh-my-claudecode:graph <descriptor.json>
• From a description: /oh-my-claudecode:graph "build then test then ask me before deploy"
• Give each logical pipeline its own run_id, because rerunning with the same run_id resumes instead of restarting

Run a pipeline and resume it after an interruption

Non-interactive graphs run through the Bash tool with omc graph run. If a run is killed partway through, rerun the same command. Committed transitions are replayed and the run continues. Completed nodes are not executed again.

Exit codes tell you the outcome: 0 means succeeded, 1 means terminal failure, 19 means another writer owns the run, 20 means the journal is corrupt or tampered with (the run fails closed), 21 means the descriptor changed on resume, and 70 means an unmapped runtime crash.

• 0 succeeded
• 1 terminal failed
• 19 another writer owns this run (busy)
• 20 corrupt or tampered journal (fail-closed)
• 21 descriptor drift on resume
• 70 runtime crash (unmapped error)

Handle approval steps interactively

If a descriptor contains a node of kind human-approval, do not run it through the Bash tool. There stdin is not interactive, and an end-of-input answer is treated as denied. Instead, run it yourself in the session with the ! prefix so that y/n answers work.

The source describes this approval behaviour only for interactive runs, so plan approval gates for that mode.

• Run approval graphs with the ! prefix so stdin stays live
• Automated Bash runs will deny approval gates

Safety notes before you run a descriptor

Command nodes are arbitrary shell lines with full process authority in the current working directory. They are not sandboxed for files or processes. Only run descriptors you wrote or trust. Command children get an allowlisted environment (such as PATH, HOME, temp folders, locale and GRAPH_* values), not your full set of host secrets.

Built-in agent nodes are read-only: they can use Read, Glob and Grep only, and they cannot edit files or call external services. Crash recovery is at-least-once for command nodes, so a command can run again after a crash that happened between its side effect and the journal write. Treat .omc/graph-runs/<run_id>/descriptor.json as executable content.

• Do not run unreviewed shell commands through a graph
• Agent steps that must edit files or call services need a custom executor
• Exactly-once behaviour for external side effects is out of scope for v1
• Idempotent commands receive GRAPH_IDEMPOTENCY_KEY before they start

Tips for writing reliable graphs

Keep each node small and give each a clear title and timeout, so failures are easy to read. Use max_attempts for commands that may fail transiently. Check the descriptor schema in src/graph/schema.ts for the authoritative rules.

Built-in executors cover fixed edges and fan_out/join pairs. Conditional and back_edge routes need a custom executor that emits a route, and without one the graph fails fast with route_required instead of guessing.

• Use fixed edges and fan_out/join pairs with the built-in executors
• conditional and back_edge routes require a custom NodeExecutor
• Built-in executors reject reconcile
• Set concurrency_limit to control parallel nodes