DOC_INDEX
THEME
DOCS/LLM Agents/Skills

Skills

Skill documents for teaching LLM agents how to use OrchStep effectively

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.

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

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...
< MCP ServerShowcase >