El paper SkillReducer (arXiv:2603.29919) cuantificó el problema a escala: de 55.315 skills analizadas, el 26.4% ni siquiera tenía descripción de routing — el campo que el agente usa para decidir cuándo activarlas. Más del 60% del cuerpo era contenido no-accionable.
Lo curioso: cuando comprimieron las skills un 48% en descripción y 39% en cuerpo, la calidad funcional subió un 2.8%. Menos contenido, mejor rendimiento. El efecto "less is more" no es intuición — está medido.
Hay algo más profundo detrás de esto que nadie está nombrando directamente.
El malentendido que nadie corrige
Cuando alguien escribe una skill, su instinto es dar al agente todo el contexto posible. Más instrucciones = agente más listo. Es la misma lógica que llevas al prompt de chat y que en agentes te destruye.
El problema no es la cantidad de información — es dónde la pones.
El sistema de routing de skills funciona con un budget fijo. Más descripción no significa que el agente entienda mejor tu skill. Significa que hay menos espacio para las demás. Y cuando el sistema trunca, no te avisa. El agente simplemente ignora las skills que no entran y resuelve sin ellas, o peor: activa la skill equivocada porque la descripción de la correcta quedó cortada.
Esto explica algo que muchos reportan en Reddit y HN: "mi agente ignora skills que sé que tiene instaladas". No las ignora. Simplemente no las ve.
El modelo de "progressive disclosure" que propone el paper SkillReducer, y que OpenSkills implementa como SDK, separa la información en tres capas:
- Capa 1 (Metadata): triggers y tags. Siempre cargada. Mínima.
- Capa 2 (Instructions): el SKILL.md core. Solo cuando el agente activa la skill.
- Capa 3 (Resources): docs de referencia. Solo cuando el contexto de la conversación lo requiere.
La lógica es la misma que ya usas en código: no importas todo al arranque. Importas lo que necesitas cuando lo necesitas.
El matiz honesto
Esto no afecta igual a todos los setups. Si tienes 3-5 skills bien escritas, el budget no es el problema — probablemente nunca lo rozas.
El problema escala con el número de skills instaladas. Un developer con 5 skills tiene margen. El mismo developer después de un mes instalando skills desde clawhub sin revisar puede tener 25, con varios duplicados, algunos sin descripción, y otros con el cuerpo completo cargándose en cada turno aunque no sean relevantes.
También depende del modelo: GPT-5.5 tiene 272K tokens de contexto, y el 2% son 5.440 tokens de budget. Modelos con ventanas más pequeñas tienen presupuestos todavía más ajustados.
A quién le aplica esto
Te aplica directamente si:
- Tienes más de 10 skills instaladas en tu agente
- Usas skills de terceros desde repositorios públicos sin revisar el tamaño
- Has notado que tu agente "olvida" usar skills que sabes que tiene
- Tu AGENTS.md tiene más de 200 líneas
No es urgente si:
- Tienes 3-5 skills propias que mantienes tú
- Cada skill tiene descripción de una sola línea con los triggers clave
- No has instalado skills nuevas en el último mes
El umbral práctico: si skill-cleaner te reporta que tu skill budget está por encima del 80% de ocupación, es momento de auditar.
La pieza que te llevas
Tres acciones concretas, en orden de impacto:
1. Audita con skill-cleaner de steipete
# Desde tu repo con las skills
npx --yes node --experimental-strip-types \
skills/skill-cleaner/scripts/skill-cleaner.ts --months 3
El reporte te dice: budget actual ocupado, skills no usadas en 3 meses, duplicados, y candidatas a comprimir.
2. Regla de los 60 chars para descripciones
La descripción que el agente usa para routing se trunca a ~60 chars en el system prompt. Escríbela como si solo tuvieras eso:
Descripción inflada
Use this skill when you need to work with the Pirinai Academy blog system. This skill helps you write, publish, and manage blog posts in the Supabase database, including handling cover images, excerpts, tags, categories, paywall configuration, and SEO metadata for the Pirinai Academy website at academia.pirinai.com.
Descripción útil
Publish and manage blog_posts in Supabase for academia.pirinai.com. INSERT/UPDATE only.
La segunda versión da al agente exactamente lo que necesita para activar la skill. El resto va en el cuerpo, y solo se carga cuando la skill se activa.
3. Mueve el contexto estático a referencias
Si tu skill tiene secciones de "cómo funciona X" o tablas de referencia que el agente solo necesita ocasionalmente, sácalas del SKILL.md principal y ponlas en references/. El agente las carga solo cuando las necesita, no en cada turno.
Docs de referencia: skill-cleaner en agent-scripts · SkillReducer paper
Pirinai Academy6 min de lectura