Home
Botz Skills

Botz Skills

Governed Agent Skills and subagents from botz.ai, for Cursor, Claude Code, and Codex. The plugin connects your agent to the hosted botz.ai MCP server and ships the botz-mcp client skill. Your agent finds a skill for the task, downloads it as a compact CRUX document, pins it by permanent guid and version, and applies it. You just ask for the work.

Plugin version 0.2.2. The skill is authored in zotoio/botz-mcp; this plugin carries a copy.

Install

Client	Marketplace file	Install
Cursor	`.cursor-plugin/marketplace.json`	Add `zotoio/zoto-agents` as a marketplace, then install zoto-botz-skills.
Claude Code	`.claude-plugin/marketplace.json`	`/plugin marketplace add zotoio/zoto-agents`, then `/plugin install zoto-botz-skills@zoto-agents`
Codex	`.agents/plugins/marketplace.json`	`codex plugin marketplace add zotoio/zoto-agents`, then install from `/plugins`

Requirements: an MCP client that supports streamable HTTP and MCP OAuth. Nothing to install locally.

Connect & sign in

The plugin adds one MCP server, botz:

{
  "mcpServers": {
    "botz": { "url": "https://mcp.botz.ai/mcp" }
  }
}

The first time your client connects, it opens a browser window to sign in with OAuth. There are no tokens or environment variables to set, and the plugin stores no credentials. Claude Code reads the same entry from .mcp.json (with "type": "http").

What's included

Component	What it does
`skills/botz-mcp`	Client skill: search, download, pin, apply, and give feedback on skills and subagents.
`/z-botz-mcp`	Shortcut command that runs the skill with your request.
`mcp.json`, `.mcp.json`	The `botz` server entry for Cursor and Claude Code.

Usage

Ask for work as usual. When the agent needs a capability it doesn't have, the skill:

searches with skill_search (or agent_search for subagent roles),
downloads the match with skill_get / agent_get as a CRUX document,
records it in .botz/skills.lock.json, applies it, and reports back with skill_feedback.

If nothing fits, it sends a brief with skill_request. Creation is conversational, so the server may ask follow-up questions.

/z-botz-mcp find a skill for writing release notes
/z-botz-mcp check for skill updates

Pinning & updates

Zero drift: every skill you use is pinned by guid and version. Forks, combinations, and evolutions on the server never change what a pinned project receives.
Updates: once per session the skill calls skill_updates and tells you about enhancements, with the changelog.
Auto-accept: say "auto accept skill updates" to set "evolution": "auto" in the lockfile.

Self-hosted servers

To use your own botz-mcp deployment, override the botz entry's url in your project or user MCP config. IDE clients still sign in with GitHub OAuth; no token or header is needed.

Headless & CI

API keys are only for non-interactive callers (CI jobs, scripts, servers) that can't open a browser sign-in. An admin mints a bzt_ key in the botz management console at /admin → IAM · API tokens; store it as a CI secret and send it as an Authorization: Bearer header:

# placeholder only - read the key from your CI secret store
curl -sS https://mcp.botz.ai/mcp \
  -H "Authorization: Bearer $BOTZ_API_KEY" \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

See Headless & CI in the botz-mcp docs.

Troubleshooting

No skill_* tools: check the botz server is enabled and finish the browser sign-in.
Sign-in loops: remove the saved botz credentials in your client and reconnect.
Upgrading from 0.1.0: the old botz-mcp entry used BOTZ_MCP_URL and BOTZ_TOKEN; remove both. IDE clients need only the URL and GitHub sign-in.