Prácticas para crear skills efectivas en agentes

Best Practices for Creating Agent Skills

Tiempo estimado de lectura: 5 min

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:

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).

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:

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

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.