# Build with a coding agent

Teach Claude Code, Codex, or Cursor to scaffold, deploy, run, and govern Tanomis agents with platform skills and a documentation MCP server, installed by one tanomis command.

Most Tanomis agents are written with a coding agent beside the developer. `tanomis` meets it
halfway: four skills that teach the agent how the platform works and how to drive `tanomis`, and a
documentation server that lets it search and read these docs as tools. Both ship inside the
`tanomis` binary, so they always match the commands your version has.

- One command installs everything: `tanomis skills install`.
- Skills go to `.claude/skills`, `.agents/skills`, and `.cursor/skills` at the root of your
  repository; the documentation server is registered in `.mcp.json` and `.cursor/mcp.json`.
- Every skill ends with a command reference rendered from your binary's own help text, so
  re-run the install after upgrading `tanomis`.
- Included in Tanomis v0.2.0 (first shipped as `cog` v0.1.1). `tanomis version` shows which
  you have, and the [installer](/getting-started/install) upgrades in place.

## Install the skills

From the root of the repository that holds your agents:

```bash
tanomis skills install
```

```text title="Output"
created    .claude/skills/tanomis-build-agent/SKILL.md
created    .claude/skills/tanomis-deploy-rollout/SKILL.md
created    .claude/skills/tanomis-govern/SKILL.md
created    .claude/skills/tanomis-run-debug/SKILL.md
created    .mcp.json
created    .agents/skills/tanomis-build-agent/SKILL.md
created    .agents/skills/tanomis-deploy-rollout/SKILL.md
created    .agents/skills/tanomis-govern/SKILL.md
created    .agents/skills/tanomis-run-debug/SKILL.md
created    .cursor/skills/tanomis-build-agent/SKILL.md
created    .cursor/skills/tanomis-deploy-rollout/SKILL.md
created    .cursor/skills/tanomis-govern/SKILL.md
created    .cursor/skills/tanomis-run-debug/SKILL.md
created    .cursor/mcp.json

To register the documentation server with Codex, add to ~/.codex/config.toml:
  [mcp_servers.tanomis-docs]
  command = "tanomis"
  args = ["docs", "serve"]
```

Commit the files: they are plain Markdown and JSON, and teammates who clone the repository get
the skills without running anything. Re-running the command is safe. A skill file that `tanomis`
wrote and nobody edited is updated in place; one you edited, or one `tanomis` did not write, is
left alone and listed, unless you pass `--force`.

| Agent | Repository scope (default) | User scope (`--scope user`) |
|---|---|---|
| Claude Code | `.claude/skills/` | `~/.claude/skills/` |
| Codex | `.agents/skills/` | `~/.codex/skills/` |
| Cursor | `.cursor/skills/` | `~/.cursor/skills/` |

Pick agents with `--agent claude,codex` (default `all`), or write into any directory with
`--dir`. `tanomis skills list` names the skills; `tanomis skills show deploy-rollout` prints one without
installing it. The full flags are on [`tanomis skills install`](/cli/skills/install).

## What the skills cover

| Skill | What the agent learns to do |
|---|---|
| `tanomis-build-agent` | Scaffold with `tanomis agent new`, write the entrypoint, declare models, tools, hosts, and limits in `agent.yaml`, run the contract test, dry-run the deploy. |
| `tanomis-deploy-rollout` | Dry-run on a branch, deploy to the sandbox tenant, read version status, canary to named customer tenants with `tanomis agent rollout`, roll back, deploy from CI with an automation client. |
| `tanomis-run-debug` | Start sessions and runs from the CLI, read events and the trace, tell a policy refusal from a failure in the agent, unblock a run waiting on an approval, attach files. |
| `tanomis-govern` | Add approvals to the right actions, narrow egress, set the authorization ceiling, declare connectors and allowed tools, manage agent access, read the audit trail for a run. |

Each skill is a workflow with a checkpoint per step, a table of what to do when a step fails,
and a command reference generated from `tanomis --help` at install time. Each also states what it
will not do:

- Never edit tenant policy to make a run pass.
- Never widen a ceiling, an egress list, or a permitted-tools list beyond what the task needs,
  and never without telling you which line changed and why.
- Never store a credential, token, or client secret in the repository, in `agent.yaml`, or in a
  skill file.

## The documentation server

`tanomis docs serve` is a Model Context Protocol server over standard input and output with three
tools: `search_docs`, `read_doc`, and `list_docs`. It serves this site, fetched as one file on
first use and cached under `~/.config/tanomis/docs-cache` (`--cache-dir` moves it); the copy is
revalidated when it is older than an hour and served from the cache when the site cannot be
reached. It runs locally, needs no credential, and serves nothing this site does not publish.

```bash
tanomis docs serve
```

The install registers it as `tanomis-docs` where the agent reads a JSON file, and prints what to
add or run where it does not:

| Agent | Registration |
|---|---|
| Claude Code, repository | Merged into `.mcp.json` |
| Claude Code, user | `claude mcp add --scope user tanomis-docs -- tanomis docs serve` |
| Cursor | Merged into `.cursor/mcp.json` or `~/.cursor/mcp.json` |
| Codex | `[mcp_servers.tanomis-docs]` in `~/.codex/config.toml`, printed by the install |

Pass `--no-mcp` to skip the registration. Point the server at another copy of the docs with
`--docs-url`, or ask the site for a fresh copy with `--refresh`; see
[`tanomis docs serve`](/cli/docs/serve).

## Where to go next

- [Quickstart](/getting-started/quickstart): the flow the skills automate.
- [`tanomis skills`](/cli/skills) and [`tanomis docs`](/cli/docs) in the CLI reference.
- [Docs for LLMs](/llms-full.txt): the same file the documentation server indexes.