System One para agentes de código

Los agentes de código pueden instalar un paquete breve de instrucciones y después escribir integraciones con System One usando el SDK de TypeScript publicado y la API HTTP alojada. El skill llama a la API System One alojada y devuelve decisiones tipadas (Choice, Score, Noul), pero la ejecución sigue siendo local: el skill no crea herramientas, no gasta créditos por sí solo y no concede permiso para ejecutar acciones.

Esta página sirve para instalar las instrucciones de integración en un agente de código. Si quieres incrustar un paso de decisión dentro de tu propio producto de agente, consulta Integración con agentes.

Preguntas frecuentes

Q: ¿Cómo añado skills de System One a Claude Code?
A: Instala el skill de agente System One y pega un prompt de clasificación, enrutamiento o finalización. El skill llama a la API System One y devuelve decisiones tipadas.

Q: ¿Funciona con Cursor o Codex?
A: Sí. Mismo patrón skill/prompt; la ejecución queda en el agente.

Q: ¿Qué es un Claude Code skill aquí?
A: Un skill reutilizable que enseña a Claude Code a usar Choice, Score o Noul en lugar de adivinar en texto libre.

Preguntas frecuentes

¿Cómo añado skills de System One a Claude Code?
Instala el skill de agente System One y pega un prompt de clasificación, enrutamiento o finalización. El skill llama a la API System One y devuelve decisiones tipadas.

¿Funciona con Cursor o Codex?
Sí. Mismo patrón skill/prompt; la ejecución queda en el agente.

¿Qué es un Claude Code skill aquí?
Un skill reutilizable que enseña a Claude Code a usar Choice, Score o Noul en lugar de adivinar en texto libre.

Instalación con un comando

El skills CLI instala paquetes SKILL.md desde rutas de GitHub:

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

La CLI también acepta el repositorio junto con un filtro de skill, un clon local o una URL de Git con #branch. No uses la forma /tree/<rama-con-barras>/, porque la CLI no maneja esas rutas.

npx skills add system-one-ai/system-one-web --skill 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

También puedes instalar el skill en inglés directamente desde este sitio, sin clonar el repositorio:

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

Alternativa manual: copia skills/system-one/ a .agents/skills/system-one/, y luego pega AGENTS.md en las instrucciones del proyecto y cursor-rules.mdc en .cursor/rules/.

Configura el agente una vez

Crea una clave de plataforma en la consola y mantenla en el servidor:

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"

Omite model para que la API alojada use su modelo por defecto. No inventes ni fijes un id de modelo. Para usar otro modelo, pide al agente que cargue GET /v1/models y copie un name exacto en la solicitud o en SYSTEM_ONE_MODEL. El trío de SDK de texto alojado es @system-one-ai/core@0.6.0, @system-one-ai/adapter-system-one@0.6.0 y @system-one-ai/transport-fetch@0.6.0. Las operaciones públicas son solo GET /v1/models y POST /v1/systemone. Los detalles están en la guía rápida y en la referencia de la API.

Prompts para pegar

Después de la instalación, pega uno de estos prompts. Cada uno pide al agente que proponga una decisión tipada y que la ejecución se quede en tu aplicación.

Añadir un clasificador

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.

Enrutar herramientas

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?

Comprobación de finalización

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.

El agente debe mantener SYSTEM_ONE_API_KEY fuera del código y de la conversación. Una probabilidad alta no es permiso para reembolsar, llamar a una herramienta ni cerrar una tarea. Consulta las primitivas de decisión y los umbrales en flujos de agente.

Modelos

Usa Clef Flash para gates rápidos, donde la decisión solo tiene que encajar en un flujo de agente. Usa Clairic para extracción de datos estructurados a partir de texto o imágenes. Ninguno de los dos exige que fijes un id a mano: si el prompt necesita nombrar el modelo, deja que el agente copie un name exacto de GET /v1/models. El catálogo de modelos es dinámico, por lo que los ids son opacos y pueden cambiar: consulta el directorio de modelos para comparar y saber cuándo cambiar de modelo.

Solución de problemas

• El comando de instalación falla con la ruta del repositorio. Usa el repositorio junto con el filtro de skill (npx skills add system-one-ai/system-one-web --skill system-one) o la alternativa manual copiando skills/system-one/ a .agents/skills/system-one/.
• El agente propone un id de modelo que no existe. Omite model y deja que la API alojada use su modelo por defecto, o copia un name exacto desde GET /v1/models.
• Faltan credenciales o la llamada falla. Comprueba que SYSTEM_ONE_API_KEY y SYSTEM_ONE_BASE_URL estén definidos en el entorno del proceso que hace la llamada, no en el prompt.
• La misma operación se ejecuta dos veces. Guarda un Idempotency-Key junto con la solicitud exacta y reutilízalo; los detalles están en idempotencia.
• El agente ejecuta la acción por su cuenta. La API System One devuelve una decisión estructurada; la ejecución y las comprobaciones de permisos se quedan en el runtime del agente.

Créditos

Las cuentas nuevas reciben 100 créditos al registrarse. Los créditos no caducan.

Para seguir: integración con agentes, elegir un modelo e idempotencia.