Mejores Prácticas para Crear Habilidades de Agentes Efectivas

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

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:
  1. “Validate environment: run scripts/check-node-env.js.”
  2. “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.json contenga @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:

1. 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.
2. 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.
3. 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

• Vite
• esbuild
• Node.js
• Madge (análisis de dependencias)
• Agents skills spec (referencia de metadatos)

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?

skill-name/
├── SKILL.md
├── scripts/
├── references/
└── assets/

CRITICAL: package.json lacks 'build' script. Recommend: run `npx ng update @angular/cli` then retry.