> ## Documentation Index
> Fetch the complete documentation index at: https://gotrebol.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrar Trébol desde tu editor con IA

> Instala el skill oficial de Trébol en Claude Code, Cursor, Codex y otros editores con IA para integrar más rápido.

Si usas un editor con IA para programar (Claude Code, Cursor, Codex, GitHub Copilot, Windsurf y otros), instala el skill oficial de Trébol. Le da a tu editor conocimiento embebido de nuestra API: autenticación, endpoints, items, account-flows, webhooks y errores comunes. Así te ayuda a integrar más rápido.

Después de instalarlo, le puedes preguntar cosas como:

* *"¿Cómo creo una verificación KYB (Know Your Business) para una empresa mexicana con RFC ABC123456Z0Y?"*
* *"¿Cómo configuro un webhook para que me notifique cuando una verificación se crea y cuando se finaliza?"*
* *"¿Cómo leo los resultados de una verificación cuando ya está completa?"*

Y obtienes respuestas con código listo para pegar, sin abrir el navegador.

## Prerequisitos

* Tener uno de los editores soportados por [skills.sh](https://www.skills.sh) instalado (Claude Code, Cursor, Codex, GitHub Copilot, Windsurf, Gemini, Cline y más)
* Tener `node` disponible para correr `npx`
* Una [API key de Trébol](/guia-devs/gestion-api-keys) (para ejecutar los ejemplos que el skill genere)
* Conocer la [URL base y autenticación](/guia-devs/conectarse) de la API

## Instalación

<Steps>
  <Step title="Instalar el skill">
    En tu terminal, ejecuta:

    ```bash theme={"dark"}
    npx skills add gotrebol/skills
    ```

    [skills.sh](https://www.skills.sh) detecta automáticamente qué editor con IA usas y configura el skill en la ruta correcta. No requiere configuración manual.
  </Step>

  <Step title="Probar">
    Abre tu editor con IA en una conversación nueva y pregunta:

    > ¿Cómo creo una verificación KYB para una empresa mexicana?

    El asistente debe responder con código y endpoints específicos de la API de Trébol. Si responde genérico, revisa [Solución de problemas](#solucion-de-problemas).
  </Step>
</Steps>

## Qué incluye

<CardGroup cols={2}>
  <Card title="Autenticación" icon="key" href="/guia-devs/conectarse">
    Header `x-api-key`, gestión de keys, rotación.
  </Card>

  <Card title="Casos de uso" icon="route" href="/guia-devs/crear-verificaciones/via-api/crear-verificacion">
    KYB (México, Colombia, EEUU), hipotecas y nómina. Creación de verificaciones vía API y vía widget, más webhooks.
  </Card>

  <Card title="Referencia de errores" icon="triangle-exclamation" href="/guia-devs/errores">
    Errores comunes, códigos de respuesta y troubleshooting de integración.
  </Card>

  <Card title="OpenAPI completo" icon="file-code" href="/api-reference/intro">
    Especificación oficial de la API para consultas detalladas de schemas.
  </Card>
</CardGroup>

## Cómo funciona

El skill es un conjunto de archivos markdown y un snapshot de OpenAPI. Tu editor con IA los lee bajo demanda cuando le preguntas sobre Trébol. Vive localmente en tu máquina, gestionado por la CLI de [skills.sh](https://www.skills.sh).

<Note>
  **Privacidad.** El skill no envía datos a Trébol. No abre conexiones, no telemetría, no analítica. Es contenido estático que tu asistente consulta localmente. Lo único que sale de tu máquina son las llamadas que tú decidas hacer a `api.gotrebol.com` con tu propia API key.
</Note>

## Mantener el skill actualizado

Publicamos mejoras al skill frecuentemente. Para traer la última versión:

```bash theme={"dark"}
npx skills update
```

Este comando actualiza **todos** los skills que tengas instalados vía skills.sh — no solo el de Trébol.

<Tip>
  **Recordatorio automático.** El skill incluye una regla de auto-frescura: si pasaron más de 30 días desde su última actualización, tu asistente con IA te recordará correr `npx skills update` al final de sus respuestas sobre Trébol.
</Tip>

Después de actualizar, puedes preguntarle al asistente *"¿qué cambió en la última versión del skill de Trébol?"* y resumirá los cambios recientes del [CHANGELOG público](https://github.com/gotrebol/skills/blob/main/skills/trebol/CHANGELOG.md).

<Accordion title="Auto-update verdadero (solo Claude Code)">
  Si usas Claude Code y quieres que el skill se actualice automáticamente cada vez que abres una sesión (sin tener que correr `npx skills update` manualmente), agrega este hook en tu `~/.claude/settings.json`:

  ```json theme={"dark"}
  {
    "hooks": {
      "SessionStart": [
        {
          "matcher": "startup",
          "hooks": [
            {
              "type": "command",
              "command": "npx skills update",
              "statusMessage": "Actualizando skills de Trébol...",
              "timeout": 60
            }
          ]
        }
      ]
    }
  }
  ```

  Esto actualiza **todos** los skills instalados vía skills.sh cada vez que abres Claude Code. Costo: \~2-5 segundos extra al inicio de cada sesión.

  > Esta opción es solo para Claude Code. Cursor, Codex y otros editores con IA no tienen hooks equivalentes. Para ellos sigue funcionando el recordatorio automático del propio skill cuando pasan >30 días sin actualizar.
</Accordion>

### Auditar el contenido del skill

Si tu equipo de seguridad necesita revisar el contenido antes de aprobar la instalación, los archivos viven en el repo público:

[github.com/gotrebol/skills/tree/main/skills/trebol](https://github.com/gotrebol/skills/tree/main/skills/trebol)

Estructura:

```text theme={"dark"}
gotrebol/skills/                  ← repo público
└── skills/
    └── trebol/
        ├── SKILL.md
        ├── CHANGELOG.md
        ├── auth.md
        ├── flows/
        │   ├── kyb-mexico.md       # walk-through detallado
        │   ├── kyb-colombia.md     # stub: items + tips
        │   ├── kyb-eeuu.md         # stub: items + tips (Beta)
        │   ├── hipotecas.md        # stub: items + tips (Beta)
        │   ├── nomina.md           # stub: items + tips (Beta)
        │   ├── webhooks.md
        │   └── widget.md
        └── reference/
            ├── endpoints.md
            ├── errors.md
            └── openapi.yaml
```

Todo es texto plano (markdown + YAML) y se puede revisar en GitHub sin instalar nada.

<h2 id="solucion-de-problemas">
  Solución de problemas
</h2>

<AccordionGroup>
  <Accordion title="El comando npx skills add no responde">
    Verifica que tienes `node` instalado (`node --version`). skills.sh requiere Node.js. Si el problema persiste, revisa [skills.sh](https://www.skills.sh) para confirmar que tu editor con IA está soportado.
  </Accordion>

  <Accordion title="El asistente responde genérico, no con información de Trébol">
    1. Confirma que el skill se instaló correctamente revisando que existe el directorio de skills de tu editor (Claude Code: `~/.claude/skills/`, Cursor: `~/.cursor/skills/`, etc.).
    2. Si tu pregunta no menciona Trébol explícitamente, el asistente podría no consultar el skill. Sé explícito ("usando el skill de Trébol, ...").
    3. Reinstala con `npx skills add gotrebol/skills` para forzar la configuración.
  </Accordion>

  <Accordion title="¿Cómo actualizo a la versión nueva?">
    Corre `npx skills update`. Este comando actualiza todos los skills instalados vía skills.sh a su última versión.

    Si quieres revisar qué cambió, consulta el [historial de commits en GitHub](https://github.com/gotrebol/skills/commits/main/skills/trebol) o el [CHANGELOG](https://github.com/gotrebol/skills/blob/main/skills/trebol/CHANGELOG.md).
  </Accordion>

  <Accordion title="Configuración corporativa: ¿el skill escribe fuera de mi proyecto?">
    El skill vive en el directorio que tu editor con IA usa para gestionar skills (no en el directorio de tu proyecto). Si tu equipo de TI requiere instalaciones por proyecto o en rutas controladas, contacta a Trébol antes de adoptar el skill para coordinar una alternativa.
  </Accordion>

  <Accordion title="¿Funciona sin conexión a internet?">
    Sí, una vez instalado el skill funciona 100% offline. El contenido vive localmente. Solo necesitas conexión en estos casos:

    * Cuando lo instalas por primera vez con `npx skills add`
    * Cuando corres `npx skills update`
    * Cuando haces llamadas reales a `api.gotrebol.com`

    El último caso no es parte del skill, sino de la integración que estás construyendo.
  </Accordion>
</AccordionGroup>

## Desinstalar

```bash theme={"dark"}
npx skills remove trebol
```

<h2 id="soporte">
  Soporte
</h2>

Si encuentras un error o el skill no responde como esperas, repórtalo en el repo público del skill:

* **GitHub**: [github.com/gotrebol/skills/issues](https://github.com/gotrebol/skills/issues)
* **Email**: [help@gotrebol.com](mailto:help@gotrebol.com)