# Self-improvement

The `improve` extension teaches an agent how to turn "change how you
work" into a source change. The agent prepares a brief, a Cursor cloud
agent edits a checkout and opens a pull request, and the running agent
reports the verified PR for human review.

Durable behavior does not change until that source is merged and
deployed.

## Mount it

Mount Cloud agents with the agent's own repository allowlisted, then
mount `improve` with the source directory.

```ts
// bot/extensions/cloud.ts
import cursorCloudAgents from "@grok/agent-sdk/extensions/cursor-cloud-agents";

export default cursorCloudAgents({
  cloud: {
    repos: [
      {
        url: "https://github.com/acme/agents",
        startingRef: "main",
      },
    ],
    autoCreatePR: true,
  },
});
```

```ts
// bot/extensions/improve.ts
import improve from "@grok/agent-sdk/extensions/improve";

export default improve({
  repo: "https://github.com/acme/agents",
  path: "agents/concierge",
  ref: "main",
});
```

Mounted as `improve`, the extension contributes the
`improve__yourself` skill. It does not contribute a tool that can bypass
the normal repository workflow.

## Ask for one behavioral change

State the change, how to tell it worked, and what behavior must stay
fixed. The agent maps the request to instructions, a skill, a tool,
channel configuration, or the model setting before preparing the coding
brief.

> Improve yourself: stop opening incident replies with a summary.
> Start with the decision, keep the existing evidence bullets, and
> preserve every current eval.

The success criterion and freeze line keep the cloud agent from turning
a narrow behavior request into an unrelated refactor.

## Follow the source change

The agent launches one cloud agent on the configured repository and
ref. It reports the complete cloud-agent ID
and URL immediately, then checks the same run instead of launching
another agent for follow-up work.

When the cloud agent opens a pull request, the running agent reads the
result and the PR before reporting what changed and which checks passed.
The pull request, not the delegation transcript, is the durable
deliverable.

Use the [Cloud agents guide](/docs/guides/cloud-agents.md) for launch, status,
transcript, steering, and cancellation behavior.

## Review, merge, then deploy

The workflow stops at a pull request. A human reviews the diff and
decides whether to merge it; a separate deployment action decides when
the new behavior becomes live.

This separation gives each boundary a real control:

- Repository permissions limit who can push the branch.
- Branch protection and review policy govern the merge.
- Deployment authorization governs the running agent.

After deployment, repeat the original request or regression eval to
confirm the behavior changed without crossing the freeze line.

## Configure it

- `repo` is the source repository URL.
- `path` is the agent's repository-relative directory.
- `ref` is the deployed branch or ref that new branches and pull
  requests target; it defaults to `main`.
- `notes` adds tree-specific guidance to every coding brief, such as a
  required test command or PR convention.
- `deploy` tells the skill who deploys a merged change and when it
  becomes live.

`notes` and `deploy` insert prose into the contributed skill. They do
not run checks, merge a branch, or trigger a deployment.

Validation checks the URL and path shape. It does not prove the source
exists, matches the current deployment, or appears in the Cloud agents
repository allowlist, so keep those values aligned yourself.

## What the extension enforces

`improve__yourself` is model guidance for locating the change, writing a
brief, following repository rules, opening a PR, and reporting it. Rules
such as "never merge" are instructions, not framework-enforced
permissions.

Use repository and deployment controls for hard enforcement. The
extension provides a repeatable path through those controls; it does not
replace them.

## What's next

- [Cloud agents](/docs/guides/cloud-agents.md): delegation and steering
- [Build with a coding agent](/docs/building-with-agents.md): have an
  external coding agent edit the project directly
- [Extensions](/docs/reference/extensions.md): namespaces and overlays
- [Deployment](/docs/deployment.md): make a merged source change live
- [Evals](/docs/evals.md): protect the requested behavior before and after
  the change