How Conductor Skills Teaches AI Agents to Build Workflows

Ask Claude Code to build you a Conductor workflow and one of two things happens. It gets confident and invents a CLI flag that doesn't exist, guesses at a JSON schema, and hands you a very convincing answer that's wrong. Or it tells you it's not sure and goes looking for the docs online. The root cause is the same either way. It might be working off information that's since changed, or the answer might live in docs we wrote for people, not in a form a machine can act on.

And even when an agent does know Conductor reasonably well, building a good workflow means knowing the difference in intricate technicalities, like how task types connect, how inputs and outputs thread between them, and how auth gets handled. So how do you get an agent to build your workflows as fluently as it writes your app code?

Well, conductor-skills is the answer. 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.

More about Conductor Skills

conductor-skills is an AI "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 they're relevant. The agent then reads these files and gains working knowledge of Conductor. For example, 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. Things that Claude, or any agent, might not know by default.

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"
• "Help me understand workers in Conductor. I am new to it and I don't code."

The agent handles everything from here (though it might ask you follow up questions), from the CLI installation, server connection, workflow JSON creation, task registration, execution, and monitoring end to end.

How It Works

The heart of the skill is skills/conductor/SKILL.md. This is a structured Markdown document that gets added 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:

• 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.

• 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.

• 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 conductor skills 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 most agents, installing conductor-skills means the install script drops a Markdown file into the right config directory and the agent picks it up on next load. I don't think there is a formal concept of a "skill". It's just a text file the agent happens to read.

Claude Code handles this differently. It has a native plugin system where skills are registered as named, versioned packages rather than loose files. So for Claude Code, conductor-skills ships as a proper plugin with a name, version, author, and source repository declared in a manifest.

This means you can install it through Claude Code's plugin marketplace with a single command, update it when a new version ships, and Claude Code loads it on demand only when it's relevant, rather than adding it into every conversation.

{
  "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.

If you want to see how I used Claude Code to build a very simple workflow, I have an article on that.

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