> 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 self-improving agent

Build an outer improvement loop where a scheduled agent reviews past runs, learns from team corrections, and proposes skill file updates — so your factory gets better over time.

A self-improving agent is the outer loop of the [software factory](/guides/agent-workflows/set-up-a-software-factory) you’ve built in the previous guides. It watches how maintainers correct the inner-loop agents — relabeled issues, edited comments, changed code — and opens a pull request to improve the skill files that drive those agents. Every correction from a teammate becomes a proposed improvement to the factory.

This guide shows how to build the outer loop for a triage agent. The same pattern applies to any agent role.

Note

The outer loop proposes improvements; it doesn’t apply them silently. Every change to a skill file goes through a normal pull request review before merging. The team decides what improves; the agent proposes it.

## Prerequisites

-   A working inner loop with at least one agent running ([set up your software factory](/guides/agent-workflows/set-up-a-software-factory))
-   A Warp account ([sign up at warp.dev](https://www.warp.dev))
-   An Oz cloud environment with access to your repository ([create one](/agent-platform/cloud-agents/environments))

## Why principles beat rules

Most agent skills start as a list of rules: “if the reporter doesn’t include a reproduction step, add `needs-info`.” Rules overfit. They break when a situation arrives that the rules didn’t anticipate, and a longer rule list makes the skill harder to maintain.

Effective skill files describe **principles**: durable ideas about how to approach a class of situation. A principle — “confirm that a bug report includes enough context for a fresh contributor to reproduce the issue” — transfers to situations the original rules didn’t cover. When the outer loop proposes a skill update, it should always aim for a principle that generalizes, not a new rule that handles one more edge case.

## 1\. Collect correction signals

The outer loop needs signals that the inner loop got something wrong. For a triage agent, the most useful signals are:

-   **Maintainer relabels** — A maintainer changes a label the triage agent applied (for example, `needs-info` → `ready-to-implement`).
-   **Maintainer re-opens** — A maintainer reopens an issue the triage agent closed.
-   **Follow-up comments** — A maintainer explains in a comment why the triage agent’s assessment was wrong.

GitHub captures all of these in the issue timeline and audit log.

The [`update-triage`](https://github.com/warpdotdev/oz-for-oss/blob/main/.agents/skills/update-triage/SKILL.md) skill in `warpdotdev/oz-for-oss` includes a Python helper script (`aggregate_triage_feedback.py`) that collects these signals for the past N days. Copy and adapt it for your repository.

## 2\. Create the update skill

1.  Create `.agents/skills/update-triage/SKILL.md` with the following content as a starting point:
    
    ```
    ---name: update-triagedescription: Review recent maintainer corrections to the triage agent's output and propose skill file updates that generalize from those corrections.---
    # Update triage skill
    You are reviewing recent maintainer corrections to the triage agent's output.
    ## What to look for
    For each correction:1. Identify what the triage agent did (the original label or comment).2. Identify what the maintainer did instead (the correction).3. Ask: why would the triage agent have gotten this wrong?4. Ask: what principle would prevent this class of error in the future?
    ## What to update
    Update only the triage-issue-local companion skill for this repository.Write principles, not rules. Do not update the shared triage-issue skill.
    Commit changes to a branch named oz-agent/update-triage.Do not push directly to main. Open a pull request for human review.
    ```
    
2.  For the complete implementation — including the correction-collection script, write-surface restrictions, and PR-opening workflow — use the [`update-triage` skill from `warpdotdev/oz-for-oss`](https://github.com/warpdotdev/oz-for-oss/blob/main/.agents/skills/update-triage/SKILL.md) as your reference.
    

## 3\. Schedule the outer loop

Weekly is a good starting cadence: it processes the previous week’s corrections and opens PRs for review at the start of the week.

1.  Create a scheduled cloud agent from the Oz CLI:
    
    ```
    oz schedule create \  --name update-triage-weekly \  --skill update-triage \  --environment YOUR_ENVIRONMENT_SLUG \  --cron "0 9 * * 1"
    ```
    
    Or, from the Oz web app: open **Agents** > **Schedules**, click **New schedule**, and set the skill, environment, and cron expression.
    
2.  Replace `YOUR_ENVIRONMENT_SLUG` with the slug of your Oz environment.
    

See [Scheduled agents](/agent-platform/cloud-agents/triggers/scheduled-agents) for the full reference.

## 4\. Review the proposed skill changes

Each time the outer loop runs, it opens a pull request with proposed changes to the `triage-issue-local` companion skill. Review that PR the same way you would review any other code change:

-   Does the proposed principle generalize correctly, or is it another specific rule in disguise?
-   Is the change scoped to the companion skill rather than the shared base skill?
-   Does it improve the agent’s reasoning, or does it just patch one edge case?

Merge the PR when the improvement is sound. Close it if the proposal is too narrow or incorrect.

Over time, the companion skill accumulates a clear description of how your team thinks about issue triage — not as a list of rules, but as a set of principles that a new maintainer or a new agent can learn from.

## Productivity tips

-   **Give feedback in the right place** — The outer loop collects signals from GitHub. If you want the triage agent to learn from a correction, add a comment to the issue explaining why the original label was wrong. That comment becomes signal for the next outer-loop run.
-   **Apply the pattern to other agent roles** — The [`update-pr-review`](https://github.com/warpdotdev/oz-for-oss/blob/main/.agents/skills/update-pr-review/SKILL.md) and [`update-dedupe`](https://github.com/warpdotdev/oz-for-oss/blob/main/.agents/skills/update-dedupe/SKILL.md) skills from `warpdotdev/oz-for-oss` apply the same outer-loop pattern to the PR reviewer and deduplication agents.
-   **Don’t skip the PR review** — The value of the outer loop is compounding improvement, not speed. A bad skill change that merges silently creates more work than it saves. Every proposed change should get a review.

## Next steps

-   [What is a software factory?](/agent-platform/cloud-agents/software-factory) — How the outer improvement loop fits into the full factory model.
-   [Set up your software factory: from triage to PR](/guides/agent-workflows/set-up-a-software-factory) — The inner loop the outer loop improves.
-   [Run a software factory in the cloud](/guides/agent-workflows/run-a-software-factory-in-the-cloud) — Move the loop to Oz for team-wide visibility.
-   [Scheduled agents](/agent-platform/cloud-agents/triggers/scheduled-agents) — Full reference for running cloud agents on a cadence.
-   [`warpdotdev/oz-for-oss`](https://github.com/warpdotdev/oz-for-oss) — The complete reference implementation including all outer-loop skills.
-   [Skills](/agent-platform/capabilities/skills) — How skill files work in Warp and Oz.