Build with a coding agent

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.

At a glance

• 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 upgrades in place.

Install the skills

From the root of the repository that holds your agents:

Terminal

tanomis skills install

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.

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.

Terminal

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.

Where to go next

• Quickstart: the flow the skills automate.
• tanomis skills and tanomis docs in the CLI reference.
• Docs for LLMs: the same file the documentation server indexes.