Los skills que mi agente no podía ver

Tenía 84 skills instalados y daba por sentado que los 84 funcionaban. Cinco no lo hacían. swiftui, testing-philosophy, typeset, web-performance y update-shortcuts-guide llegaban al modelo como nombres sueltos, sin ninguna descripción adjunta, mientras que sus archivos en disco tenían descripciones perfectamente válidas. Un skill sin descripción no puede recibir enrutamiento, porque la descripción es la señal de enrutamiento. Esos cinco nunca podían activarse de forma automática, y nada en ninguna parte me lo dijo. Ningún error, ninguna advertencia, ninguna línea de log. Los encontré por accidente, y la única razón por la que pude demostrar la causa es que la corrección revirtió el problema delante de mí. {.answer-block}

En resumen

• Las descripciones de skills se cargan en el contexto de cada turno y comparten un presupuesto fijo de caracteres. Si lo superas, las descripciones se descartan en silencio.¹²
• Tenía 84 skills instalados, 82 de ellos con descripción, para un total de 21,848 caracteres. Cinco llegaron con el nombre presente y la descripción ausente. En disco, esos cinco tenían entre 206 y 336 caracteres cada uno.
• Ningún atributo de archivo explicaba cuáles cinco se descartaron. Longitud de la descripción, tamaño del archivo, formato YAML, discrepancia entre name y el directorio, y fecha de modificación: todo se solapaba entre los descartados y los conservados.
• Reescribí 74 descripciones hasta dejar el total en 9,885 caracteres. Los cinco skills reaparecieron a mitad de sesión, en la misma conversación, con la descripción intacta. Hipótesis, intervención, confirmación.
• El presupuesto exacto no está documentado y hoy se discute. Anthropic tiene incidencias abiertas que reportan que la fracción se calcula contra una base fija de 200K e ignora la extensión de contexto de 1M.³⁴
• La regla de reescritura que hizo que todo entrara: el único trabajo de una descripción es responder cuándo hay que invocar esto. El procedimiento, la filosofía y las rutas de archivos pertenecen al cuerpo, que solo se carga al invocarlo.

Una falla sin mensaje de error

La mayoría de los errores del harness se anuncian solos. Un hook termina con código distinto de cero, un servidor MCP se niega a arrancar, una llamada a una herramienta devuelve un stack trace. El presupuesto de descripciones no hace nada de eso. Le sirve al modelo, sin decir palabra, una lista más corta que la que tienes en disco, y cada síntoma posterior parece un problema del modelo en vez de un problema de plomería.

Me di cuenta leyendo mi propia ventana de contexto en lugar de mi sistema de archivos. Al revisar el listado de skills, cinco entradas tenían un nombre y nada después. Todas las demás tenían un nombre y una oración. Fui a buscar los archivos:

swiftui                    HAS  322 chars on disk -> DROPPED in context
testing-philosophy         HAS  291 chars on disk -> DROPPED in context
typeset                    HAS  248 chars on disk -> DROPPED in context
web-performance            HAS  206 chars on disk -> DROPPED in context
update-shortcuts-guide     HAS  336 chars on disk -> DROPPED in context

La consecuencia es peor que un skill lento o equivocado. Un agente decide si invoca un skill leyendo su descripción. Si le quitas la descripción, no degradaste el enrutamiento: lo eliminaste. El skill está instalado, es válido y resulta inalcanzable. swiftui es mi skill de patrones de iOS 26, lo que significa que cada sesión de Swift que ejecuté había estado volando sin él.

Anthropic tiene incidencias abiertas que describen la misma falla, entre ellas una titulada «Skill description budget silently truncates routing information, causing skill routing failures».² Así que el comportamiento es un error conocido y no una mala configuración local. Fue útil enterarme, y no me ayudó a encontrar cuáles de mis skills estaban afectados.

Descartar las respuestas fáciles

La tentación era adivinar el mecanismo y arreglarlo. Primero intenté refutar las conjeturas, porque «cinco skills están rotos» y «cinco skills están rotos por esta razón» son afirmaciones muy distintas.

Si alguna propiedad a nivel de archivo marcaba un skill para el descarte, el grupo descartado debería diferir del grupo conservado en algo medible. Los comparé:

| Propiedad | Descartados (5) | Conservados (77) | |—|—| | Longitud media de la descripción | 280 caracteres | 266 caracteres | | Tamaño medio del archivo | 9,106 bytes | 7,608 bytes | | Descripción YAML en escalar de bloque | 2 de 5 | 30 de 77 | | name distinto del directorio | 1 de 5 | 4 de 77 | | Fecha de modificación | de enero a julio | de enero a julio |

Nada los separaba. Las descripciones descartadas no eran las más largas, los archivos no destacaban por su tamaño, el estilo de YAML estaba mezclado en ambos grupos y las fechas de modificación cubrían el mismo rango. La posición alfabética también falló: los skills que se ordenan después de swiftui conservaron su descripción.

En ese punto, la posición honesta era que tenía un síntoma reproducible y ningún mecanismo. Así que lo escribí de esa manera y me puse a buscar una prueba en lugar de una teoría.

La prueba

Si lo que importa es el total, entonces recortar el total debería restaurar las descripciones descartadas, sin importar qué archivos recorte. Esa predicción es refutable y barata.

Reescribí 74 descripciones y llevé el total de 21,848 caracteres a 9,885. Los cinco skills antes invisibles volvieron con su descripción adjunta, en la misma sesión, sin reiniciar nada.

Ese es todo el experimento. Una predicción, una intervención, una confirmación. El descarte es función del tamaño agregado, no de ninguna propiedad del archivo individual, que es justamente la razón por la que ningún atributo por archivo podía distinguir a los dos grupos.

Un error que no deja rastro sigue dejando un contrafáctico. Si no puedes encontrar la causa inspeccionando la falla, cambia una variable y observa si la falla la sigue.

Quiero ser preciso sobre lo que no establecí. No conozco el presupuesto exacto, y no voy a publicar un número que no puedo sustentar en una fuente. La documentación oficial omite el límite.⁵ Las mediciones de la comunidad sitúan el techo práctico cerca de los 15,500 a 16,000 caracteres y señalan unos 109 caracteres de sobrecarga por entrada provenientes de las etiquetas XML, el nombre del skill y el campo de ubicación, nada de lo cual captura un conteo crudo de caracteres de descripción.⁶ Con 84 skills, solo esa sobrecarga ronda los 9,156 caracteres. Al mismo tiempo, colaboradores de Anthropic reportan que la fracción del presupuesto se calcula contra una base fija de 200K e ignora la extensión de contexto de 1M, de modo que dos sesiones en la misma máquina pueden recibir presupuestos distintos.³⁴

Mi primer borrador de este hallazgo afirmaba que mi configuración estaba «119% por encima del presupuesto». Había multiplicado una suposición sin verificar (1% de una ventana de 1M) por una medición real y produje un número seguro de sí mismo que no tenía nada debajo. Los hechos observados sobreviven: 21,848 caracteres descartaron cinco descripciones y 9,885 no descartaron ninguna. El porcentaje no sobrevivió, y nunca debió haberse escrito.

El único trabajo de una descripción es el enrutamiento

Recortar 12,000 caracteres suena destructivo. No lo fue, porque casi todo lo que vivía en esas descripciones nunca hacía trabajo de enrutamiento.

Esto es lo que anunciaba mi skill jiro, con 686 caracteres:

Filosofía de artesanía shokunin para la calidad del código y el orgullo profesional. Se activa al implementar funciones, refactorizar código, escribir pruebas, revisar trabajo o trabajar en cualquier cambio no trivial en FastAPI/Python, Swift/SwiftUI, frontends con HTMX y código de infraestructura. Integra tres filosofías centrales: Shokunin (excelencia en los detalles invisibles), Omotenashi (servicio a través del oficio), Rick Rubin (canalización y destilación creativa). Punto de decisión central: el Evidence Gate (producir pruebas de calidad, no sensaciones sobre ella). Úsalo cuando: construyas funciones, refactorices, pruebes, revises código, corrijas errores o hagas cualquier trabajo donde se exija evidencia de calidad antes de reportar que está terminado.

Unos 500 de esos caracteres explican qué contiene el skill. Nada de eso ayuda a decidir si abrirlo. El reemplazo tiene 126 caracteres:

Estándares de artesanía y evidencia para la calidad del código. Úsalo al implementar, refactorizar, probar, revisar o corregir errores.

Las mismas palabras disparadoras, el mismo comportamiento de enrutamiento, la quinta parte del costo. La filosofía no desapareció; vive en el cuerpo, que solo se carga cuando el skill de verdad se ejecuta. Pagarla en cada turno no compraba nada.

El patrón se repitió en todo el conjunto. Nueve skills update-*-guide cargaban 3,024 caracteres de texto repetido casi idéntico sobre revisar fuentes, sincronizar copias y ejecutar traducciones. Reducidos a unos 115 caracteres cada uno, siguen enrutando bien, porque lo que los distingue es qué guía actualizan, no el pipeline que comparten.

Tres reglas hicieron el trabajo:

1. Conserva el disparador, corta la explicación. Los nombres, los comandos slash y las palabras que un usuario escribiría de verdad se quedan. Las descripciones del procedimiento interno se van.
2. Las rutas de archivos pertenecen al cuerpo. Una ruta no puede ayudarle al modelo a decidir cuándo invocar algo.
3. El texto repetido compartido es pura sobrecarga. Si nueve skills dicen la misma oración, esa oración no distingue a ninguno.

El segundo impuesto: descripciones que actúan sin que las llamen

Al recortar apareció un costo más sutil. Once de mis descripciones, 3,808 caracteres en total, cargaban lenguaje imperativo: ALWAYS, NEVER, MUST, PROACTIVELY, BEFORE. distribute decía NEVER. no-shortcuts decía ALWAYS. git-custody decía BEFORE.

Esas palabras están en el contexto en cada turno, se ejecute o no el skill. Se leen como instrucciones porque están escritas como instrucciones, y el modelo no tiene manera confiable de tratar una descripción como texto de catálogo inerte mientras trata como vinculante una instrucción de sistema redactada de forma idéntica.

Un trabajo reciente le pone nombre al efecto. «The Regression Tax», medido en unas 6,000 ejecuciones sobre dos benchmarks de automatización de oficina y tres stacks de harness, identifica la ósmosis de descripciones de skills: un skill que cambia el comportamiento del agente solo por estar presente en el contexto, incluso sin ser invocado nunca.¹ Su hallazgo principal es que los mejores skills ganan por regresionar menos y no por aportar más, y que los skills sobreinvierten en guía procedimental mientras subinvierten en fundamentación y verificación.

La evidencia de producción llegó antes que la teoría. Anthropic dio marcha atrás con la activación automática de los skills incluidos /verify y /code-review en la v2.1.215, y los dejó solo de invocación explícita.⁷ Dos versiones después, /deep-research también dejó de autoinvocarse.⁸ Son skills pesados cuyas ejecuciones no solicitadas costaban más de lo que rendían: ósmosis observada en el mundo real por el propio proveedor y corregida quitando la activación en vez de reescribir la descripción.

Así que una descripción sobredimensionada cuesta dos veces. Consume presupuesto que otros skills necesitan para enrutar, y ejerce una presión sobre el comportamiento que nadie pidió. Ambos costos caen en turnos donde el skill no aporta nada.

La parte incómoda: puede que el cuerpo tampoco gobierne

«Muévelo al cuerpo» es el consejo que acabo de dar, y trae consigo un supuesto que conviene decir en voz alta: que un procedimiento que el agente carga al invocarlo realmente gobierna lo que el agente hace. Un nuevo trabajo de benchmark sugiere que ese supuesto es más débil de lo que parece.

HANDBOOK.md probó exactamente eso. Sesenta y cinco tareas, documentos de políticas de 20 a 124 páginas, agentes trabajando con correo, chat, calendarios y comercio en empresas simuladas, con 824 criterios de evaluación programáticos. La mejor de treinta configuraciones de modelos aprobó el 36.2% de los intentos, y la mayoría de las configuraciones de frontera quedó por debajo del 25%.⁹

Los modos de falla que nombran son los que importan aquí. Los agentes dejan que una solicitud plausible del entorno anule la política vigente. Ejecutan una verificación obligatoria y luego actúan en contra de su resultado. Pierden detalles de las reglas en horizontes largos. Ninguna de esas fallas es de recuperación de información; el documento estuvo disponible todo el tiempo.

Así que la versión honesta de mi regla es más estrecha que «las descripciones enrutan, los cuerpos explican». Sacar el procedimiento de la descripción sigue siendo correcto, porque recupera presupuesto que otros skills necesitan para enrutar y evita que un texto nunca invocado dirija el comportamiento. Ambas cosas son ganancias reales y ninguna depende de que el cuerpo gobierne bien. Lo que no te compra es la confianza de que el procedimiento reubicado se vaya a seguir. Un manual de 124 páginas y un cuerpo de SKILL.md de 3,000 palabras están en la misma curva.

La lectura práctica: trata la longitud del cuerpo como un costo, no como un estacionamiento gratuito. Si una regla de verdad tiene que cumplirse, una descripción es el lugar equivocado para ella y un cuerpo largo es apenas un poco mejor. La aplicación de las reglas pertenece a algo determinista (un hook, una regla de permisos, una prueba), no a una prosa que le pedimos a un modelo recordar mientras hace otra cosa.

Auditar los tuyos

Empieza dentro de una sesión. Ejecuta /context, que reporta si algún skill quedó excluido.⁵ Si marca exclusiones, tienes el problema y ya terminaste de diagnosticar.

La razón por la que yo no empecé ahí es instructiva: mis cinco skills no estaban excluidos, llegaban con el nombre intacto y la descripción despojada, que es una falla más silenciosa que una entrada ausente y puede no manifestarse igual. Así que verifica contra tu sistema de archivos de todos modos. La comprobación no necesita más herramientas que una shell:

python3 - <<'PY'
import os, re, glob
rows = []
for f in glob.glob(os.path.expanduser('~/.claude/skills/*/SKILL.md')):
    name = os.path.basename(os.path.dirname(f))
    fm = re.match(r'^---\s*\n(.*?)\n---\s*\n', open(f, encoding='utf-8', errors='replace').read(), re.S)
    if not fm:
        continue
    d = re.search(r'^description:\s*(.*?)(?=\n[a-zA-Z_-]+:|\Z)', fm.group(1), re.S | re.M)
    if not d:
        continue
    desc = ' '.join(d.group(1).split()).strip('"\'').lstrip('|').strip()
    rows.append((len(desc), name))
rows.sort(reverse=True)
print(f'{len(rows)} skills, {sum(r[0] for r in rows)} description chars')
for length, name in rows[:15]:
    print(f'  {length:4d}  {name}')
PY

Después compara la salida con lo que tu modelo recibió de verdad. La brecha entre ambas cosas es todo el hallazgo. Si un skill aparece en tu contexto con un nombre y ninguna oración después, ese skill está instalado y es inalcanzable.

De la auditoría se desprenden tres hábitos:

Presupuesta cada skill nuevo, no solo los largos. La sobrecarga por entrada viaja con cada skill sin importar la longitud de la descripción, así que el décimo skill de 90 caracteres cuesta más de 90 caracteres.

Vuelve a contar después de agregar skills. No puedo darte un margen seguro, porque el techo no está documentado y, según los reportes, varía según cómo se calcule la fracción.³⁴ Una comprobación empírica le gana a un número de holgura calculado que descansa sobre una suposición, que es exactamente el error que cometí.

Haz una copia antes de recortar. La mayoría de mis directorios de skills no estaban bajo control de git, y siete eran enlaces simbólicos a un directorio que ni siquiera era un repositorio, así que git add los rechazó con «beyond a symbolic link». Primero escribí cada descripción original en un archivo JSON. Un control de versiones que no has verificado no es un respaldo.

Puntos clave

• Un skill sin descripción no está degradado, está inalcanzable. La descripción carga con toda la decisión de enrutamiento.
• La falla es silenciosa por construcción. Ningún error, ninguna advertencia, ningún log. Ejecuta /context para ver advertencias de exclusión y luego compara el listado de tu contexto con tu sistema de archivos, porque una descripción despojada es más silenciosa que una entrada ausente.
• Lo que provoca el descarte es el tamaño agregado, no las propiedades por archivo. Ningún atributo del archivo individual predijo qué skills perdieron su descripción.
• Cuando la inspección falla, interviene. No pude encontrar el mecanismo examinando la falla. Cambiar el total y ver cómo la falla se revertía lo demostró en un solo paso.
• Las descripciones enrutan; los cuerpos explican. Todo lo que en una descripción no ayuda a decidir cuándo invocar se paga en cada turno y no rinde nada.
• Los imperativos en las descripciones actúan sobre ti sin ser invocados. ALWAYS y NEVER dirigen el comportamiento desde el catálogo, que es el efecto de ósmosis medido.¹
• No publiques un porcentaje que no puedas sustentar. Mi propio primer borrador multiplicó una medición real por un presupuesto adivinado y produjo un número seguro de sí mismo y equivocado.

Preguntas frecuentes

¿Por qué no se activa mi skill de Claude Code?

Revisa si el modelo alcanza a ver su descripción. Las descripciones de skills se cargan en el contexto de cada turno y comparten un presupuesto fijo de caracteres, y superarlo descarta descripciones en silencio, sin error, sin advertencia y sin línea de log. Cinco de mis 84 skills llegaban al modelo como nombres sueltos mientras sus archivos en disco tenían descripciones perfectamente válidas. Un skill sin descripción no puede recibir enrutamiento.¹²

¿Cuál es el presupuesto de descripciones de skills en Claude Code?

El presupuesto exacto no está documentado y hoy se discute, y no voy a publicar un número que no puedo sustentar en una fuente. Lo que medí: 21,848 caracteres de descripciones descartaron cinco descripciones, y 9,885 caracteres no descartaron ninguna. Las mediciones de la comunidad sitúan el techo práctico cerca de los 15,500 a 16,000 caracteres, con unos 109 caracteres de sobrecarga por entrada, y colaboradores de Anthropic reportan que la fracción del presupuesto se calcula contra una base fija de 200K.³⁴⁶

¿Cómo audito cuáles de mis skills perdieron su descripción?

Empieza dentro de una sesión con /context, que reporta si algún skill quedó excluido. Después verifica contra tu sistema de archivos de todos modos, porque mis cinco no estaban excluidos: llegaban con el nombre intacto y la descripción despojada, una falla más silenciosa que una entrada ausente. Suma los caracteres de descripción en el frontmatter de tus archivos SKILL.md y compara esa lista con lo que tu contexto muestra en realidad.⁵

¿Qué va en la descripción de un skill y qué en el cuerpo?

El único trabajo de una descripción es responder cuándo debe invocarse el skill. Conserva las palabras disparadoras, los nombres y los comandos slash que un usuario escribiría de verdad, y mueve el procedimiento, la filosofía y las rutas de archivos al cuerpo, que solo se carga al invocarlo. Mi descripción de jiro pasó de 686 caracteres a 126 con el mismo comportamiento de enrutamiento, porque unos 500 de esos caracteres solo explicaban qué contiene el skill.

¿Las descripciones de skills afectan el comportamiento incluso cuando el skill nunca se ejecuta?

Sí, y ese es el segundo impuesto. Once de mis descripciones cargaban ALWAYS, NEVER, MUST, PROACTIVELY y BEFORE, palabras que están en el contexto en cada turno y se leen como instrucciones porque están escritas como instrucciones. «The Regression Tax» le pone nombre al efecto: ósmosis de descripciones de skills, un skill que cambia el comportamiento del agente solo por estar presente en el contexto, incluso sin ser invocado nunca.¹

Referencias