+++
title = "Bonsai agent skill"
description = "Teach Claude Code, or another coding agent, to manage clusters with the CLI."
weight = 121
updated = 2026-11-11

[extra]
nav_title = "Agent skill"
weight = 80
+++

The CLI ships with a skill that teaches a coding agent to manage your clusters with it. With the skill installed, you can ask for things like:

- "Create a sandbox cluster for this project and put its URL in `.env`."
- "How close is the `search` cluster to its plan's limits?"
- "What were the top search terms this week?"

The agent runs `bonsai` in your shell, with your token. Nothing else is installed, and nothing runs in the background.

## Claude Code

```bash
bonsai skill install
```

This writes a [Claude Code skill](https://docs.claude.com/en/docs/claude-code/skills) to `~/.claude/skills/bonsai/SKILL.md`, where every project can use it. Add `--project` to write it to `.claude/skills/` in the current folder instead, to commit it for your team:

```bash
bonsai skill install --project
```

Claude Code loads the skill on its own when a request is about a Bonsai cluster.

The skill is a copy, made when you ran the command. Run `bonsai skill install` again after you upgrade the CLI to bring it up to date. It says whether it installed the skill, updated it, or found it already up to date.

## Other agents

`bonsai skill print` prints the same text, for any agent that reads instructions from a file:

```bash
bonsai skill print >> AGENTS.md
```

## What the skill tells the agent

- **Run every command with `--json --no-input`**, so the agent reads the API's JSON and never hangs on a prompt.
- **Check `bonsai whoami` first.** If there's no valid token, it asks you to run `bonsai login` in your own terminal, or to set `BONSAI_TOKEN`. It's told never to ask for a token in the chat.
- **Which command does what**, for clusters, connection URLs, usage, metrics, top queries, Actions and the catalog, with `bonsai api` for anything else.
- **Confirm before changes that cost money.** Before `cluster create`, `cluster resize` and `cluster destroy`, the agent names the cluster, plan and region and asks you. It takes plan and region IDs from `bonsai plans` and `bonsai regions`, not from memory.
- **How Actions work**: how long the CLI waits, and how to pick a wait up again with `bonsai wait`.
- **Never show a password.** The agent writes a cluster's URL straight into a git-ignored env file with `bonsai cluster url <cluster> --write .env`, and never runs `cluster url` without `--write`. If the file isn't ignored by git, it asks you to add it to `.gitignore` instead of working around the refusal.
- **What the [exit codes](@/docs/cli/scripting/index.md#exit-codes) mean**, such as telling you when a payment method is needed.

Read it in full with `bonsai skill print`. For agents other than Claude Code, see [Use Bonsai with any coding agent](@/docs/agents/other-agents/index.md).

## Limits

The skill is instructions, not a sandbox. The agent can do whatever your token can, so:

- Log in with a token that has only the [scopes](@/docs/api/authentication/index.md#scopes) you want an agent to have. Without `clusters:write`, it can't create, resize or destroy anything.
- Top search terms are text your users typed. An agent reading them should treat them as data, never as instructions.

## Skill or MCP server?

Both give an agent the same abilities.

- The **skill** suits agents that can run shell commands, like Claude Code. The agent can combine `bonsai` with `jq` and your other tools.
- The [**MCP server**](@/docs/cli/mcp-server/index.md) suits clients that call tools instead of running a shell, like Claude Desktop. It has a read-only mode, and no tool ever returns a password.

You can use both: the skill tells the agent to prefer the MCP server's `write_cluster_url` tool when it's there.