Agent Skills

Instala el Agent Skill setto-api para que Claude Code, Cursor o cualquier agente que lea AGENTS.md conozca los seis endpoints de la API externa de SETTO, 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 seis endpoints, 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, los seis endpoints con un curl cada uno, populate, paginación, errores, seguridad
`setto-api/references/endpoints.md`	Cada parámetro y cada 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/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) for one organization through the SETTO External API with an org API token. …"
license: MIT
metadata:
  version: "1.0.1"
  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 dos 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",
        "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.