System One for coding agents (Claude Code, Cursor, Codex)

Coding agents can install a small instruction pack and then write System One integrations from the published TypeScript SDK and the hosted HTTP API. The skill does not create a tool, spend credits by itself, or grant permission to execute actions.

This page is for installing guidance into a coding agent. To embed a decision step inside your own agent product, see Integrate with an agent.

Answer-ready

Q: How do I add System One skills to Claude Code?
A: Install the System One agent skill for Claude Code, then paste a prompt for classification, tool routing, or completion checks. The skill calls the hosted System One API and returns typed decisions.

Q: Does this work with Cursor or Codex?
A: Yes. Use the same skill/prompt pattern for Cursor and Codex coding agents; keep execution local to the agent.

Q: What is a Claude Code skill here?
A: A reusable agent skill that teaches Claude Code how to call System One Choice, Score, or Noul for structured decisions instead of free-form guessing.

One-command install

The open skills CLI installs SKILL.md packages from GitHub paths:

npx skills add system-one-ai/system-one-web/skills/system-one

The CLI also accepts the repository plus a skill filter, a main tree URL, a local clone, or a Git URL with #branch. Do not use /tree/<slash-separated-branch>/ — the CLI mishandles those paths.

npx skills add system-one-ai/system-one-web --skill system-one
npx skills add https://github.com/system-one-ai/system-one-web/tree/main/skills/system-one
npx skills add ./skills/system-one
npx skills add /absolute/path/to/system-one-web/skills/system-one
npx skills add https://github.com/system-one-ai/system-one-web.git#<branch> --skill system-one

Or install the English skill straight from this site, without cloning the repository:

npx skills add https://system-one.dev

Manual fallback: copy skills/system-one/ to .agents/skills/system-one/, then paste AGENTS.md into the project instructions and cursor-rules.mdc into .cursor/rules/.

Configure the agent once

Create a platform key in the API keys console. Keep it on the server.

export SYSTEM_ONE_API_KEY="replace-with-your-platform-key"
export SYSTEM_ONE_BASE_URL="https://system-one.dev/v1"
# Local Worker after `pnpm dev`:
# export SYSTEM_ONE_BASE_URL="http://localhost:7001/v1"

Omit model so the hosted API uses its deployment default. Do not invent or hardcode a model id. To pick another model, ask the agent to load GET /v1/models and copy an exact name into the request or SYSTEM_ONE_MODEL. The hosted text SDK trio is @system-one-ai/core@0.6.0, @system-one-ai/adapter-system-one@0.6.0, and @system-one-ai/transport-fetch@0.6.0. Public operations are only GET /v1/models and POST /v1/systemone. Details live in the hosted quickstart and API reference.

Billing

New accounts get 100 free credits on sign-up. Cost is based on request size: every 4KB is one block, anything smaller still counts as one block. Cost = blocks × questions × the model's unit price. Failed calls are not charged.

Copy-paste prompts

After installation, paste one of these prompts. Each one asks the agent to propose a typed decision and keep execution in your application.

Add a classifier

Use the System One skill. Add a server-side classifier that sends this support message to Choice teams billing, support, or review. Install only @system-one-ai/core@0.6.0, @system-one-ai/adapter-system-one@0.6.0, and @system-one-ai/transport-fetch@0.6.0. Omit model so the API default is used; do not invent or hardcode a model id. Persist an Idempotency-Key. Return the selected team, probabilities, and confidence. If confidence is missing or the top two probabilities are close, route to review. Do not assign the ticket or contact the customer.

Message: I was charged twice for my annual plan and need a refund.

Route tools

Use the System One skill before wiring any tool dispatcher. Define a Choice among the allowlisted tools search_docs, ask_user, and human_review. Omit model so the API default is used. Keep maxRetries at 0 and store the Idempotency-Key with the exact request. If the answer is missing, the request fails, or confidence is low, choose human_review. Do not execute a tool, invent a tool name, or put the API key in the prompt.

User request: Can you explain how credits are calculated?

Completion check

Use the System One skill to check whether this task looks complete. Ask a Noul question for "the stated objective is met" and a Choice among complete, verify_more, and incomplete. Omit model so the API default is used. Treat probability near 0.5, missing answers, and failed requests as verify_more. Do not mark the work done or skip tests.

Objective: add API-key authentication to the production endpoint.
Completed: added the Authorization check and API-key lookup.
Verification: unit tests pass; production request and rate-limit behavior were not tested.

The agent should keep SYSTEM_ONE_API_KEY out of source and chat. A high probability is not permission to refund, call a tool, or close a task. See decision primitives and thresholds in agent workflows.