Visión general de Skills

Una skill es un paquete de instrucciones — en Markdown, con reglas, ejemplos y sub-referencias — que le enseña a un asistente de IA a ejecutar un flujo específico de principio a fin, siempre de la misma manera. Piénsala como el "manual del buen colega" que el asistente carga en el contexto en el momento en que la activas.

A diferencia de una pregunta suelta, cuando invocas una skill el asistente sigue las reglas de esa skill — el orden correcto, los campos obligatorios, las trampas conocidas — en lugar de improvisar con base en lo que aprendió durante el entrenamiento.

Qué trae una skill

Cada skill suele incluir:

• SKILL.md — el punto de entrada, con el resumen del flujo, reglas transversales y el mapa de las sub-referencias.
• references/ — sub-referencias detalladas por tema o dominio (endpoints, DTOs, ejemplos de payload, reglas de negocio).
• Convenciones internas — qué preguntar antes de empezar, qué evitar, qué errores comunes ya se han mapeado.

El asistente lee el SKILL.md al abrir y abre las sub-referencias solo cuando el tema lo requiere — esto mantiene el contexto ligero y evita respuestas "a ojo".

Cómo invocar una skill

Se invoca de dos maneras:

1. Comando directo — escribe /nombre-de-la-skill en el asistente. Ej.: /phoenix-bug, /anymarket-backoffice-api-guide.
2. Lenguaje natural — describe lo que necesitas y el asistente detecta la skill correcta a partir de las frases disparadoras declaradas en ella. Ej.: "haz el RCA del bug 12345", "ayúdame a integrar el registro de productos con ANYMARKET".

Una vez invocada, la skill suele hacer preguntas de clarificación antes de actuar (entorno, credenciales, contexto del proyecto) — es intencional y evita retrabajo.

Dónde viven las skills

Físicamente, las skills viven en carpetas versionadas — cada una con su propio SKILL.md y references/. El asistente descubre las skills disponibles a partir del directorio configurado en tu harness (el cliente/IDE de IA que usas) o de un repositorio interno del equipo. Cada harness tiene su propio directorio por defecto y su forma de recargar skills — consulta la documentación del harness que uses para saber la ruta exacta.

Catálogo de skills

Skill	Qué hace	Cómo invocarla
ANYMARKET Backoffice API Guide	Guía completa de la API v2 Backoffice de ANYMARKET — 17 dominios (productos, SKUs, pedidos, stock, precios, listings, NF-e, callbacks, etc.), reglas de autenticación, entornos, paginación, rate limit y el flujo greenfield vs brownfield para integraciones.	/anymarket-backoffice-api-guide — o pide en lenguaje natural cualquier cosa relacionada con integración ERP ↔ ANYMARKET (TOTVS, Winthor, Protheus, SAP, ERP propio).

Cómo instalar una skill

La idea siempre es la misma, sin importar el harness que uses:

1. Clona (o descarga) el repositorio de la skill.
2. Copia la carpeta de la skill al directorio de skills que tu harness lee.
3. Recarga el harness (reinicio, comando de reload o equivalente).
4. Confirma que la skill aparece en la lista de skills disponibles (/help, panel de configuración, etc., según el harness).

La ruta exacta del directorio y la forma de recargar cambian de un harness a otro — revisa la documentación oficial del tuyo antes de empezar.

Si la skill trae un install.sh o instrucciones específicas en el SKILL.md, sigue el paso a paso desde ahí — algunas skills necesitan variables de entorno (tokens, endpoints) para funcionar.

Cómo crear una nueva skill

Para proponer una skill nueva:

1. Esboza qué flujo quieres automatizar (input → pasos → output esperado) y qué decisiones el asistente necesita tomar en el camino.
2. Escribe el SKILL.md siguiendo el patrón de las existentes — frontmatter con name y description (las frases disparadoras viven ahí), cuerpo con reglas y mapa de las sub-referencias.
3. Divide el contenido en sub-referencias (references/<tema>.md) para mantener cada archivo enfocado — el asistente solo abre lo que necesita.
4. Prueba la skill con casos reales antes de publicarla. Ajusta las frases disparadoras hasta que el asistente la detecte correctamente.
5. Abre la propuesta con el equipo de IA & Automatización para review y publicación en el repositorio interno de skills.

Buenas prácticas

• La descripción de la skill importa. Es lo que el asistente lee para decidir si la invoca — frases disparadoras vagas causan falsos positivos y negativos.
• Una skill, un flujo. Si necesitas cubrir dos flujos muy distintos, probablemente son dos skills.
• Preguntas antes de actuar. Las skills que hacen cambios sensibles deben clarificar entorno / credenciales / contexto antes de disparar cualquier llamada — evita retrabajo y errores en producción.
• Sub-referencias ligeras. Cada archivo en references/ debe caber en un solo tema. Contexto grande cuesta tokens y degrada la calidad de la respuesta.