English

Pasadas las 700 líneas, divide la skill

Tu doc de IA de 800 líneas no se está leyendo. Se está hojeando.

Un archivo de skill solo sirve si el modelo de verdad lo carga y lo sigue. Pasadas unas 700 líneas — o en el momento en que empieza a cubrir varios temas no relacionados — una skill deja de leerse con cuidado. Se hojea, se pierden reglas clave y se come una porción enorme del contexto necesite la tarea actual todo su contenido o no. La solución es la divulgación progresiva (progressive disclosure): divide el archivo gigante en piezas enfocadas, y hazlo sin romper una sola referencia existente.

Por qué las skills grandes dejan de funcionar

Dos modos de falla se agravan pasado el umbral:

• Hojear en vez de leer. Los archivos largos y multitema diluyen la atención. La regla que importaba para esta tarea está enterrada en la línea 640, junto a cuatro temas que no aplican.
• Carga todo-o-nada. Un monolito se carga entero. Pagas el costo completo de contexto aunque la tarea toque una sola sección, desplazando el código y el razonamiento que sí necesitan la ventana.

La señal para dividir es simple: unas 700 líneas, o más de un tema en un archivo.

El mecanismo: dividir sin romper referencias

El truco es dividir de modo que cada enlace, mención y referencia @ al archivo viejo siga resolviendo.

1. Conserva el nombre de archivo original como entrada de resumen. No lo borres ni lo renombres. Convierte su contenido en un resumen corto más una tabla de contenidos de un nivel de profundidad que apunte a las piezas nuevas. Cada referencia que ya apunta a este nombre de archivo sigue funcionando — ahora aterriza en un mapa en vez de un monolito.
2. Mueve cada tema a un archivo hermano plano en la misma categoría. No subcarpetas anidadas — hermanos planos, una metodología enfocada cada uno.
3. Enlaza solo un nivel de profundidad: entrada a hermano, nunca hermano a hermano. El resumen apunta a los hermanos; los hermanos no se referencian entre sí. Eso mantiene el grafo de carga plano y predecible.

# Antes: un monolito
skills/release.md            # 800 líneas, cinco temas

# Después: entrada de resumen + hermanos planos
skills/release.md            # MISMO nombre de archivo — ahora resumen + TOC
skills/release-versioning.md
skills/release-changelog.md
skills/release-rollback.md
skills/release-announcements.md

<!-- skills/release.md — entrada de resumen, referencias de un nivel -->
# Metodología de release (resumen)
Carga el hermano que coincida con tu tarea:

- Versionado y etiquetado → release-versioning.md
- Generación de changelog → release-changelog.md
- Procedimiento de rollback → release-rollback.md
- Anuncios de release      → release-announcements.md

Por qué esta forma aguanta

Cada hermano queda enfocado y cargable por sí solo, y el nombre de archivo de entrada preservado significa que nada río arriba se rompe.

Movidas avanzadas

• Divide por tema, no solo por conteo de líneas. Dos preocupaciones no relacionadas en un archivo son razón suficiente, aun por debajo de las 700 líneas.
• Nunca renombres la entrada. Toda la propiedad de "sin referencias rotas" depende de conservar el nombre de archivo original como resumen.
• Mantén el grafo en un nivel. La entrada apunta a los hermanos; los hermanos no se apuntan entre sí. Grafos más profundos hacen la carga impredecible.
• Una metodología por hermano. Si un hermano en sí empieza a desbordarse pasado el umbral, divídelo de la misma forma.
• Reaudita tras dividir. Los nuevos archivos hermanos nacen sin referencias salvo de su padre — anótalo para que una auditoría posterior no los marque como muertos.

Recursos

• Agent Skills — documentación de Anthropic (progressive disclosure)
• Effective context engineering for AI agents — Anthropic
• Memory / imports de CLAUDE.md — documentación de Claude Code
• Model Context Protocol — recursos