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
Section titled “Install the skill”The repository is a Claude Code plugin marketplace. Add it, then install the plugin:
/plugin marketplace add zksecurity/zkao-sdk/plugin install zkao@zkaoAdd the repository as a plugin marketplace:
codex plugin marketplace add zksecurity/zkao-sdkInstall zkao from that marketplace in the desktop app’s Plugins directory.
The portable plugin uses the same skill as Claude Code.
Save the skill into your agent’s skills directory:
curl -fsSL https://docs.zkao.io/skill.md -o SKILL.mdAgents without a skills system can read the same URL as context.
Shell-based agents can use the CLI from the Quickstart.
Connect with MCP
Section titled “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
Section titled “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.
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
Section titled “Docs for agents”Every page on this site has a plain Markdown version for agents.
| URL | What it holds |
|---|---|
/llms.txt |
An index of the docs, following the llms.txt convention. |
/llms-full.txt |
All guides and API reference pages in one file. |
/llms-small.txt |
A shorter bundle of guides. |
.md pages |
One page as Markdown. Replace the trailing slash with .md. |
/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
Section titled “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.
-
Start the login. It prints a URL and a code, then exits.
Terminal window zkao login --no-wait --no-browser --project <projectId>--projectis optional. It preselects the project on the approval page. -
The agent gives the URL and code to you. You open the URL, check the code, pick the project, and approve.
-
The agent finishes the login.
Terminal window zkao login --resumeEach call returns at once.
Still waiting for approvalmeans try again later.Authorizedmeans 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.
For unattended agents, create a token by hand instead and pass it through ZKAO_API_TOKEN and ZKAO_PROJECT_ID. See Authentication.
Keeping the skill current
Section titled “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:
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.
