# 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 "" --json`, compares the strong matches, and reviews the best one with `stacks show --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 --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 --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 ` 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.