Skills

OrchStep provides skill documents that teach LLM agents domain-specific knowledge about workflow authoring, MCP integration, and module creation. Skills are structured instruction sets that agents load to become proficient with OrchStep.

Installing Skills

Skills live in the orchstep repository under skills/. Install one user-wide with a single command, then start a new agent session so the agent discovers it. The examples below install orchstep-workflow-design; swap in any skill name from the list on this page.

Claude Code

mkdir -p ~/.claude/skills && curl -fsSL https://github.com/orchstep/orchstep/archive/refs/heads/main.tar.gz \
  | tar -xz --strip-components=2 -C ~/.claude/skills orchstep-main/skills/orchstep-workflow-design

For a project-scoped install, target .claude/skills/ inside your repository instead of ~/.claude/skills. Verify that ~/.claude/skills/orchstep-workflow-design/SKILL.md exists, then invoke /orchstep-workflow-design in a new session — or simply ask the agent to "design an OrchStep workflow that builds and tests my app" and the skill triggers automatically.

Prefer to let the agent install it for you? Paste this prompt into Claude Code:

Install the OrchStep workflow-design skill: download
https://github.com/orchstep/orchstep/archive/refs/heads/main.tar.gz and extract
skills/orchstep-workflow-design into ~/.claude/skills/ (create the directory if
needed). Verify ~/.claude/skills/orchstep-workflow-design/SKILL.md exists, then
tell me how to invoke the skill.

Codex

mkdir -p ~/.codex/skills && curl -fsSL https://github.com/orchstep/orchstep/archive/refs/heads/main.tar.gz \
  | tar -xz --strip-components=2 -C ~/.codex/skills orchstep-main/skills/orchstep-workflow-design

Codex discovers skills from ~/.codex/skills by default; if CODEX_HOME is set, use $CODEX_HOME/skills instead. Verify that orchstep-workflow-design/SKILL.md exists below the skills directory, then start a new Codex session and ask it to design an OrchStep workflow.

Other agents

If your agent supports SKILL.md packages, copy the whole skills/orchstep-workflow-design directory into its skills directory. Otherwise, add the raw SKILL.md URL to the agent's project instructions (for example AGENTS.md or .cursor/rules) with a note to read and follow it when designing OrchStep workflows.

Tested on Claude Code; Codex confirmed by a community report (details). If you verify another agent, tell us.

Available Skills

orchstep-workflow-design

Designs production-quality OrchStep YAML workflows from user requirements. Three modes adapt to how much the user already knows:

Quick mode — for concrete requests ("write a deploy pipeline"). Reads from 9 bundled reference files covering syntax, functions, templates, variables, control flow, error handling, modules, stdin, and anti-patterns. Produces a complete workflow with error handling, assertions, and rollback paths. No questions asked.

Wizard mode — for vague or exploratory requests ("help me design my CI pipeline"). Asks 2-4 intent questions about trigger, environments, complexity, error tolerance, and human interaction needs. Produces a tailored workflow with a design rationale explaining why each pattern was chosen.

Deep dive mode — for edge cases or version-specific behavior. Fetches real examples from the public website source or references bundled annotated examples for the latest patterns.

Bundled with 4 annotated example workflows (CI pipeline, deploy-with-approval-gates, parallel build matrix, multi-env promotion). Replaces the earlier orchstep-workflow-authoring skill with richer reference material and a smarter design flow.

Use when: Creating new workflows, improving existing ones, or learning the best way to model a process in OrchStep. Works equally well with "write this" and "help me design."

Built-in prompt generators

You don't have to write the prompt yourself. The orchstep repository ships prompt-generator tasks in its root orchstep.yml: each one interviews you with select/checkbox/text questions, then prints a ready-to-paste prompt engineered for this skill — CI/CD pipelines, release automation, environment setup, and migrations, out of the box.

git clone https://github.com/orchstep/orchstep.git && cd orchstep

orchstep run prompt_migrate    # migrate existing automation (Make, Just, Task, Ant, Gradle, scripts, CI) to OrchStep
orchstep run prompt_features   # design a new workflow from a feature checklist (env groups, dotenv, retries, ...)
orchstep run prompt_scenario   # common scenarios: env setup, CI/CD, release, runbooks, data pipelines

Paste the generated prompt into your LLM agent — for example Claude Code with orchstep-workflow-design installed — and it designs the workflow for you, from your actual codebase, with error handling and assertions included:

orchstep-mcp-integration

Teaches agents how to use the OrchStep MCP server. Covers:

• Starting the MCP server (orchstep mcp serve)
• Available tools (run, list_tasks, lint, module_search, module_install, workflow_generate, version)
• Tool parameters, response formats, and error codes
• Usage patterns (discover-and-run, validate-before-running, module-based, generate-and-execute)
• Client configuration for Claude Desktop and generic MCP clients

Use when: Building AI-powered automation that orchestrates workflows, manages modules, or generates workflow definitions.

orchstep-module-creation

Teaches agents how to create reusable OrchStep modules. Covers:

• Module structure (orchstep-module.yml + orchstep.yml)
• Module metadata (name, version, description, author, license)
• Config schema (required/optional parameters with types, defaults, validation)
• Exported tasks and dependencies
• Versioning with semver
• Publishing and distribution via Git
• Module patterns (infrastructure, notification, testing)

Use when: Packaging deployment patterns, operational runbooks, or infrastructure automation for distribution.

orchstep-capture

Captures the work done in a Claude Code session and converts it into a clean, replayable OrchStep YAML workflow with variable extraction.

• Analyzes the agent's session history (shell commands, file edits, HTTP calls, git operations) to identify the task's goal, key actions, and verification steps
• Skips noise (ls, cd, failed retries) — only the real work survives
• Extracts hardcoded values into {{ vars.X }} placeholders for reusability
• Generates an envrioment template file alongside the workflow
• Modes: smart capture (auto-deduplicates, classifies functions) or --raw (faithful transcript)
• Output: workflows/<name>.yml and workflows/<name>.env

Supports /orchstep-capture <name> [description] invocation. The captured workflow can be replayed later with orchstep run or used as a regression test that other agents can re-run to verify the behavior still works.

Use when: A multi-step task was just completed in an LLM session (deploy, debug, refactor, data pipeline, infra change) and the result should be saved as a replayable workflow. Trigger phrases: "capture this", "save this as a workflow", "make this replayable".

How Skills Work

Skills are loaded by LLM agents as context when they need to perform OrchStep-related tasks. The skill document provides:

1. Quick reference -- concise syntax reminders for common operations
2. Complete API -- all parameters, return values, and options
3. Patterns -- proven workflows for common scenarios (deploy pipelines, CI/CD, etc.)
4. Anti-patterns -- common mistakes to avoid

Skill Integration

Skills are distributed in the orchstep repository under the skills/ directory. Any LLM agent framework that supports skill/instruction loading can use them.

Each skill follows a standard format:

---
name: skill-name
description: When to use this skill
---

# Skill Title

Structured instructions and reference material...