# Skill para agentes

> Lo que carga tu agente de código antes de escribir contra esta API

Si la integración la escribe un agente de código (Claude Code, Cursor, Codex y otros),
hay una skill que le da el contrato de esta API y las condiciones de parada que un CFE
necesita. Es un derivado de esta documentación, no un reemplazo: lo que leés acá es lo
que el agente lee allá, en un formato que puede cargar por partes.

## Instalación

### Claude Code

Como plugin, que es la forma que se mantiene actualizada sola:

```
/plugin marketplace add pymouy/skills
/plugin install gateway@pymo
```

### Cursor, Codex y otros

```bash
npx skills add pymouy/skills
```

El CLI detecta los agentes que tenés instalados y te deja elegir a cuáles agregarla.

### A mano

Copiar el directorio `skills/gateway/` a `.claude/skills/` de tu proyecto, o donde tu
agente lea sus skills.

<Warning>
Una copia a mano no se actualiza sola, y esta skill cambia cuando cambia la API. Una copia
vieja no queda incompleta: queda describiendo una API que ya cambió, con la misma
seguridad con la que describía la anterior.
</Warning>

## Qué carga tu agente, y cuándo

La skill está partida en niveles para que el agente cargue sólo lo que la tarea pide.

| Nivel | Qué es | Cuándo lo carga |
|---|---|---|
| `SKILL.md` | Las reglas fiscales, las condiciones de parada y el ruteo hacia el resto | Entero, apenas la tarea nombra a pymo o a esta API |
| `referencias/*.md` | Una guía por pregunta: ambientes y sesión, emisión, estado y webhooks, recepción, contenido fiscal, salida del comprobante | Sólo la que corresponde a lo que está haciendo |
| `referencias/contrato.openapi.json` | Los esquemas exactos de cada request y cada respuesta | Cuando necesita el detalle de un cuerpo, buscando la operación |

Vienen también `fixtures/`, con ejemplos de request y de código, y `scripts/validar.mjs`,
un validador offline y sin dependencias (Node 18+) que revisa un cuerpo de request, o el
código de una integración, antes de que salga.

## Qué decide la skill y qué no

Un CFE no es un registro de API reversible. Es un documento fiscal: consume un número de
CAE que no vuelve, no se borra, y un comprobante mal emitido sólo se compensa con otro
comprobante. La skill está escrita para eso, así que no está optimizada para terminar
sola sino para terminar bien.

**Sí decide** cómo se autentica, qué endpoint corresponde, qué forma tiene el request,
cómo se lee la respuesta, cómo se reintenta y cómo se reconcilia el estado final.

**No decide** qué tipo de CFE corresponde a una operación, qué tratamiento fiscal lleva
una línea, si corresponde una nota de crédito o una anulación, ni cuándo se puede emitir
en contingencia. Eso es del régimen fiscal y del contador de la empresa.

Donde falta un dato fiscal, la skill le indica al agente que frene y pregunte, no que
complete el campo con algo plausible. Es la misma regla de la [Introducción](/), dicha
como condición de parada, porque a un agente al que se le pide que la factura salga hay
que decírsela así.

## Qué cubre, y qué queda afuera

La skill nombra las mismas operaciones que la [Referencia de la API](/api-reference), no
un subconjunto: si un endpoint está publicado acá, la skill lo conoce. Dos de ellos,
`createCreditNote` y `createDebitNote`, se publican con un cartel de **Beta**, y eso vale
igual para el agente: la forma del request o de la respuesta puede cambiar.

Lo que la skill sí recorta es prosa, no endpoints. Un par de secciones de estas guías
salen resumidas en la versión que carga el agente, porque el detalle largo es para leer
y no para decidir con él.

## Cómo se mantiene

`SKILL.md` y `referencias/` se generan desde el mismo contrato que la
[Referencia de la API](/api-reference) y desde esta misma documentación; no se editan a
mano, así que cambian cuando cambia la API.

Si algo de la skill contradice a la API, es un error nuestro: abrí un issue.