/skill-doctor: los skills de Claude Code que gastan contexto

Lanzas Claude Code, todavía no has pedido nada, y una parte del contexto ya se ha ido. En la instalación medida aquí, hay 117 skills personales cargados, 108 nunca se han invocado, y su listado vuelve a salir en cada turno de conversación.

Lo que muestra exactamente /skill-doctor

El comando llegó con Claude Code 2.1.261, publicada el 4 de septiembre de 2026. La nota de la versión lo resume en una línea: muestra qué skills cargados no se usan nunca y cuánto cuestan en contexto, para que puedas podarlos.

La documentación precisa el alcance. El informe cubre los skills de tu sesión, salvo los skills incluidos con Claude Code y los skills de empresa. Señala los que nunca se han invocado, indica dónde desactivarlos y de paso lista los plugins que no has usado últimamente. En sesión interactiva, se abre en la pestaña Stats del gestor /plugin; en modo no interactivo, con -p, Claude Code lo imprime como texto.

Dos condiciones que conviene conocer antes de probarlo. Hace falta Claude Code 2.1.252 o más reciente. Y desde Remote Control, en el teléfono o el navegador, el comando se niega a responder: devuelve Skill usage reports are not available on this connection. Ejecútalo en la terminal de la máquina que aloja la sesión.

¿Por qué un skill que nunca se invoca sigue costando contexto?

Porque un skill se carga en tres tiempos. El estándar abierto Agent Skills lo llama divulgación progresiva: al arrancar, el agente solo lee el nombre y la descripción de cada skill; cuando una tarea encaja con esa descripción, lee el cuerpo del SKILL.md; solo abre los archivos anexos si los necesita. El mecanismo se explica en nuestra guía del formato SKILL.md.

El primer nivel, en cambio, se paga en cada turno de conversación. La documentación de Claude Code es clara: cada skill del listado se suma al contexto en cada turno, lo use Claude o no. Y ese listado tiene un presupuesto en caracteres que equivale al 1 % de la ventana de contexto del modelo. Superado ese límite, Claude Code acorta las descripciones para caber en el presupuesto, arriesgándose a borrar justo las palabras clave que activan el skill correcto.

Tener demasiados skills cuesta tokens, entonces, y de paso empeora la activación de los que de verdad querías usar.

El informe, sobre 117 skills

En una instalación que carga 117 skills personales, el comando saca una línea por skill y una frase de conclusión. El modo no interactivo lo imprime en texto plano, lo que permite guardarlo:

claude -p '/skill-doctor'

Skills loaded this session

  skill                      source        context  7d tokens   uses  last used
  ab-test-setup              userSettings     ~270          -     0×  never
  cold-email                 userSettings     ~230          -     0×  never
  …
  seo-onpage                 userSettings     < 20          -     0×  never
  …
  seo-search-console         userSettings     ~190       1.2m     1×  6 days
  seo-keyword-research       userSettings     ~160      15.2m     1×  3 days
  video                      userSettings     ~210     548.4k     4×  3 days
  wp-article-thumbnails      userSettings     ~190      28.5m     8×  today

  context = this skill's one-line listing in the system prompt, included every turn
  (dash = not in the current listing, costs nothing; full SKILL.md loads only when it runs)
  7d tokens = tokens attributed to the skill over the last 7 days of sessions on this machine

108 skills loaded but never invoked. Each one adds to the system prompt every turn.
Disable in /skills, or remove from .claude/skills.

Cuatro columnas soportan la decisión. context da el peso de la línea del listado, la que vuelve a salir en cada turno: de menos de 20 a 360 tokens por skill aquí, unos 8.800 en total. 7d tokens cuenta lo que el skill ha consumido realmente en siete días, y muestra un guion cuando no ha consumido nada. uses y last used dicen el resto: de los 117 skills cargados, 108 nunca se han invocado, y solo cinco han consumido algo durante la semana.

Medirlo sin el comando

En una versión anterior a la 2.1.252, o simplemente para contrastar el orden de magnitud, el nivel 1 se mide directamente en los archivos, ya que no está hecho más que de frontmatter YAML.

# Peso del nivel 1: nombre + descripción de cada skill personal
awk 'FNR==1{f=0;p=0}
     /^---[[:space:]]*$/{f++; next}
     f!=1{next}
     /^[A-Za-z_-]+:/{p=($1=="name:"||$1=="description:"||$1=="when_to_use:")}
     p{c+=length($0)}
     END{printf "%d skills, %d caracteres, ~%d tokens\n", ARGC-1, c, c/4}' \
  ~/.claude/skills/*/SKILL.md
# 117 skills, 45715 caracteres, ~11428 tokens

La estimación «un token por cada cuatro caracteres» da 11.428 tokens allí donde el informe cuenta unos 8.800: se pasa por arriba, lo que basta de sobra para decidir. El mismo cálculo sobre ~/.codex/skills da 7 skills y unos 590 tokens: en esto, los dos agentes no juegan en la misma liga, como muestra nuestra comparativa entre Codex y Claude Code.

El segundo comando saca la clasificación. Con ella basta para decidir.

awk 'FNR==1{if(NR>1) print c, d; c=0; f=0; p=0; n=split(FILENAME,t,"/"); d=t[n-1]}
     /^---[[:space:]]*$/{f++; next}
     f!=1{next}
     /^[A-Za-z_-]+:/{p=($1=="name:"||$1=="description:"||$1=="when_to_use:")}
     p{c+=length($0)}
     END{print c, d}' ~/.claude/skills/*/SKILL.md | sort -rn | head -5
# 1101 elevenlabs-game-music
# 1078 elevenlabs-game-sfx
# 864 directory-submissions
# 855 customer-research
# 831 ab-test-setup

Estos 117 archivos SKILL.md suman 778.142 caracteres, unos 194.500 tokens, y el listado solo representa el 6 % de eso. La divulgación progresiva cumple su función, entonces, y lo que pesa a diario sigue siendo el número de skills. Aun así, 45.715 caracteres están en el orden de magnitud del presupuesto del listado: sin /context es imposible saber si mis descripciones ya están recortadas.

Recortar lo que no sirve

Abre /skills, resalta un skill, pulsa Espacio para recorrer los estados y luego Esc para guardar. El propio menú escribe el ajuste skillOverrides en .claude/settings.local.json. Hay cuatro estados.

name-only es el compromiso adecuado para un skill que invocas tú mismo de vez en cuando: el nombre se queda en el listado, la descripción deja de pesar. off es para los que instalaste «para probar».

Cuidado con los plugins: los skills que trae un plugin no dependen de skillOverrides. Hay que desactivar el plugin desde /plugin y luego ejecutar /reload-plugins, o reiniciar la sesión, para que sus skills se descarguen.

Comprobar que el recorte ha servido

La línea Skills de /context da el tamaño del listado después de aplicar el presupuesto: es exactamente lo que recibe el modelo. Anótala, recorta, reinicia la sesión, anótala otra vez. Si no se mueve aunque hayas desactivado diez skills, probablemente ya estabas en el tope y Claude Code truncaba tus descripciones; aun así, el recorte habrá ganado en precisión de activación.

Para la factura, /cost y /usage siguen siendo la referencia, pero no esperes más que una mejora modesta: el verdadero beneficio se nota en el contexto, no en euros. Si buscas un ahorro de otro orden de magnitud, hay que mirar el enrutado de las lecturas de archivos, como en la experiencia de Spotify con los hooks.

Hay dos ajustes que permiten ampliar el presupuesto en vez de recortar: skillListingBudgetFraction (por ejemplo, 0.02 para el 2 %) y la variable de entorno SLASH_COMMAND_TOOL_CHAR_BUDGET, que fija un número de caracteres. Ampliarlo solo desplaza el problema: el contexto que ganas en skills lo pierdes en otro sitio.

Lo que hay que recordar

• Un skill que nunca se invoca sigue costando su nombre y su descripción en cada turno: es el nivel 1 de la divulgación progresiva.
• /skill-doctor requiere Claude Code 2.1.252 o más reciente, y aparece en la pestaña Stats del gestor /plugin.
• El informe cuenta aquí 117 skills cargados, 108 nunca invocados, unos 8.800 tokens de listado. Dos líneas de awk sobre ~/.claude/skills/*/SKILL.md dan el mismo orden de magnitud sin el comando.
• Se recorta con /skills y la tecla Espacio; los skills de un plugin se recortan desde /plugin y luego /reload-plugins.
• Se comprueba en la línea Skills de /context, que refleja el presupuesto realmente aplicado.