Teach an agent to author workflows

Ask a general-purpose agent to "write me a deploy pipeline" and you get plausible YAML. Plausible is the problem. It invents fields that don't exist, skips error handling because you didn't ask for it, and hardcodes values that should have been variables. You spend the next twenty minutes correcting syntax instead of reviewing logic.

The orchstep-workflow-design skill exists to close that gap. It teaches an agent how to author OrchStep workflows that actually lint — with the error handling, assertions, and rollback paths a production workflow needs, not just the happy path.

Two modes, depending on how much you know

The skill adapts to how concrete your request is.

Quick mode is for when you already know what you want — "write a deploy pipeline," "give me a CI workflow." The skill reads from nine bundled reference files covering syntax, functions, templates, variables, control flow, error handling, modules, stdin, and anti-patterns, then produces a complete workflow. No questions asked. It includes error handling, assertions, and rollback paths by default, because those are not optional in real automation.

Wizard mode is for the vague or exploratory ask — "help me design my CI pipeline." Here the skill asks two to four intent questions: what triggers it, how many environments, how complex, how much error tolerance, whether a human needs to approve anything. Then it produces a tailored workflow plus a design rationale explaining why each pattern was chosen. You learn the reasoning, not just the result.

There's also a deep dive mode for edge cases and version-specific behavior, which pulls real examples from the website source or from bundled annotated examples when you need the latest patterns.

What "production-grade" looks like

The difference between toy YAML and the kind the skill produces is mostly in the parts you didn't ask for but needed. Here is a pipeline with a real environment gate, a retry, and an assertion:

name: ci
defaults:
  tier: staging
tasks:
  pipeline:
    steps:
      - name: install
        func: shell
        do: echo "installing dependencies"
      - name: test
        func: shell
        do: echo "running tests"
        retry:
          max_attempts: 2
          interval: "2s"
      - name: gate
        if: '{{ eq vars.tier "production" }}'
        then:
          - name: scan
            func: shell
            do: echo "security scan"
        else:
          - name: skip
            func: shell
            do: echo "skipping scan on {{ vars.tier }}"
      - name: verify
        func: assert
        args:
          condition: '{{ ne vars.tier "" }}'
          message: "tier must be set"

Notice what the skill did without being told. The flaky test step has a retry. The production path runs a security scan that staging skips, via a real if/then/else. The whole thing ends with an assert that fails loudly if a required variable is missing. And it uses tier for the environment name — not env, which is a reserved word in OrchStep that the skill knows to avoid. That last detail is exactly the kind of thing a general agent gets wrong and a skill-equipped one gets right.

Why a skill beats a clever prompt

You could try to cram all of this into a system prompt. The skill is better for three reasons:

• It's grounded. Nine reference files mean the agent quotes verified syntax instead of pattern-matching from whatever YAML it saw in training. Wrong syntax is worse than no syntax.
• It's complete. Error handling, assertions, and rollback paths come standard. You review logic, not boilerplate.
• It's honest about intent. Wizard mode asks instead of assuming, so the workflow matches your actual constraints instead of a generic template.

The skill replaced the earlier orchstep-workflow-authoring skill with richer reference material and a smarter design flow — same idea, more reliable output.

Use it when

Reach for it when you're creating a new workflow, improving an existing one, or just learning the best way to model a process in OrchStep. It works equally well with "write this" and "help me design this." If you already have a hand-written workflow that lints and reads clearly, you don't need the skill — but the moment you're staring at a blank orchstep.yml, it's the fastest way to a correct one.

Where to go next

• Skills — the full orchstep-workflow-design description and modes
• Quick Start — your first workflow by hand
• Error Handling — the retry/catch/finally the skill defaults to

Staring at an empty orchstep.yml? Let the skill draft it, then review the logic instead of the syntax.