Skill para agentes de IA

Si usted programa con la ayuda de un agente de código (Claude Code, por ejemplo), puede darle una skill que conoce la API de Facta y el SDK @facta-dte/api. Así el agente deja de adivinar métodos, campos o códigos de error: consulta lo que la skill trae, que sale del código del SDK, de sus guías y del contrato OpenAPI de esta misma documentación.

Una skill es una carpeta con un archivo SKILL.md que dice cuándo usarla, más archivos de referencia que el agente abre solo cuando los necesita. No es un programa ni se conecta a nada: son instrucciones y ejemplos.

Qué cubre

Tema	Lo que el agente aprende
Instalación y llaves	Qué abre cada una de las tres cadenas, por qué viven solo en el servidor, los ambientes 00 y 01 y la región.
Tipos de DTE	Factura, crédito fiscal, notas, exportación y sujeto excluido: qué receptor pide cada uno y si el precio lleva IVA.
Idempotencia	Una llave por operación de negocio, qué hacer ante un resultado incierto y el patrón de pedido a factura desde un webhook.
Contingencia, anulación y retorno	La contingencia es un éxito, la anulación no se deshace y el evento de retorno es otro documento.
Archivos y entrega	El Archivo DTE y el JSON original, el PDF, el ticket y el correo o WhatsApp en dos pasos con el token de cinco minutos.
Catálogo y almacenamiento	Los tres modos del catálogo, cuándo escribir y las copias de seguridad, incluida la salvaguarda de emergencia.
Errores y depuración	Cada `FactaErrorCode`, agrupado y con qué hacer, y cómo medir una llamada lenta.
Salir a producción	Una lista de verificación y los errores de integración más comunes.

Trae además cuatro plantillas listas para copiar —un servidor con Express, una ruta de Next.js, una pantalla de React y un webhook de pedido a factura— que se compilan contra el SDK en cada cambio del repositorio, y un índice de las recetas del playground, que son código real y probado.

Instalarla en Claude Code

Descargue el .zip (enlace abajo) o copie la carpeta skills/facta-dte-api/ del repositorio del SDK.
Deje la carpeta facta-dte-api donde Claude Code busca skills: en ~/.claude/skills/ para todos sus proyectos, o en .claude/skills/ dentro de un proyecto (súbala al repositorio si quiere que la use todo el equipo).

shPara todos sus proyectos

unzip facta-dte-api-skill.zip -d ~/.claude/skills/

shPara un solo proyecto

unzip facta-dte-api-skill.zip -d .claude/skills/

Abra una sesión nueva y pida lo que necesita, por ejemplo: «integra Facta DTE en este proyecto» o «emite un crédito fiscal con este pedido». Claude carga la skill a partir de su descripción.

Otros agentes

Cualquier agente que lea el formato de skills (SKILL.md con referencias) puede cargar la misma carpeta desde su propio directorio de skills. Si el suyo no lo admite, dele SKILL.md como contexto y que abra los archivos de references/ cuando SKILL.md se lo indique.

Dónde descargarla

Descargar la skill (.zip): el mismo archivo que ofrece el playground, donde además puede ver correr las recetas en el ambiente de pruebas.
Verla en GitHub: la carpeta skills/facta-dte-api/ del repositorio del SDK. Mientras la skill no llegue a la rama main, el enlace apunta a la rama dev.

Desde la versión 0.5.0 la skill también viaja dentro del paquete de npm: después de instalarlo la encuentra en node_modules/@facta-dte/api/skills/facta-dte-api/ y puede copiarla de ahí a la carpeta de skills de Claude Code.

Lo que no hace

No tiene llaves ni acceso a su cuenta. No emite nada por sí sola: ayuda a escribir el código que lo hace.
Cubre solo lo que el SDK y el contrato publican. Si algo no está en esas fuentes, la skill lo dice en lugar de inventarlo. Por ejemplo, los comprobantes de retención (07) y de donación (15) no los ofrece la API, y el listado con el documento incluido todavía no está publicado en el SDK.
Está pensada para TypeScript y JavaScript, y para HTTP directo. El SDK oficial es ese; para otros lenguajes consulte las páginas de HTTP directo.
No sustituye revisar el resultado. Pruebe siempre en el ambiente 00 con una llave facta_test_ antes de pasar a producción: la guía de pruebas a producción sigue siendo la referencia.