Skip to content
Recipes Ecosystem Source Code Docs

Build a Custom Skill Workflow

Package a repeatable, multi-step workflow as an OpenCode Skill so the agent can run it on demand. Skills let you encode your best practices into a reusable, triggerable process.

When to use this recipe

  • You run the same multi-step workflow repeatedly.
  • You want the agent to follow your team’s exact process every time.
  • You want to share a workflow across projects or teammates.

Prerequisites

  • OpenCode installed.
  • A workflow you can describe as discrete steps.

Steps

  1. Decompose your workflow

    Write down the steps as you’d do them manually. This becomes the skill body.

    • Read the issue
    • Reproduce locally
    • Write a failing test
    • Implement the fix
    • Verify and open a PR draft

  2. Create the skill file

    Place a SKILL.md in your skills directory following the skill format.

    # Fix-and-PR

## When to use
Use when asked to fix a GitHub issue end to end.

## Steps
1. Read the issue and summarize the problem.
2. Reproduce it locally with a test.
3. Implement the minimal fix.
4. Run the full test suite.
5. Open a draft PR with a summary referencing the issue.

  3. Define the trigger

    Make clear when the skill should activate so the agent invokes it at the right moment.

  4. Test the skill

    Trigger it with a real issue and watch each step execute.

  5. Iterate

    Refine the wording until the agent reliably follows every step without prompting.

Key prompt

I have a recurring workflow: triage a GitHub issue, reproduce, fix, test, and open a PR. Write a SKILL.md that encodes this so you can run the whole flow when I give you an issue number.

Common pitfalls

  • Overly broad triggers: If the trigger is too loose, the skill fires when you don’t want it. Scope the “When to use” tightly.
  • Implicit steps: The agent skips anything not written down. Spell out every step, including verification.
  • Skipping the test phase: Always include a “verify” step, or the skill can ship incomplete work.

Next up