Best Practices for Creating Agent Skills
Tiempo estimado de lectura: 5 min
- Diseña SKILL.md como orquestador compacto: no como una enciclopedia; enumera pasos y triggers claros.
- Externaliza lo frágil: scripts deterministas en scripts/, reglas densas en references/, templates en assets/.
- Progressive Disclosure (JiT): carga solo archivos cuando surge un trigger explícito.
- Validación en tres fases con LLMs: discovery, lógica y edge-case testing.
Introducción
¿Quieres que tus agentes dejen de fallar por cosas tontas? La mayoría lo hace porque sus skills son documentación para humanos disfrazada de herramienta para máquinas. Los agentes no leen; ejecutan. Y para ejecutar necesitan reglas claras, rutas exactas y scripts que no improvisen.
Aquí va la arquitectura práctica que uso cuando diseñamos skills que realmente funcionan en producción.
Resumen rápido (lectores con prisa)
Qué es: Un conjunto de reglas, scripts y plantillas organizadas para que un agente tome decisiones deterministas.
Cuándo usarlo: Al diseñar skills que interactúan con repositorios, migraciones, o tareas automatizadas que requieren reproducibilidad.
Por qué importa: Evita ambigüedades que causan alucinaciones y resultados inconsistentes.
Cómo funciona: SKILL.md orquesta; scripts ejecutan validaciones; references/ y assets/ se cargan sólo mediante triggers explícitos.
Estructura de una skill: la regla de hierro
skill-name/ ├── SKILL.md # Metadatos + instrucciones core (<500 líneas) ├── scripts/ # CLIs pequeños para tareas deterministas ├── references/ # Reglas densas, cheatsheets, esquemas └── assets/ # Templates y archivos estáticos
SKILL.md es “el cerebro”: orquesta, no enciclopedia. scripts/ ejecuta lo que no puede fallar. references/ y assets/ guardan lo pesado, pero el agente sólo los lee cuando se lo indicas.
Naming y frontmatter: haz que la skill sea visible
El agente decide cargar una skill solo por el frontmatter. Si tu nombre y descripción son vagos, la skill es invisible.
Reglas:
- name = 1–64 chars, minúsculas, números y guiones. Debe coincidir exactamente con el nombre del directorio.
- descripción = máximo 1,024 caracteres, en tercera persona e incluye negative triggers.
Ejemplo práctico:
name: angular-vite-migrator description: Migra proyectos Angular CLI de Webpack a Vite y esbuild. Usar para actualizar builders o reemplazar plugins de Webpack por equivalentes de Rollup. No usar para proyectos React, Svelte o para sólo actualizar la versión de Angular.
Eso reduce falsos positivos. Punto.
Progressive Disclosure: carga solo lo necesario
Los LLMs tienen memoria limitada. Meter 800 líneas de vite.config.ts en el prompt es pedir perdón por las alucinaciones.
Patrón: JiT (Just-in-Time).
- SKILL.md enumera pasos altos y dice exactamente cuándo abrir un archivo.
- Coloca plantillas complejas en assets/ y reglas en references/.
- Instrucción clara: “Si detectas @angular-builders/custom-webpack en angular.json, abre references/webpack-fallbacks.md”.
El agente no ve nada hasta que el trigger ocurre. Menos tokens, más precisión.
Escribe para máquinas: imperativo y pasos numerados
Las skills son código en lenguaje natural. Escribe en tercera persona, imperativo y con pasos numerados.
Correcto:
1. Ejecuta scripts/env-validator.mjs 2. Si el exit code es 1, reporta: "Node version incompatible. Upgrade required." Termina.
Incorrecto: “Quizá quieras comprobar la versión de Node…” — frase que confunde y genera ambigüedad.
Scripts deterministas: no pidas improvisación
No le pidas al LLM que escriba parsers complejos en cada ejecución. Empaqueta esos parsers y detectores como scripts pequeños y probados en scripts/. El agente los invoca con parámetros y actúa según stdout/stderr.
Ejemplo de stdout útil:
CRITICAL: Found legacy CommonJS 'legacy-lib' that uses dynamic require(). Recommendation: add to optimizeDeps.include or shim with esm-adapter. See references/commonjs-guide.md
Ese mensaje debe permitir al agente decidir el siguiente paso sin adivinar.
Templates y outputs parseables
Coloca un template en assets/ (por ejemplo, assets/vite.config.template.ts). Instrucción en SKILL.md:
- “Copia assets/vite.config.template.ts a vite.config.ts y rellena los placeholders según el mapeo en references/mapping.md.”
Los LLMs reconocen patrones; darles la plantilla evita salidas rotas y archivos inválidos.
Validación con LLMs: prueba en tres fases
Las skills las usarán LLMs, así que valídalas con LLMs.
1. Discovery Validation
Pega solo el frontmatter en un LLM limpio. Pide 3 prompts que deben activar la skill y 3 que no. Ajusta la descripción hasta que el modelo acierte.
2. Logic Validation
Pasa el SKILL.md y la estructura de archivos. Pide al LLM que actúe como agente y escriba su monólogo paso a paso: qué lee, qué ejecuta, y dónde se ve obligado a adivinar.
3. Edge Case Testing (Red Team)
Pide al LLM que te rompa la skill con preguntas concretas: Node antiguo, builders custom, imports dinámicos. Si responde con huecos, rellena referencias y scripts hasta que no queden ambigüedades.
Ejemplos de fallas comunes y cómo prepararlas
- CommonJS legacy en esbuild: añade scripts/detect-commonjs.mjs que devuelvan JSON con las dependencias problemáticas y recomendaciones.
- @angular-builders/custom-webpack en angular.json: stop automatic migration. Instruye a abrir references/webpack-fallbacks.md y proponer un plan híbrido (mantener Webpack para producción, migrar dev a Vite).
- Entorno Node no compatible: scripts/env-validator.mjs debe chequear process.version y salir con mensaje accionable.
Cierre con criterio
Construir skills no es arte ni redacción creativa: es ingeniería. Nombra con precisión, externaliza lo frágil a scripts, usa templates y obliga a los agentes a cargar sólo lo que necesitan. Haz esto y tus agentes dejarán de inventar soluciones —y empezarán a producir resultados reproducibles.
Reestructura una skill bajo estas reglas hoy y verás cómo el agente deja de improvisar. Esto no acaba aquí; las skills bien diseñadas son la base de la automatización fiable.
Dominicode Labs
Para equipos que diseñan workflows y agentes, recursos y experimentos prácticos en automatización y agentes están disponibles en Dominicode Labs. Considera revisarlo como complemento para validar skills y pipelines en entornos reales.
FAQ
¿Qué debe contener SKILL.md?
SKILL.md debe ser el orquestador: metadatos (frontmatter), pasos numerados claros, triggers explícitos sobre cuándo abrir archivos en references/ o assets/, y referencias a scripts/ ejecutables. Mantenerlo por debajo de 500 líneas.
¿Por qué externalizar parsers en scripts/?
Porque los parsers y detectores complejos son frágiles si se piden al LLM en cada ejecución. Scripts deterministas devuelven stdout/stderr o JSON que permite decisiones automáticas sin ambigüedad.
¿Cómo funciona Progressive Disclosure?
El agente solo carga información adicional cuando un trigger en SKILL.md lo indica (JiT). Así se evita saturar el prompt con archivos largos y se mejora la precisión.
¿Qué formato deben tener los outputs de los scripts?
Outputs legibles por máquina: líneas con prefijos (ej. CRITICAL:) o JSON. Deben contener suficiente contexto y una recomendación accionable para que el agente decida el siguiente paso.
¿Cuándo incluir references/webpack-fallbacks.md?
Incluirlo cuando detectes @angular-builders/custom-webpack en angular.json. La instrucción en SKILL.md debe ordenar abrir ese archivo y proponer un plan híbrido si aplica.
¿Cómo validar una skill con LLMs?
Validación en tres fases: Discovery Validation con solo frontmatter, Logic Validation con SKILL.md y estructura de archivos (monólogo del agente), y Edge Case Testing (Red Team) para cerrar huecos.