# Air Workbench > Open AIR Workbench to discover local Agent Skills, visualize and round-trip a Skill workflow as AIR (Agent Intermediate Representation), review a native Codex or Claude plan, inspect observable execution evidence, or promote a reviewed plan or trace into a Skill draft. Use only when the user explicitly asks for AIR Workbench, the legacy Workflow Studio, Skill-to-graph or graph-to-Skill conversion, visual workflow editing, plan approval, observable tracing, or plan/trace promotion. Do not trigger for ordinary Skill execution, general planning, or routine Codex/Claude requests. - Skill: `jiunbae/air-workbench` (Agent Skill, multi-file: 73 files) - Install (CLI): `npx skillmds@latest add jiunbae/air-workbench` - Raw SKILL.md: https://api.skillmd.com/api/skills/jiunbae/air-workbench/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: jiunbae (https://skillmd.com/u/jiunbae) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/jiunbae/air-workbench --- # AIR Workbench Keep `SKILL.md` as the native executable and distributable artifact. AIR is the portable, editable interchange view: ```text SKILL.md ⇄ AIR workflow ⇄ visual graph ``` Resolve all script paths relative to this Skill directory. Do not install a global command: ```bash node scripts/air.mjs --help ``` AIR is a project-defined format, not an IANA or standards-body format. `agents/air-workbench/` is the current physical package path, renamed from `agents/workflow-studio/`; “Workflow Studio” identifies only `scripts/workflow-studio.mjs`, its compatibility commands, and legacy artifacts. ## 1. Open the current AIR Workbench editor Start AIR Workbench without an input to discover installed and project-local Skills automatically: ```bash node scripts/air.mjs workbench ``` The catalog scans standard project, user, system, repository, and authoritative enabled Codex plugin Skill roots with finite read-only bounds and exposes only opaque item IDs through the local API. Explicit enabled configuration and valid remote-install markers are authority; cache presence alone is ignored. It opens the first discovered Skill, or an empty document when none is available. The four-region shell keeps Resources, the React Flow canvas, Properties / Run setup, and Problems / Evidence / Source / Diff in one workspace. Use the Resources filter, **Quick Open** (`Command/Ctrl+P`), and manual **Refresh resources** as needed. Never accept a browser-supplied path, root, glob, URL, or output destination. The local catalog/OpenAPI contract is version `1.2.0`; AIR artifacts and `/air/v1` remain unchanged. A catalog Skill may carry a display-only `relative_path` label, relative to the root that observed it, so a Skill can be found by the directory a reader knows it by even when its frontmatter name differs; it is never absolute, never escapes that root, is omitted when it cannot be formed, and is never accepted as input. Skill content edits rotate opaque IDs. Use only an explicit `replaces_id` produced by a complete, mutually unique server-private same-source relation to offer Keep/Cancel/Reload. It covers only the immediately preceding successful generation and is not a route alias. Omit it for unchanged, split, merge, swap, incomplete, unreadable, or truncated scans; never match by public name, hash, source label, or path. Open a specific Skill or AIR artifact by supplying one input: ```bash node scripts/air.mjs workbench /path/to/skill/SKILL.md node scripts/air.mjs workbench /path/to/workflow.air.json ``` Discovery is enabled at launch. It is snapshot-based: do not claim a watcher, live follow, provider signal, or managed run. Modified documents are isolated in memory, and a resource switch requires Keep, Discard, or Cancel instead of silently replacing edits. Default binding is loopback. An explicit `--host 0.0.0.0` is informed consent to expose the same token-protected, read-only catalog over plaintext HTTP to reachable IPv4 networks: ```bash node scripts/air.mjs workbench \ --host 0.0.0.0 ``` Tell the user to replace `0.0.0.0` in the printed URL with `http://:PORT/?token=TOKEN`, preserving the port and token. Use a trusted network/firewall, keep the token URL private, and stop the process after review. Do not describe `0.0.0.0` as local-user-only. ## 2. Inspect metadata-only Codex and Claude sessions The default Resources catalog includes bounded Codex rollout streams and Claude main/subagent streams. Selecting a session creates an in-memory, read-only AIR `trace` snapshot. Its graph and Evidence timeline contain observed record envelopes plus separately inferred temporal order. `hidden_reasoning_recovered` is always `false`. All public surfaces omit raw prompts, messages, reasoning, commands and arguments, results, stdout/stderr, attachments, file content, environment and credentials, branches, filesystem paths, and provider identifiers. Use only opaque server-instance session/snapshot IDs. The artifact must retain the metadata-only privacy manifest and omission counts. Require every published catalog row to have a unique opaque session ID that resolves to exactly one server-private source authority. Never reissue a public snapshot ID during one server registry lifetime, even after its private continuation handle expires. **Refresh resources** takes another bounded catalog snapshot and, for the selected session, requests continuation from the last server-owned cursor. Incomplete trailing JSONL remains uncommitted until a later manual refresh. If a continuation source was truncated, replaced, rotated, or rewritten, report the source change instead of joining histories. Even when no prior snapshot handle is supplied, verify the server-owned last-published bounded continuity high-water before reusing an epoch or event IDs. Revalidate that high-water at every later publication cut and do not lower it when a fresh capture accepts a shorter prefix; start a new epoch with disjoint event IDs after a mismatch. Provider lifecycle evidence is asymmetric; `unknown` is correct when no authoritative evidence exists. Session graphs are evidence, not editable workflows. Do not enable step/edge editing, plan setup, Markdown export, source, or diff for them, and never expose raw provider JSONL to the browser. ## 3. Choose the AIR representation - `.air.json` is the complete AIR 1 artifact for `workflow`, `plan`, and `trace`. - `.air.md` is the lossless workflow-only Markdown carrier defined by the AIR codec. Lossless does not mean byte-identical: the carrier is the source bytes as an exact prefix plus an appended inert `air:v1` metadata comment, so it is always larger than the source. Never tell a user that `air convert` returns their original bytes. The byte-preserving render is `workflow-studio export` on an unedited import. - `.air.md` contains valid Agent Skill Markdown, but Codex and Claude do not discover it merely from that extension. To activate or distribute it as a native Skill, place the reviewed bytes at `/SKILL.md` — after confirming with the user which of the two outputs they want there. - Plans and traces use `.air.json`; Markdown reports of them are non-lossless views, not AIR carriers. Use the AIR CLI to import, validate, or convert without overwriting an existing output: ```bash node scripts/air.mjs import /path/to/skill/SKILL.md \ --out /path/to/workflow.air.json node scripts/air.mjs validate /path/to/workflow.air.json node scripts/air.mjs convert /path/to/workflow.air.json \ --out /path/to/workflow.air.md ``` ## 4. Migrate legacy artifacts explicitly AIR Workbench reads Workflow IR `1.0`, exact `workflow-studio:v1` Skill metadata, plain `SKILL.md`, and saved legacy workflow/plan/trace artifacts. It does not silently rewrite them. Migration is deterministic, no-overwrite, and new-output-only. A migrated legacy plan loses executable approval because AIR binds different bytes; any old approval is historical, non-authorizing provenance. Require a fresh AIR approval before any future AIR-native execution path. ```bash node scripts/air.mjs migrate /path/to/legacy.json \ --to air/1 \ --out /path/to/migrated.air.json ``` ## 5. Review and edit a workflow Keep the graph canvas, semantic outline, selection inspector, source, and diff in one review context: - select a step or dependency on the React Flow canvas or keyboard-operable outline; - edit step titles/bodies and supported dependency properties; - add, reorder, or delete steps and connect/reconnect dependencies; - use bounded undo/redo for semantic graph edits; and - review source and the full diff before downloading an artifact or Markdown draft. Canvas positions, viewport, focus, and selection are presentation state and must never enter AIR, legacy Workflow IR, plan hashes, approvals, or promoted Skills. Mount the interactive canvas only at or below 1,000 nodes and 1,000 edges. Above either limit, use the bounded first-100-rows-per-kind fallback while preserving validation, diagnostics, source truth, and downloads. For a real repository smoke test: ```bash node scripts/workflow-studio.mjs import \ ../background-implementer/SKILL.md \ --out /tmp/background-implementer.workflow.json node scripts/workflow-studio.mjs studio \ /tmp/background-implementer.workflow.json ``` An unchanged Skill round-trip must preserve its source bytes exactly. Unsupported or ambiguous Markdown remains opaque rather than being guessed. ## 6. Use the legacy native-run compatibility path The established Workflow IR `1.0` native-run commands remain available unchanged while AIR-native plan/run support is developed: ```bash node scripts/workflow-studio.mjs plan /path/to/workflow.json \ --agent codex \ --cwd /path/to/workspace \ --prompt-file /path/to/prompt.txt \ --safety read-only \ --out /path/to/plan.json node scripts/workflow-studio.mjs approve /path/to/plan.json \ --out /path/to/approved-plan.json node scripts/workflow-studio.mjs run /path/to/approved-plan.json \ --trace /path/to/trace.json ``` Use `--agent claude` for Claude Code. Default to `read-only`; `workspace-write` requires a separate explicit choice. Browser review is not CLI authorization. Any prompt, graph, agent, working-directory, safety, or command change requires new approval. The browser's **Run setup** prepares and downloads a reviewed plan; it is not a Run control and does not grant native approval. Before a native run, state that the graph is supplied to the selected CLI but is not enforced node by node. A trace includes observable provider events and explicitly inferred sequence, not hidden reasoning or causal truth. Missing CLIs fail explicitly; never install, silently fall back, add bypass flags, or accept arbitrary passthrough arguments. ## 7. Promote a reviewed legacy plan or trace Promotion always writes a new Skill draft and never overwrites a source: ```bash node scripts/workflow-studio.mjs promote /path/to/plan-or-trace.json \ --name reviewed-workflow \ --description "Run the reviewed workflow." \ --out /path/to/reviewed-workflow ``` Review generated instructions and provenance warnings. Trace-derived steps describe observed history, not guaranteed future behavior. ## Compatibility and limits - AIR 1 uses `format: "air"`, `air_version: "1.0.0"`, the `https://open330.github.io/air/` project origin, and canonical `/air/v1` read-only discovery routes. - `/api/artifact`, Workflow IR `1.0`, `workflow-studio:v1`, and `scripts/workflow-studio.mjs` remain explicit compatibility boundaries. - The server has no browser file-write, Skill-install, or agent-run endpoint. - Native execution remains delegated to installed Codex and Claude CLIs; AIR Workbench is not a managed node-by-node orchestrator. - The default Resources catalog discovers bounded Skills plus metadata-only Codex rollout and Claude main/subagent sessions. Session snapshots and timelines are read-only and refresh manually; there is no watcher or live follow. - The installed runtime uses checked-in same-origin assets and needs no npm, CDN, registry, telemetry, remote service, or global executable. - Import coverage is partial and shape-based. Only the recognized document shapes become steps; anything else imports to zero nodes and zero edges with a `workflow.none` warning, which is a normal result and not an error. The bottom rung chains ordinary `##` sections in document order and marks the result `heuristic` confidence with `inferred` edge provenance — say so instead of presenting an inferred order as the author's declared sequence. `README.md` lists the rungs and their `confidence.rule_id` values. - This Skill is not part of the `core` install profile. Install it explicitly with `agt skill install -g --from jiunbae/agent-skills/agents/air-workbench` or `./install.sh agents/air-workbench`. See `README.md` and `spec/AIR-1.0.0.md` for the complete contract, safety model, build instructions, and compatibility matrix.