> For the complete documentation index, see [llms.txt](/llms.txt).
> Markdown versions of each page are available by appending .md to any URL.

# Build a triage agent for your issue backlog

Create a triage agent that reviews new GitHub issues, applies labels, and flags open questions. Your backlog stays actionable without manual effort.

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](/agent-platform/cloud-agents/software-factory).

## Prerequisites

-   A Warp account ([sign up at warp.dev](https://www.warp.dev))
-   A GitHub repository with Issues enabled
-   An Oz cloud environment with access to your repository ([create one](/agent-platform/cloud-agents/environments))
-   A Warp API key added to your CI secrets as `WARP_API_KEY` ([create one](/reference/cli/api-keys))

## 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`](https://github.com/warpdotdev/oz-for-oss/blob/main/.agents/skills/triage-issue/SKILL.md) 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`](https://github.com/warpdotdev/oz-for-oss/blob/main/.github/issue-triage/config.json) 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`](https://github.com/warpdotdev/oz-for-oss/blob/main/.agents/skills/bootstrap-issue-config/SKILL.md) 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](/reference/cli/).

## 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](/agent-platform/cloud-agents/integrations/github-actions) for the full setup guide for `warpdotdev/oz-agent-action`.

## 5\. Review and improve

Watch the first few runs in the [Oz web app](https://oz.warp.dev) 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](https://github.com/warpdotdev/docs/blob/main/.agents/skills/triage-issue-local/SKILL.md) for the companion skill pattern.

## Next steps

-   [What is a software factory?](/agent-platform/cloud-agents/software-factory) — How the triage agent fits into the full development loop.
-   [Write product and tech specs with agents](/guides/agent-workflows/write-product-and-tech-specs-with-agents) — Add the spec role once your backlog is well-triaged.
-   [Build a self-improving agent](/guides/agent-workflows/build-a-self-improving-agent) — Automate skill improvement based on your corrections.
-   [GitHub Actions integration](/agent-platform/cloud-agents/integrations/github-actions) — Full documentation for `warpdotdev/oz-agent-action`.
-   [Run agents unattended](/guides/agent-workflows/how-to-run-unattended-agents) — Broader patterns for cloud agents triggered by external events.