Agent Skills

Instala el Agent Skill setto-api para que Claude Code, Cursor o cualquier agente que lea AGENTS.md conozca los 38 endpoints de la API externa de SETTO (incluidas las escrituras de configuración de torneos, de cuadros, de resultados y de programación, y la «Actividad»), los flujos de configuración, cuadros y resultados, sus reglas de populate y sus códigos de error.

Un Agent Skill es una carpeta con un SKILL.md adentro: frontmatter YAML que dice para qué sirve el skill, y un cuerpo en Markdown que el agente carga cuando una tarea coincide. SETTO publica uno, setto-api, que le enseña a un agente toda la API externa — los 38 endpoints, cómo crear un torneo, inscribir equipos, sustituir a un jugador, dar de baja a un equipo, armar los grupos y el cuadro y cargar resultados, las listas blancas de populate, los códigos de error y la regla de "nunca imprimas el token" — sin que tengas que explicarlo cada vez.

Es la alternativa para todos los clientes que el servidor MCP no alcanza, y también es útil junto con MCP: el skill es lo que le dice a un agente cuándo las herramientas de SETTO son la jugada correcta.

Qué trae

El skill se sirve desde este sitio bajo /.well-known/skills/, con /skills/… como alias corto de los mismos archivos.

Archivo	Qué es
`setto-api/SKILL.md`	El skill en sí: cuándo usarlo, autenticación y los seis permisos, los 38 endpoints, el flujo de programación proponer → confirmar → aplicar, las reglas de las escrituras de configuración (leer primero, «Vista previa» → sí → aplicar, llaves de idempotencia, límites del plan) y de las de cuadros y resultados (vista previa → sí → aplicar, «Confirmar cuadro», el orden local/visitante de un resultado, `overwrite` solo con la palabra del organizador), populate, paginación, resultados de fútbol, errores, seguridad
`setto-api/references/endpoints.md`	Cada parámetro, campo del cuerpo y valor legal de `populate`, por endpoint, más el modelo de datos
`setto-api/references/errors.md`	Cada código de error, su causa y si reintentar ayuda
`setto-api/references/workflows.md`	«Crear torneo», «Inscribir parejas», «Sustituir jugador», «Baja de equipo», «Armar grupos / cuadro» y «Cargar resultados», paso a paso
`setto-api/cursor/setto-api.mdc`	El mismo material como regla de proyecto de Cursor
`setto-api/AGENTS.md`	Una sección lista para pegar en un `AGENTS.md` existente
`index.json`	Catálogo legible por máquina de los skills que publica este sitio

El frontmatter, si quieres ver la forma antes de instalar:

SKILL.md

---
name: setto-api
description: "Read SETTO tournament data (tournaments, divisions/categories, teams, rounds, games, standings), set tournaments up (create a tournament and its categories, register teams, substitute a player, withdraw a team), set up their groups and knockout draws (a category's format, its groups, the knockout draw and its confirmation), record or clear game results, and plan or set a tournament's game schedule through the SETTO External API …"
license: MIT
metadata:
  version: "1.7.0"
  docs: "https://docs.setto.io"
  openapi: "https://docs.setto.io/openapi.json"
  mcp: "https://docs.setto.io/mcp"
---

Instálalo

La CLI skills acepta una URL de descarga directa a un solo SKILL.md, que es lo que sirve este sitio:

npx skills add https://docs.setto.io/.well-known/skills/setto-api/SKILL.md

Por defecto se instala en el proyecto actual. Banderas útiles:

Bandera	Efecto
`-g`, `--global`	Instala en tu directorio de usuario en lugar del proyecto
`-a`, `--agent <agents...>`	Apunta a agentes específicos, por ejemplo `claude-code`, `codex`

Las demás fuentes que soporta la CLI son un atajo de GitHub (owner/repo), una URL completa de GitHub, GitLab o Azure Repos, cualquier URL de git, una ruta local y archivos comprimidos. El repositorio de SETTO es privado, así que la URL directa al SKILL.md de arriba es la que hay que usar.

Archivos de referencia

Instalar desde una sola URL de SKILL.md trae únicamente ese archivo. Agrega los tres archivos de referencia a mano si los quieres — mira la pestaña manual.

Deja el token fuera

El skill nunca contiene un token, y le dice al agente que lea uno de la variable de entorno SETTO_API_TOKEN y que nunca lo imprima, registre ni commitee. Déjalo así: no pegues tu token en SKILL.md, setto-api.mdc ni AGENTS.md — esos archivos se commitean.

Actualizar

No hay actualización automática. Vuelve a correr el comando de instalación para traer la versión actual; el archivo se sobrescribe limpio. metadata.version en el frontmatter te dice qué tienes — compáralo contra SKILL.md en este sitio. Los cambios rompedores de la API están en el registro de cambios.

Descubrirlo programáticamente

https://docs.setto.io/.well-known/skills/index.json lista lo que publica este sitio, para que una herramienta pueda encontrar el skill sin raspar la documentación:

/.well-known/skills/index.json

{
  "skills": [
    {
      "name": "setto-api",
      "description": "Read SETTO tournament data …",
      "files": [
        "SKILL.md",
        "references/endpoints.md",
        "references/errors.md",
        "references/workflows.md",
        "cursor/setto-api.mdc",
        "AGENTS.md"
      ]
    }
  ]
}

Cada entrada de files es relativa a /.well-known/skills/<name>/.

Relacionado

Servidor MCP — llamadas de herramienta reales en lugar de HTTP escrito a mano, donde el cliente lo soporte.
Documentación para LLMs — llms.txt, Markdown por página, /openapi.json.
Autenticación — de dónde sale el token que va en SETTO_API_TOKEN.