Mejores Prácticas para Crear Habilidades de Agentes Efectivas
DominicodeBest Practices for Creating Agent Skills
Tiempo estimado de lectura: 6 min
Ideas clave
- Diseñar skills con frontmatter preciso y estructura mínima para que los agentes los carguen correctamente.
- Escribir instrucciones procedimentales orientadas a máquinas, usando Progressive Disclosure para ahorrar tokens.
- Empaquetar scripts deterministas para operaciones repetitivas y definir stdout/stderr como contrato para decisiones automáticas.
- Validar skills con fases: Discovery, Logic y Edge-case testing usando LLMs.
- Documentar fallbacks y thresholds en referencias; tratar skills como componentes versionados e inspeccionables.
Best Practices for Creating Agent Skills: si quieres que un agente no solo arranque, sino que sobreviva en producción, necesitas más que buenos prompts. Necesitas arquitectura, disciplina y pruebas diseñadas para máquinas. Este artículo explica, con ejemplos prácticos y referencias, cómo construir skills que los LLMs realmente puedan usar.
Resumen rápido (lectores con prisa)
Definir frontmatter preciso, escribir pasos procedimentales en tercera persona imperativa, mover reglas densas a references/ y proveer scripts deterministas. Validar con tres fases (Discovery, Logic, Edge-case) y usar stdout/stderr como contrato para decisiones automáticas.
Best Practices for Creating Agent Skills: estructura, metadatos y responsabilidades claras
Los agentes ven un skill antes que nada por su frontmatter. Si ese nombre o descripción no son precisos, el agente nunca cargará tu skill. Sigue estas reglas prácticas:
- Estructura mínima obligatoria:
skill-name/ ├── SKILL.md # Metadatos + instrucciones core (<500 líneas) ├── scripts/ # CLIs pequeños para tareas deterministas ├── references/ # Reglas densas, esquemas, decision-trees └── assets/ # Plantillas y JSON schemas
- Frontmatter: nombre exacto del skill = nombre del directorio; 1–64 caracteres, minúsculas, números y guiones.
- Descripción: 1.024 caracteres máx.; redactar en tercera persona; incluir negative triggers (qué NO debe hacer el skill).
Referencia: agentes basados en metadatos (ej.: agentskills.io).
Escribe para máquinas: instrucciones procedimentales y JiT loading
Los LLMs funcionan por patrones. Tu SKILL.md no es un manual; es el orquestador.
- SKILL.md: pasos cronológicos en tercera persona imperativa. Ejemplo:
- “Validate environment: run scripts/check-node-env.js.”
- “If fails, abort with message from stderr and surface actionable advice.”
- No copies masivas de config. Usa Progressive Disclosure: mueve plantillas y reglas densas a assets/ y references/ y obliga al agente a leerlas solo cuando las necesite.
- Rutas siempre con forward slashes (/).
Beneficio: menor consumo de tokens, decisiones más precisas.
Bundle deterministic scripts for repetitive operations
No pidas al modelo que genere parseadores complejos cada ejecución. Provee scripts probados:
- scripts/detect-commonjs.mjs — detecta módulos CommonJS problemáticos (puede usar madge: Madge).
- scripts/env-validator.mjs — valida versión de Node, gestor de paquetes y permisos.
- scripts/transform-schema.py — transforma esquemas con reglas inmutables.
Diseña los scripts para devolver errores humanos y machine-actionable por stderr/stdout. Ejemplo de stderr útil:
CRITICAL: package.json lacks 'build' script. Recommend: run `npx ng update @angular/cli` then retry.
Referencias técnicas: Vite, esbuild, Node.js.
Progressive Disclosure: cuándo cargar qué
Patrón:
- SKILL.md indica: “Si detectas X, leer references/X.md”.
- Agent only loads references/X.md when X aparece en el repo.
Ejemplo aplicado a migración Angular→Vite:
- No leer webpack-fallbacks.md salvo que
angular.jsoncontenga@angular-builders/custom-webpack.
Resultado: contexto limpio hasta el momento de la decisión.
Validación con LLMs: Discovery, Logic y Edge-case testing
Prueba tus skills con otros agentes siguiendo tres fases:
- Discovery Validation
- Pega solo el frontmatter en un LLM y pregúntale qué prompts deberían y no deberían activar la skill. Ajusta description hasta que el modelo sea inequívoco.
- Logic Validation
- Da al LLM SKILL.md + tree de archivos. Pídele simular ejecución paso a paso con monólogo interno: “¿Qué archivo leo? ¿Qué script ejecuto? ¿Dónde me obligaron a adivinar?”
- Marca las líneas donde el agente tuvo que suponer datos.
- Edge Case Testing
- Pide al LLM que actúe como QA hostil y genere 3–5 preguntas que rompan la skill (p. ej. Node version < 18, custom webpack builders, imports dinámicos CommonJS).
Sugerencia de benchmark: SkillsBench para inspiración de evals (busca repositorios o frameworks de evaluación de skills).
Manejo de errores y criterios de fallback
- Stdout/stderr como contrato: script devuelve JSON estructurado para éxito o mensajes humanos para fallos.
- Define thresholds decisionales: p. ej., si detectas >3 dependencias CommonJS problemáticas, abortar migración automática y sugerir fallback híbrido.
- Documenta fallbacks en references/, no en SKILL.md.
Ejemplo rápido de decisión (pseudocódigo)
1. Run scripts/env-validator.mjs 2. If exit code ≠ 0 -> return error to user with remediation steps 3. Run scripts/detect-legacy-deps.mjs 4. If legacyDeps.count > 3 -> consult references/commonjs-guide.md and recommend hybrid strategy 5. Else -> read assets/vite.config.template.ts and generate vite.config.ts
Cierre: audiencia, responsabilidad y próxima iteración
Las Agent Skills son componentes de infraestructura: deben ser nombradas, versionadas y validadas como cualquier servicio. La disciplina (terminología única, scripts deterministas, progressive disclosure y validación con LLMs) convierte un experimento en una herramienta repetible.
Implementa estas prácticas y reduce fallos sorpresa en entornos reales. Si quieres un checklist listo para copiar en SKILL.md o ejemplos de scripts env-validator/detect-commonjs, disponemos de plantillas y pruebas automatizadas que puedes integrar hoy.
Fuentes y lectura adicional
Implementa esto ahora: estructura tu skill, saca las reglas densas a references/, empaqueta los scripts y empieza las pruebas Discovery/Logic/Edge-case con un LLM. Tu próxima iteración será menos sorpresiva y mucho más confiable.
Para continuar con herramientas y plantillas que complementan este enfoque, considera explorar Dominicode Labs como una continuación lógica de prácticas de automatización y evaluación de skills.
FAQ
- ¿Qué debe contener la estructura mínima de un skill?
- ¿Qué es Progressive Disclosure y cuándo usarlo?
- ¿Cómo deben devolver los scripts errores y resultados?
- ¿Qué pruebas realizar con LLMs?
- ¿Cuándo abortar una migración automática?
¿Qué debe contener la estructura mínima de un skill?
La estructura mínima es:
skill-name/ ├── SKILL.md ├── scripts/ ├── references/ └── assets/
SKILL.md contiene metadatos e instrucciones core (<500 líneas); scripts/ almacena herramientas deterministas; references/ reglas densas; assets/ plantillas y esquemas.
¿Qué es Progressive Disclosure y cuándo usarlo?
Es la práctica de mover reglas y artefactos densos a archivos que se cargan solo si son necesarios. Úsalo para reducir tokens y mantener el contexto limpio hasta el momento de la decisión.
¿Cómo deben devolver los scripts errores y resultados?
Definir stdout/stderr como contrato: devolver JSON estructurado para éxitos y mensajes humanos accionables en stderr para fallos, por ejemplo:
CRITICAL: package.json lacks 'build' script. Recommend: run `npx ng update @angular/cli` then retry.
¿Qué pruebas realizar con LLMs?
Realiza tres fases: Discovery (solo frontmatter), Logic (simulación paso a paso con SKILL.md + tree) y Edge-case (QA hostil generando escenarios que rompan la skill).
¿Cuándo abortar una migración automática?
Define thresholds decisionales; por ejemplo, si detectas >3 dependencias CommonJS problemáticas, aborta la migración automática y recomienda una estrategia híbrida documentada en references/.