English

Mantén las skills planas, y los helpers en el código fuente

Tu carpeta de skills de IA se está volviendo un codebase fantasma.

Empieza inocente: una skill necesita parsear un archivo, así que dejas un scriptcito al lado. Luego otra skill necesita casi lo mismo, así que lo copias. Pronto tu directorio de skills está lleno de helpers anidados, módulos de utilidades y scripts — lógica sin tests, duplicada entre skills, y alejándose del código real que se suponía debía reflejar. Eso es un codebase fantasma, y es justo lo que las skills querían evitar.

Por qué anidar helpers sale mal

Una skill es una metodología — guía que el modelo lee y sigue. Un script helper es código determinista — corre igual cada vez. Mezclarlos pone lógica real en un lugar sin ninguna de las salvaguardas que la lógica real necesita:

• Sin tests. Los scripts enterrados en una carpeta de skill no están en tu suite de pruebas. Se rompen en silencio.
• Duplicación. La misma lógica de parsear-esto o formatear-aquello se copia en cada skill que la necesita, y las copias divergen.
• Deriva silenciosa. Cuando el comportamiento real cambia en tu árbol de fuente, las copias anidadas no. Ahora la skill instruye al agente con lógica obsoleta.
• Sin revisión. El código que nunca aterriza en un pull request revisado nunca recibe los ojos que habrían atrapado el bug.

El mecanismo: skills planas, helpers en la fuente

Dos reglas mantienen limpia la frontera:

1. Mantén cada skill como un archivo plano y único — una metodología autocontenida por skill, sin árbol de scripts anidado. Si una skill crece más de lo que un archivo debería contener, divídela en archivos hermanos planos, no en subcarpetas de código.
2. Pon los helpers deterministas en tu árbol de fuente real, donde se prueban, revisan y versionan. La skill referencia la herramienta; no la contiene.

# Antipatrón: codebase fantasma
skills/
  release/
    SKILL.md
    scripts/
      bump_version.py      # sin tests, duplicado en otras dos skills
      changelog_utils.py

# Mejor: skill plana, el helper vive en la fuente
skills/
  release.md               # solo metodología; dice "corre scripts/release/bump.py"
src/
  release/
    bump.py                # en la suite de tests, revisado, única fuente de verdad
    changelog.py
tests/
  release/test_bump.py

La skill le dice al agente qué hacer y cuándo; el árbol de fuente guarda el código que lo hace de forma determinista.

Metodología vs. código determinista

La divulgación progresiva hace el resto

Las skills hermanas y planas encajan de forma natural con la divulgación progresiva (progressive disclosure): el agente carga solo los archivos que una tarea realmente necesita, en vez de arrastrar todo un árbol anidado al contexto. Menos archivos cargados, cada uno enfocado, y ninguno una copia de código que vive — y se prueba — en otro lado.

Movidas avanzadas

• Cuando vayas a meter un script dentro de una skill, detente. Pregúntate si esa lógica debería ser una función probada en src/ que la skill invoque.
• Una metodología por archivo de skill. Si se cuelan dos preocupaciones, esa es la señal para dividir en hermanos planos.
• Busca duplicación con grep. Si el mismo helper aparece en dos carpetas de skill, pertenece a la fuente como una sola función.
• Referencia por ruta, no por copia. Una skill debe nombrar la herramienta a correr, para que la única implementación probada siga siendo la autoridad.

Recursos

• Agent Skills — documentación de Anthropic (progressive disclosure)
• Engineering effective agent skills — Anthropic
• Model Context Protocol — herramientas
• Don't repeat yourself (DRY) — Wikipedia