/skill-doctor es un comando de Claude Code que muestra cuánto contexto ocupa cada una de tus skills y con qué frecuencia se usan, para que decidas cuáles apagar. Llegó en el resumen de la semana del 31 de agosto al 4 de septiembre de 2026 y requiere la versión 2.1.252 o posterior. Si has ido acumulando skills y plugins, es la forma más rápida de limpiar el listado.
Qué cambió y por qué importa
Cada skill que Claude Code tiene disponible deja su nombre y su descripción en el contexto de la conversación, en cada turno, la uses o no. El cuerpo completo del SKILL.md solo se carga cuando la skill se invoca, pero la descripción siempre ocupa sitio. Con dos o tres skills no se nota; con decenas (propias, de proyecto y de plugins) el listado empieza a comerse contexto que podría usarse para tu código.
Según la documentación oficial, cuando hay demasiadas skills el listado recorta descripciones, empezando por las de las skills que menos se invocan. Es decir: una skill que no usas puede estar empujando fuera la descripción de otra que sí te importa. /skill-doctor te da la visibilidad para decidirlo con datos en lugar de a ojo.
Requisitos
- Claude Code v2.1.252 o posterior (compruébalo con
claude --versiony actualiza si hace falta). - Una sesión local en tu terminal: por Remote Control el comando responde que los informes de uso de skills no están disponibles en esa conexión.
- Una sesión que obtenga los feature flags de forma normal: la documentación indica que no funciona si esa obtención se omite.
El informe cubre las skills de tu sesión, pero no las incluidas con Claude Code (bundled) ni las de empresa (enterprise). Eso es lo que puedes gestionar tú, que es justo lo interesante.
Paso a paso
1. Abre el informe
Dentro de una sesión interactiva escribe:
/skill-doctorEl informe se abre en la pestaña Stats del gestor /plugin. Si lo necesitas en un script o en CI, usa el modo no interactivo, donde el informe se imprime como texto:
claude -p "/skill-doctor"Ojo: la documentación que leí no detalla las columnas exactas del informe ni da un ejemplo de salida, y tampoco fija desde cuándo una skill cuenta como «nunca usada». Por eso no voy a describirte columnas que no puedo verificar; lo que sí dice es que muestra el coste en contexto y la frecuencia de uso de cada skill, y que marca las que nunca se han invocado e indica dónde desactivarlas.
2. Interpreta lo que ves
La recomendación oficial es empezar por las skills con mayor coste de contexto. Una forma razonable de ordenar tus decisiones:
| Situación | Qué hacer |
|---|---|
| Coste alto y uso frecuente | Déjala; si puedes, acorta su description y when_to_use poniendo el caso de uso clave primero. |
| Coste alto y nunca invocada | Candidata principal a apagar o borrar. |
| Coste bajo y nunca invocada | Revísala sin prisa; el ahorro es pequeño. |
| Skill que solo quieres lanzar a mano | Pon disable-model-invocation: true para que su descripción salga del contexto. |
La tabla es una guía mía de lectura, no un criterio oficial: la documentación no define umbrales.
3. Apaga o elimina lo que sobra
Tienes varias palancas, según el origen de la skill. Para una skill que invocas solo tú, añade esto al frontmatter de su SKILL.md:
---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
---Con eso Claude deja de invocarla por su cuenta y su descripción sale del contexto; tú sigues pudiendo llamarla con /deploy. Atención: user-invocable: false hace lo contrario (solo la invoca Claude) y su descripción sigue ocupando contexto.
Para controlarlo desde los ajustes, la documentación describe skillOverrides, con valores como "name-only" (deja solo el nombre) u "off" (la oculta):
{
"skillOverrides": {
"legacy-context": "name-only",
"deploy": "off"
}
}Si la skill es tuya o del proyecto, puedes borrar su carpeta (~/.claude/skills/<nombre>/ o .claude/skills/<nombre>/). Si viene de un plugin, desactiva o desinstala el plugin con /plugin uninstall <plugin>@<marketplace>. Las skills sincronizadas desde tu cuenta de claude.ai no se pueden editar en local: los cambios se pierden en la siguiente sincronización, así que se cambian en claude.ai.
Costos y seguridad
La documentación no habla de un coste económico del comando; lo que se gana al limpiar es contexto disponible en cada turno. Antes de borrar nada, haz copia de la carpeta o revisa el control de versiones: si una skill de proyecto está versionada, borrarla afecta a todo tu equipo. Y desinstalar un plugin elimina todas sus skills de una vez, no solo la que no usabas.
Para ajustar el presupuesto del listado, la documentación menciona skillListingBudgetFraction y skillListingMaxDescChars, además del tope de 1.536 caracteres por entrada entre description y when_to_use. Con /doctor ves una estimación del coste del listado y con /context el tamaño de la fila de skills.
Qué significa para quien programa con IA
Cuanto más armas tu entorno (instrucciones en CLAUDE.md, plugins, skills propias), más importa mantenerlo ligero. Piensa en /skill-doctor como una revisión periódica, parecida a limpiar dependencias de un proyecto: cada cierto tiempo, mira qué no usas y quítalo. Si además publicas plugins, combínalo con claude plugin eval para comprobar que lo que dejas instalado de verdad aporta algo. Y si estás construyendo tus propios agentes, la lección es la misma que en este agente en Python sin frameworks: el contexto es un recurso limitado y conviene gastarlo con intención.
Una nota de honestidad: esta novedad es de principios de septiembre de 2026, no de esta semana, y el resumen oficial más reciente que encontré al preparar esta guía seguía siendo de esa época.
Preguntas frecuentes
¿Cuánto contexto ocupan realmente mis skills?
Depende de cuántas tengas y de la longitud de sus descripciones. La documentación fija un tope de 1.536 caracteres por entrada y un presupuesto que escala con la ventana de contexto del modelo. /skill-doctor y /context te dan tus números concretos.
¿Borrar una skill sin usar es seguro?
Para skills personales o de proyecto es reversible si guardas la carpeta o usas git. Si dudas, empieza con "name-only" u "off" en skillOverrides en vez de borrar.
¿Funciona con Remote Control o en CI?
En Remote Control no: ejecútalo en la terminal de la máquina donde corre la sesión. En scripts puedes usar el modo -p, que imprime el informe como texto.
Fuentes
- Claude Code: novedades de la semana 36 (31 ago – 4 sep 2026)
- Documentación oficial de skills: encontrar skills sin usar
- Claude Code: resumen semanal de novedades
Última revisión: 12 de noviembre de 2026. Este artículo fue preparado con ayuda de IA; consulta cómo usamos la IA. Los comandos y ajustes provienen de la documentación oficial de Claude Code y no se ejecutaron para esta guía.
