# Build with a coding agent

Agent SDK projects live in files and expose structured CLI
commands. A coding agent can create the project, exercise its tools, run a
real turn, and inspect the result. You approve the plan and side effects while
the coding agent owns the edit-and-test loop.

This page covers a coding agent working inside a checkout. To let a
running agent propose changes to its own source, use the separate
[self-improvement extension](/docs/guides/improve.md).

## Create an agent from a goal

Give the coding agent a purpose and the surfaces people will use. The
`create-agent` skill asks only for missing decisions, shows a file plan,
then scaffolds and verifies a small first version.

> Use the Agent SDK create-agent skill to build a PR triage agent
> reachable through GitHub. It should summarize failed checks, post one
> review comment per pull request, and include one smoke eval.

Ask it to read
[`skills/create-agent/SKILL.md`](/docs/package/skills/create-agent/SKILL.md). The
first version should stay narrow: instructions, one or two tools, the
chosen channels or connections, and a smoke eval.

## Add one capability

For an existing project, name the user-visible outcome and point the
coding agent at the matching procedure. It should inspect the current
agent first, make the smallest change, then exercise the new path.

Examples:

> Add Slack mentions and DMs to this agent. Follow the setup-slack
> skill, keep replies in the source thread, and verify one local mention.

> Connect the private inventory MCP server with host OAuth. Keep its
> write tools behind a narrow server-tool wrapper.

> Add a GitHub ready-for-review trigger and replay PR 42 before posting
> anything live.

The companion skills live under `skills/`: [Slack](/docs/package/skills/setup-slack/SKILL.md),
[MCP OAuth](/docs/package/skills/mcp-auth/SKILL.md), and
[GitHub](/docs/package/skills/github/SKILL.md). Use the capability guide for the
reader experience and the skill for the coding procedure.

## Verify tools before tuning the prompt

Start with discovery, then call deterministic server tools without a
model turn. If a tool returns the wrong evidence, fix the tool before
changing instructions.

```text
agent-sdk validate --dir .
agent-sdk info --dir . --json

agent-sdk tool call inspect_pr --dir . \
  --input '{"prUrl":"https://github.com/acme/checkout/pull/42"}'
```

`validate` confirms the discovered project shape. `info` shows what the
serve host will mount. `tool call` runs the authored tool with schema
validation and exposes its real output.

## Verify one end-to-end turn

Once deterministic inputs are correct, send the same request a user
will. The coding agent should check the final answer and tool trajectory
before declaring the capability complete.

```text
agent-sdk run --dir . \
  --message "Is https://github.com/acme/checkout/pull/42 ready to approve?"
```

`run` prints the saved trace path. Use that exact path instead of
constructing one from the session ID:

```text
agent-sdk session get --file <trace-path-printed-by-run>
agent-sdk eval --dir . --tag smoke
```

Finish with the project's TypeScript check. Agent SDK executes
TypeScript through type stripping, so a successful turn does not prove
the project type-checks.

## Hand off credential-dependent checks

Project discovery, `info`, server-tool calls, and serve bring-up do not
need a model credential. Model turns and evals resolve
`CURSOR_API_KEY`, `CURSOR_API_KEY_FILE`,
`CURSOR_SERVICE_ACCOUNT_KEY`, then `agent-sdk login`.

When the coding environment has none, it should complete every key-free
check and hand you the exact remaining commands:

```text
agent-sdk run --dir . --message "<fixture prompt>"
agent-sdk serve --dir . --dev
agent-sdk eval --dir . --tag smoke
```

Missing access is a handoff boundary, not a reason to skip verification
or invent a substitute result.

## Improve a working agent

After one smoke turn passes, give the coding agent fixed fixtures, one
success criterion, and the behavior that must not change. The
hillclimb skill measures the current run, changes one lever, remeasures,
and adds an eval for every kept improvement.

> Hillclimb the PR triage agent on these two saved PRs. Reduce repeated
> reads without losing either gold finding. Keep the review JSON shape
> and all existing evals unchanged.

Ask it to read
[`skills/hillclimb/SKILL.md`](/docs/package/skills/hillclimb/SKILL.md). Keep
creation and improvement separate: a smoke turn proves the surface
works; a measured climb proves it works better on fixed inputs.

## Related

- [Early-alpha migration](/docs/guides/migrate.md): hand an architecture v1
  migration to `agent-sdk migrate` or the bundled coding-agent skill
- [Quickstart](/docs/quickstart.md): build the first agent manually
- [Evals](/docs/evals.md): protect behavior with regression cases
- [Hillclimbing](/docs/hillclimbing.md): run one measured improvement round
- [Self-improvement](/docs/guides/improve.md): let a running agent propose a
  source change through a pull request
- [CLI reference](/docs/reference/cli.md): command contracts and flags