# AI agents

The zkao skill teaches an agent to drive a project through MCP, the CLI, or HTTP. It covers login, scopes, scans, triage, guidance, credits, and publishing. Claude Code and Codex plugins share the same skill and MCP connection.

An agent with the skill can handle requests like “enable formal verification on the main branch with a monthly budget of 500 credits” or “run a diff scan of this change”.

## Install the skill

Claude Code

The repository is a Claude Code plugin marketplace. Add it, then install the plugin:

```text
/plugin marketplace add zksecurity/zkao-sdk
/plugin install zkao@zkao
```

Codex

Add the repository as a plugin marketplace:

```bash
codex plugin marketplace add zksecurity/zkao-sdk
```

Install `zkao` from that marketplace in the desktop app’s Plugins directory. The portable plugin uses the same skill as Claude Code.

Other agents

Save the skill into your agent’s skills directory:

```bash
curl -fsSL https://docs.zkao.io/skill.md -o SKILL.md
```

Agents without a skills system can read the same URL as context.

Shell-based agents can use the CLI from the [Quickstart](https://docs.zkao.io/quickstart/).

## Connect with MCP

Add `https://zkao.io/api/mcp` as a remote MCP server in your client. It uses Streamable HTTP and OAuth. Follow the client’s sign-in flow to approve a project and its permissions. The plugin manifests configure this endpoint for Claude Code and Codex. You do not need to copy an API token into the plugin.

The connection belongs to one project. Use its identity tool to check the project before acting. CLI login and MCP authorization are separate. For staging, configure `https://staging.zkao.io/api/mcp` instead.

## Complete the review

After analysis finishes, the agent reads the scan’s `triage` completeness. A `COMPLETED` scan can still have unreviewed findings. Those findings are withheld from results.

When triage stopped on budget, the scan offers allowed resumption budgets. The agent can resume within the spending limit you authorized. It reuses the same request key and budget when retrying. It tracks the returned triage run, then checks the scan’s completeness again. See [Resume unfinished triage](https://docs.zkao.io/guides/scans/#resume-unfinished-triage).

For fixes, the agent reads the finding’s evidence and verifies the change with a scan or recheck. Further scans and triage require an authorized credit budget.

## Docs for agents

Every page on this site has a plain Markdown version for agents.

| URL                                                        | What it holds                                                                    |
| ---------------------------------------------------------- | -------------------------------------------------------------------------------- |
| [`/llms.txt`](https://docs.zkao.io/llms.txt)               | An index of the docs, following the [llms.txt](https://llmstxt.org/) convention. |
| [`/llms-full.txt`](https://docs.zkao.io/llms-full.txt)     | All guides and API reference pages in one file.                                  |
| [`/llms-small.txt`](https://docs.zkao.io/llms-small.txt)   | A shorter bundle of guides.                                                      |
| `.md` pages                                                | One page as Markdown. Replace the trailing slash with `.md`.                     |
| [`/openapi/v1.yaml`](https://docs.zkao.io/openapi/v1.yaml) | The full API contract.                                                           |

Each page also has a **Copy as Markdown** button next to its title.

Requests with `Accept: text/markdown` receive Markdown at the normal page URL.

## Logging in from an agent

A bare `zkao login` waits for browser approval for minutes. Most agent tool calls time out first. Split the login instead, so no command blocks.

1. Start the login. It prints a URL and a code, then exits.

   ```bash
   zkao login --no-wait --no-browser --project <projectId>
   ```

   `--project` is optional. It preselects the project on the approval page.

2. The agent gives the URL and code to you. You open the URL, check the code, pick the project, and approve.

3. The agent finishes the login.

   ```bash
   zkao login --resume
   ```

   Each call returns at once. `Still waiting for approval` means try again later. `Authorized` means the token is saved. Pass `--timeout <seconds>` to wait up to that long in one call.

You can approve several projects in one login. Each one gets its own saved token. `zkao config use <projectId>` switches between them.

Caution

Only approve a login you started. Approving mints a real API token for the project you pick. Revoke it any time under **Project Settings → Integrations**.

For unattended agents, create a token by hand instead and pass it through `ZKAO_API_TOKEN` and `ZKAO_PROJECT_ID`. See [Authentication](https://docs.zkao.io/authentication/).

## Keeping the skill current

The CLI checks npm for a newer release at most once a day. When one exists, every command prints a notice on stderr:

```text
zkao: version X.Y.Z is available (running A.B.C). Update with `npm install -g @zksecurity/zkao-cli`. If you are an agent working from a zkao skill file, update that too: it may describe fewer commands than the API now offers.
```

The notice never touches stdout, so piping output to `jq` keeps working. An agent that sees it should update the CLI and fetch the skill again. Set `ZKAO_NO_UPDATE_CHECK=1` to turn the check off.
