Use stacks with your agent

# Use stacks with your agent

> Install the stacks skill so your coding agent picks a stack, writes the project and loops on verify, and choose which agents a project is set up for.

This page installs the stacks skill, which lets your coding agent pick a stack, write the project and loop on verify from a request in chat. It also covers which agent `stacks new` launches and how to set a project up for more than one agent.

## When you need the skill

You need the skill when you want to start from a chat message such as "start me a Go CLI with tests and CI", because the agent has to know stacks exists.

You don't need it when you run `stacks new` at a terminal. stacks writes the project and starts your agent with one instruction, read `.stacks/BRIEF.md` and carry it out, and the brief is the whole task. The [Quickstart](https://stacks.steamfield.io/docs/quickstart.md#create-the-project) covers that path.

## Install the skill

The skill is one short Markdown file telling an agent when to reach for stacks and how to run it. Claude Code loads it automatically when a request matches its description.

```sh title="Terminal"
stacks skill install            # ~/.claude/skills/stacks/SKILL.md, for every project
stacks skill install --project  # .claude/skills/ in the current repository only
```

Running it again is safe. An identical file is left alone, and a copy you've edited is kept unless you add `--force`.

The agent doesn't need stacks installed globally. When `stacks` isn't on its PATH, the skill tells it to run `npx -y @steamfield/stacks@latest`, and every brief names the exact command to use for `verify`.

### Install the skill for other agents

Codex, OpenCode and Cursor read instructions from their own places. Print the skill and save it where your agent looks for skills or rules:

```sh title="Terminal"
stacks skill install --print > SKILL.md
```

An agent can also read `stacks guide`, which is what `stacks` prints with no arguments: a shorter version of the same instructions.

### Install the skill as a Claude Code plugin

The stacks repository is also a Claude Code plugin marketplace. Its plugin carries the stacks skill and the authoring skill, pinned to the latest release:

```sh title="Terminal"
claude plugin marketplace add steamfield/stacks
claude plugin install stacks@stacks
```

### Install the skill for writing your own stacks

A second skill, `stacks-author`, teaches an agent to turn a repository into a stack, design a new stack with you, and submit it to the public registry. The plugin includes it. Without the plugin, install it with `stacks skill install stacks-author`, or have any agent read it through `stacks guide author`. [Write your own stack or fragment](https://stacks.steamfield.io/docs/guides/authoring.md) covers the process.

## How the agent handles a project request

With the skill installed, ask your agent in your own words, for example "set up a TypeScript CLI properly". The agent then:

1. Runs `stacks search "<your words>" --json`, compares the strong matches, and reviews the best one with `stacks show <id> --json`.
2. Tells you which stack it picked, why, and one tradeoff. If nothing fits well, it says so and offers the closest entries from `stacks list --json`.
3. Runs `stacks new <stack> <dir> --json`. It adds `--sandbox` when you asked for the quickest local setup.
4. Reads `.stacks/BRIEF.md` and follows it, asking you only the decisions the brief says to ask.
5. Runs `stacks verify`, fixes what fails, and repeats until the outcome is `green`. Then it runs `stacks verify --all` and fixes anything that run turns up.
6. Works through the brief's after-green list (manual checks, docs) and summarizes: the stack, the decisions it took, anything left undone, and the problems it noted in `.stacks/NOTES.md`.

For a repository you already have, step 3 is `stacks add <fragment...> --json` instead, and the agent also merges the files `add` parked under `.stacks/incoming/`. [Add to an existing repository](https://stacks.steamfield.io/docs/guides/existing-repo.md) walks through it.

## Changes the agent needs your permission for

The agent never edits the verify steps or `.stacks/manifest.json`, and if verify reports `VerifyChanged` it stops and asks you. Only you can accept changed steps, by running `stacks verify --accept-changes` at your own terminal. stacks refuses that command when it detects an agent.

The agent also won't pick an untrusted entry (one from a project registry inside a repository, or from an unsigned custom index) unless you named it, and it confirms with you first if you did. [Registries and trust](https://stacks.steamfield.io/docs/concepts/registries-and-trust.md) explains which entries are trusted.

On a first run, stacks prints a short telemetry notice. The skill tells the agent to relay it to you once, including how to turn it off. An agent can turn telemetry off with `stacks telemetry disable`, but it can't turn it on: `stacks telemetry enable` needs a person at a terminal. The [telemetry page](https://stacks.steamfield.io/telemetry/) has the details.

## Agent output and exit codes

stacks detects an agent from markers such as `CLAUDECODE` or `AI_AGENT`, or because stdout isn't a terminal, and prints agent output: the same result as the human text with the progress and log noise removed. With `--json` the agent gets exactly one JSON object per command, and `stacks schema <name>` prints the JSON Schema for each.

When a command fails, the exit code tells the agent what to do next:

| Exit | The agent should |
| --- | --- |
| 0 | Continue. For `verify`, check the outcome: only `green` is done |
| 2 | Fix the input: a typo in an id, a bad flag, a non-empty target directory |
| 3 | Fix the configuration or the manifest |
| 4 | Retry later: an upstream service was unavailable |
| 5 | Read the verify report on stdout and fix what it names |
| 6 | Ask you: something needs a person's permission |
| 130 | Nothing; the run was interrupted |

[Output, JSON and exit codes](https://stacks.steamfield.io/docs/reference/output.md#exit-codes) has the full table and the error envelope.

## Which agent launches

At a terminal, `new` and `add` launch the first agent from your `agents` setting that's on your PATH. With none configured, a single installed agent launches without asking, and if several are installed you pick from a numbered list. The search order is Claude Code, Codex CLI, OpenCode, Cursor CLI, Copilot CLI, then the Codex app on macOS. Your pick isn't saved.

Choose explicitly with `--launch`, or skip launching with `--no-launch`:

```sh title="Terminal"
stacks new go-cli my-cli --launch codex
stacks new go-cli my-cli --no-launch
```

Nothing launches under `--json`, from inside an agent session, without a terminal, or for an untrusted entry. In those cases stacks prints the prompt for you to give your agent.

## Set up a project for more than one agent

`--agents` decides which agents' config files a project gets. It's separate from which agent launches. The default is `claude`; every target gets `AGENTS.md`.

```sh title="Terminal"
stacks new go-cli my-cli --agents claude,codex
```

To make that your default, set `"agents": ["claude", "codex"]` in `~/.config/stacks/config.json` ([Configuration](https://stacks.steamfield.io/docs/reference/configuration.md)).

The adapter files install guardrails, such as hooks that block destructive commands and writes that look like secrets, plus lint-on-write where the agent supports it. How much each agent enforces varies:

| Agent | What the adapter installs | Status |
| --- | --- | --- |
| Claude Code (`claude`) | Destructive-command and secret-write hooks, lint-on-write, format-on-stop; `CLAUDE.md` imports `AGENTS.md` | Proven in real agent runs |
| Codex (`codex`) | Bash and `apply_patch` guards once you trust the hooks, workspace-write sandbox, on-request approvals; lint and format are instructions | Proven in real agent runs |
| OpenCode (`opencode`) | Permission and plugin guards, lint-on-write, format-on-idle | Unproved: tested offline only |
| Cursor (`cursor`) | Shell and write guards before each tool call, always-applied rules; lint and format are instructions | Unproved: tested offline only |

> [!NOTE]
> Codex runs project hooks only after you review and trust them through `/hooks`. Until then, the guards are written but inactive.

When a guard blocks something, the agent should ask you rather than find another way around it.

## Next steps

- [Use stacks over MCP](https://stacks.steamfield.io/docs/mcp.md): for Claude Desktop and other clients without a shell.
- [Start a new project](https://stacks.steamfield.io/docs/guides/new-project.md): presets, fragments and decisions in a full project.
- [Verify: the definition of done](https://stacks.steamfield.io/docs/concepts/verify.md): what the agent is looping on.
- [Output, JSON and exit codes](https://stacks.steamfield.io/docs/reference/output.md): the contract scripts and agents parse.