Build a triage agent for your issue backlog

Learn how to build a triage agent using Oz that reviews each new GitHub issue for clarity, applies labels, and flags open questions before implementation begins. After completing the steps in this guide, you will have a working triage skill deployed as a GitHub Action — the first agent in your software factory.

Prerequisites

• A Warp account (sign up at warp.dev)
• A GitHub repository with Issues enabled
• An Oz cloud environment with access to your repository (create one)
• A Warp API key added to your CI secrets as WARP_API_KEY (create one)

1. Define your triage criteria

Before writing a skill, decide what your triage agent should do. A good triage agent answers three questions for every new issue:

1. Is the report clear enough to act on?
2. Is it a duplicate of an existing issue?
3. What label should it have?

Identify:

• The label taxonomy for your repository (e.g., bug, enhancement, ready-to-implement, needs-info, duplicate).
• Who owns each area of the codebase. This becomes your STAKEHOLDERS file.
• What makes an issue “ready to implement”: does it need a reproduction step, version number, or proposed approach?

You will encode these decisions in a skill file in the next step.

2. Create the triage skill

A skill is a markdown file that defines the agent’s behavior. It tells the agent what to analyze, how to classify results, and what to output.

1. Create a .agents/skills/triage-issue/ directory in your repository with a SKILL.md file.
2. Copy the triage-issue skill from warpdotdev/oz-for-oss into your repository. This is the production triage skill Warp uses for its own open source repository.
3. Adapt the skill for your repository:
   • Replace the label taxonomy with your labels.
   • Update the ownership section to reflect your codebase.
   • Adjust the definition of “ready to implement” to match your team’s requirements.
4. Create .github/issue-triage/config.json with your label taxonomy. See the config.json from warpdotdev/oz-for-oss for the format.

Write the skill file in terms of principles, not rules.

• A rule says “if the reporter doesn’t include a reproduction step, add needs-info.”
• A principle says “confirm that a bug report includes enough context for a fresh contributor to reproduce the issue.”

Principles transfer to situations the original rules didn’t cover; long rule lists overfit and become harder to maintain.

Tip

The bootstrap-issue-config skill from oz-for-oss can generate an initial config.json and STAKEHOLDERS file by analyzing your existing labels and CODEOWNERS file. Run it once when setting up a new repository.

3. Test the triage agent locally

Before deploying to GitHub Actions, test the triage agent against a real issue using the Oz CLI:

oz agent run \
  --skill .agents/skills/triage-issue \
  --prompt "Triage GitHub issue #ISSUE_NUMBER in OWNER/REPO" \
  --share

The --share flag generates a session link your team can use to inspect what the agent did. Review the session output: check that the labels and comments match what you would write manually. If something is wrong, refine the skill file and run again.

For the full reference of oz agent run flags, see the Oz CLI reference.

4. Deploy with GitHub Actions

Once the skill output looks correct, deploy it as a GitHub Action that triggers automatically when a new issue is opened.

1. Create .github/workflows/triage-issue.yml with the following content:

name: Triage new issues

on:
  issues:
    types: [opened]

permissions:
  issues: write

jobs:
  triage:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: warpdotdev/oz-agent-action@v1
        with:
          skill: triage-issue
          prompt: |
            Triage GitHub issue #${{ github.event.issue.number }} in ${{ github.repository }}.
            Issue title: ${{ github.event.issue.title }}
            Issue body: ${{ github.event.issue.body }}
          environment: YOUR_OZ_ENVIRONMENT_SLUG
          warp_api_key: ${{ secrets.WARP_API_KEY }}
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

2. Replace YOUR_OZ_ENVIRONMENT_SLUG with the slug of the Oz environment you created in the prerequisites.

3. Add WARP_API_KEY to your repository’s GitHub Actions secrets under Settings > Secrets and variables > Actions.

See GitHub Actions integration for the full setup guide for warpdotdev/oz-agent-action.

5. Review and improve

Watch the first few runs in the Oz web app to verify the agent is labeling and commenting correctly. When you disagree with the agent, e.g., when you relabel an issue or edit a comment, note the pattern. Patterns you see repeatedly are signals to update your skill file.

Add repo-specific context without forking the core skill by creating a triage-issue-local companion skill. This file specializes the base skill for your repository (your label taxonomy, ownership map, and definition of readiness) while keeping the shared skill stable. See the docs repo example for the companion skill pattern.

Next steps

• What is a software factory? — How the triage agent fits into the full development loop.
• Write product and tech specs with agents — Add the spec role once your backlog is well-triaged.
• Build a self-improving agent — Automate skill improvement based on your corrections.
• GitHub Actions integration — Full documentation for warpdotdev/oz-agent-action.
• Run agents unattended — Broader patterns for cloud agents triggered by external events.