Deeper Dive into Conductor Skills: Teaching AI Agents to Orchestrate Workflows

AI coding agents are increasingly capable of writing code, running commands, and interacting with external systems. But they're only as useful as the context they have. By default, an agent like Claude Code, Cursor, or GitHub Copilot knows nothing about Conductor, about its CLI, its workflow JSON schema, how to connect tasks together, or how to handle authentication.

conductor-skills solves that. It's a structured knowledge package that teaches any major AI coding agent how to create, run, monitor, and manage Conductor workflows without the user having to explain any of it.

What it is

conductor-skills is a "skill". In agentic terms (at the moment) a skill is a set of files that, once installed, are loaded into an AI agent's context when relevant. The agent reads these files and gains working knowledge of Conductor: what commands to run, what the workflow JSON schema looks like, how to write workers in multiple languages, when to use which task type, and how to handle edge cases like missing CLI, auth errors, or unregistered workers.

Once installed, you can say things like:

• "Create a workflow that calls the GitHub API to get open issues and sends a Slack notification"
• "Connect to my Conductor server at https://play.orkes.io/api"
• "Show me all failed workflow executions from the last hour"
• "Write a Python worker that processes image thumbnails"
• "Signal the wait task in execution abc-123 with approval: true"

The agent handles everything, from the CLI installation, server connection, workflow JSON creation, task registration, execution, and monitoring end to end.

How It Works

The core: a single Markdown file

The heart of the skill is skills/conductor/SKILL.md. This is a structured Markdown document that gets injected into the AI agent's system context when the skill is activated. It tells the agent the rules, setup flow, and command references:

Rules — hard constraints on behavior. For example:

• Always try to install the conductor CLI before falling back to the Python script.
• Never echo auth tokens in output or logs
• Use --profile to target named environments, not raw URL overrides

Setup flow — a step-by-step procedure the agent follows for first-time setup: check if CLI is installed, offer local vs. remote server, test connectivity, handle 401s, save profiles.

Command reference — every major operation the agent might need, with exact CLI syntax and fallback equivalents:

# Register a workflow
conductor workflow create workflow.json

# Run synchronously
conductor workflow start -w fetch_url -i '{"url": "..."}' --sync

# Retry failed executions
conductor workflow retry {workflowId}

# Signal a WAIT task
conductor task signal --workflow-id {id} --task-ref {ref} --status COMPLETED

Output formatting rules — how to present results (structured summaries, never raw JSON dumps, never echo tokens).

Mermaid visualization - rules for generating flowchart diagrams from workflow definitions, including how to map each Conductor construct (SWITCH, FORK_JOIN, DO_WHILE, SUB_WORKFLOW) to the right Mermaid syntax.

The frontmatter at the top of SKILL.md also specifies which tools the agent is allowed to use when this skill is active:

---
name: conductor
description: "Create, run, monitor, and manage Conductor workflows and tasks."
allowed-tools: Bash(conductor *), Bash(python3 *conductor_api.py*), Bash(npm install *), Read, Write, Edit, Grep, Glob
---

This scopes the agent's tool access to only what's needed: the Conductor CLI, the fallback Python script, npm for installing the CLI, and file tools for writing workflow definitions.

Reference files

Beyond the main SKILL.md, the skill bundles three deep-reference documents that the agent reads when it needs more detail:

• references/workflow-definition.md — the full workflow JSON schema, every task type (SIMPLE, HTTP, INLINE, SWITCH, FORK_JOIN, DO_WHILE, WAIT, HUMAN, SUB_WORKFLOW, TERMINATE, and more), and the ${...} expression syntax for connecting inputs and outputs between tasks.

• references/workers.md — SDK examples for writing workers in Python, JavaScript, Java, Go, C#, Ruby, and Rust. Each example shows how to define a task function, connect to the server, and start polling.

• references/api-reference.md — REST endpoint details for direct API access, used when the agent needs to call the Conductor API directly (e.g. for integrations the CLI doesn't cover).

Example walkthroughs

Three worked examples give the agent concrete patterns to follow:

1. create-and-run-workflow.md – define a workflow, register it, check for missing workers, execute it, monitor it.
2. monitor-and-retry.md - search executions by status, diagnose failures from task output, batch-retry.
3. signal-wait-task.md - human-in-the-loop patterns with WAIT tasks and external signals.

The fallback script

If the agent is in an environment where Node.js and npm can't be installed, the CLI isn't available. For that case, the skill includes scripts/conductor_api.py, which is a self-contained Python script that covers the same operations (create workflow, start execution, get status, signal tasks, etc.) from direct REST API calls. That said, the agent is instructed to always try the CLI first and only fall back to this script if the CLI genuinely can't be installed.

How it was built

Agent-agnostic by design

The core skill is plain Markdown which is why this can be language agnostic. Every major AI coding agent like Claude Code, Codex CLI, Gemini CLI, Cursor, Windsurf, Cline, GitHub Copilot, Aider, Amazon Q, Roo Code, Amp, OpenCode has some mechanism for loading persistent instructions into context. They all read text. A skill built as Markdown can target all of them with the same content. So you’re not stuck with just using Claude Code.

The install scripts handle all of this automatically.

The install scripts

Two scripts ship with the repo: install.sh (macOS/Linux) and install.ps1 (Windows). They share the same logic:

1. Parse flags — --agent, --all, --global, --project-dir, --upgrade, --uninstall, --check
2. Auto-detect agents — scan for config directories and executables to find which agents are actually installed
3. Download skill files — pull the latest versions of SKILL.md, all reference files, all example files, and the fallback script from GitHub
4. Place them correctly — write files to the right location for each agent, global or project-level
5. Handle the Claude Code case — Claude Code has a native skill/plugin system, so the installer uses the appropriate mechanism rather than raw file copying

Running --all auto-detects every supported agent on the system and installs for each one. Running --upgrade re-downloads the latest files and overwrites existing ones. The installer is idempotent so re-running it only touches newly detected agents.

The Claude Code plugin

For Claude Code specifically, the skill ships as a native plugin with a proper manifest:

{
  "name": "conductor",
  "description": "Create, run, monitor, and manage Conductor workflows and tasks",
  "version": "1.0.0",
  "author": { "name": "Conductor OSS" },
  "repository": "https://github.com/conductor-oss/conductor-skills",
  "license": "Apache-2.0"
}

This enables marketplace installation:

/plugin marketplace add conductor-oss/conductor-skills
/plugin install conductor@conductor-skills

Claude Code loads the skill on demand. When a user's request matches the skill's description, the SKILL.md content is injected into context and the allowed tools are activated.

What This Pattern Enables

conductor-skills is an example of a broader pattern: giving AI agents durable, structured domain knowledge rather than explaining things from scratch in every session. The alternative is prompting an agent with "here's how Conductor works" every time which doesn't scale and wastes tokens, is prone to errors, wastes time and is overall annoying.

This matters for Conductor specifically because Conductor workflows involve a lot of moving parts: the CLI, server connectivity, authentication, JSON schema, task types, worker registration, execution monitoring, error handling.

You can also check out the public repository if you want to explore it even more and see how it was built.