Tenía 56 Agentes de IA Instalados. Estaba Usando Uno.

Durante semanas tuve la misma sensación incómoda con mi configuración de IA: a veces Claude Code elegía al especialista equivocado para la tarea. Nada catastrófico. El trabajo salía. Pero cada tanto una petición aterrizaba en un lugar extraño y yo no sabía explicar por qué. Soy diseñador de producto, no developer, así que mi primer instinto fue asumir que había configurado algo mal y que un ingeniero de verdad lo detectaría en cinco minutos.

Entonces hice lo que debí hacer desde el principio: dejé de adivinar y pedí evidencia. Lo que encontré no era un bug de routing. Era un problema de inventario. Tenía 56 agentes de IA instalados y, en cinco semanas y media de trabajo diario, exactamente uno de ellos se había usado. Una vez.

Este post es la historia de cómo pasó eso, cómo lo limpié sin romper nada y el método que salió de ahí. Si usas Claude Code, Cursor o cualquier herramienta de IA que te deja instalar “packs” de agentes y skills, hay bastantes probabilidades de que tu setup se parezca al mío. La buena noticia: el arreglo cuesta casi nada y se paga solo de inmediato, en mejores resultados y en menos tokens.

1. El Vocabulario, Antes de la Historia

Si ya vives dentro de Claude Code, salta esta sección. Si eres diseñador o PM y trabajas con herramientas de IA pero nunca abriste estas carpetas de configuración, aquí está todo lo que necesitas en cuatro definiciones.

Los agentes son especialistas a los que puedes delegar trabajo. Piénsalos como freelancers con contrato: un investigador, un copywriter, un revisor de QA. Cada uno es apenas un archivo de texto con dos partes: una descripción de cuándo usarlo y las instrucciones de cómo se comporta. Cuando le pides algo a Claude, un router lee las descripciones de todos los agentes instalados y decide quién se queda con el trabajo.

Las skills son manuales reutilizables. Donde un agente es un quién, una skill es un cómo: un procedimiento documentado para una tarea repetible, como “publicar un post” o “auditar un archivo de Figma”. Se cargan en la memoria de trabajo de la IA solo cuando son relevantes, y eso importa más de lo que parece.

Los hooks son barreras automatizadas. Scripts pequeños que se disparan antes o después de acciones específicas y pueden bloquearlas. Los míos incluyen uno que detiene cualquier comando que escribiría en un servidor de producción y otro que se niega a dejar que Claude diga “listo, funciona” si editó código sin correr una sola verificación. Los hooks son la diferencia entre una regla que a la IA se le pide cumplir y una regla que no puede romper.

Los plugins son paquetes que traen agentes, skills y hooks juntos. Una instalación, muchas piezas.

[!info] El único concepto técnico que explica todo lo demás en este post: cada vez que envías un mensaje, la IA vuelve a leer su contexto de trabajo completo desde cero. Tus reglas, cada descripción de agente, cada definición de herramienta, toda la conversación hasta ese punto. Es como reabrir el archivo completo de Figma con 195 pantallas cada vez que quieres mover un botón. La pantalla que estás tocando es barata. El archivo es caro.

Esa relectura es la razón por la que el inventario importa. Cada agente instalado aporta su descripción a ese contexto en cada mensaje, se use o no. Pagas por el desfile aunque nadie marche.

2. Cómo Llegaron 56 Agentes a Mi Setup

Aquí viene la parte vergonzosa, y sospecho que es la más común.

En marzo instalé un pack público de agentes desde GitHub. Ya los has visto: colecciones bellamente organizadas con carpetas para ingeniería, diseño, marketing, testing, gestión de proyectos. Cincuenta y seis especialistas, un comando, capacidad instantánea. Se sintió como contratar un estudio entero gratis.

Nunca volví a mirar esa carpeta. Los agentes eran globales, o sea que aplicaban a todos los proyectos de mi máquina: el trabajo de clientes, mis sitios personales, todo. Y como el trabajo seguía saliendo, asumí que estaban ayudando.

Cuando el routing empezó a sentirse raro, le pedí a Claude Code una auditoría de solo lectura de mi propia configuración. Sin arreglar nada. Solo que me dijera qué tenía instalado de verdad y dónde se solapaban las descripciones. El reporte volvió con hallazgos que cualquier persona de producto reconocerá como un olor a mal diseño:

• Dos agentes tenían descripciones idénticas byte por byte pero permisos distintos. Uno podía consultar bases de datos, el otro no. Cuál de los dos atendía una petición de datos era literalmente cara o cruz.
• Un agente se describía para un stack tecnológico que no uso. Su descripción abría con “implementación premium” y “CSS avanzado”, que son imanes para cualquier petición de UI, y luego especificaba un framework que no existe en ninguno de mis proyectos.
• La descripción de un agente no era una descripción. Era una instrucción: “Eres el líder de este proceso”. Eso no es metadata. Es una postulación de empleo que gana toda petición ambigua.
• Un cuarto del pack jamás podría aplicar a mi trabajo. Seis agentes de desarrollo en VR. Ocho de marketing en redes sociales. Ruido puro en cada decisión de routing.

[!warning] El router solo lee descripciones. Ni las instrucciones completas del agente, ni tus reglas de proyecto, ni tu intención. Si dos descripciones se solapan, la elección entre ellas es intuición. Este es el dato más útil que aprendí en todo el proceso, y ninguna guía de instalación lo menciona.

3. Evidencia Antes que Opinión

La auditoría mostró que la configuración estaba desordenada. No mostró si ese desorden realmente me estaba perjudicando. Son preguntas distintas, y confundirlas es la forma en que las limpiezas se convierten en reescrituras que rompen cosas.

Así que antes de tocar nada, fui por los datos de uso. Claude Code guarda transcripts de tus sesiones, y esos transcripts registran cada vez que se delegó trabajo a un agente. Un escaneo de cinco semanas y media de historial produjo el número que replanteó todo:

De 56 agentes instalados, 55 tenían cero invocaciones. El número 56 tenía una, un día que lo llamé explícitamente por su nombre para una propuesta de diseño visual.

Mientras tanto, el agente generalista que viene de fábrica había absorbido 40 delegaciones entre todos mis proyectos. Mi sospecha de “a veces elige al especialista equivocado” estaba mal de la forma más interesante posible. Casi nunca elegía a un especialista. Todo caía por defecto en el generalista, que hace todo aceptablemente y nada excelentemente, mientras yo pagaba el costo de contexto de 56 descripciones en cada mensaje por el privilegio.

Repetí el mismo análisis con mis skills. Treinta y cinco instaladas. Tres con algún uso registrado. El patrón se sostuvo en aproximadamente 90% de peso muerto en ambas capas.

[!important] Cuenta el uso antes de juzgar el valor. Los nombres y las descripciones te dicen qué dice hacer algo. Los transcripts te dicen qué pasó de verdad. En mi caso, la intuición decía “mal routing entre especialistas” y los datos decían “ningún routing”. Cada decisión que tomé después fue mejor porque descansaba en la segunda respuesta, no en la primera.

Una advertencia honesta que pertenece a cualquier historia con datos: los transcripts se retienen solo por una ventana limitada, 30 días por defecto. “Cero uso registrado” significa cero uso en la ventana visible, no cero jamás. Esa distinción cambió cómo hice la limpieza, y eso me lleva al método.

4. Archivar, Nunca Borrar

La limpieza siguió tres reglas, y cada una existe porque saltármela me habría costado caro.

Regla uno: todo se mueve, nada muere. Creé una carpeta de archivo junto a la carpeta de agentes y moví los 56 archivos ahí. Claude Code no escanea el archivo, así que dejaron de competir al instante, en todos los proyectos a la vez. Pero están a un arrastrar y soltar de volver. Dado el punto ciego de 30 días en mis datos de uso, borrar habría sido arrogante. Archivar es humildad reversible.

Regla dos: un humano aprueba cada fase. Corrí toda la limpieza a través del propio Claude Code, pero con un checkpoint duro escrito en las instrucciones: muéstrame el plan completo y espera mi visto bueno explícito antes de escribir nada. Esto importa el doble si tu setup corre en un modo permisivo donde la IA no pregunta antes de actuar. El mío lo hacía. El checkpoint en el prompt era la única puerta de aprobación que existía.

Regla tres: cada fase termina con un reporte de tres partes. Qué cambió, con conteos exactos. Cómo se verificó, con output real en lugar de promesas. Y qué queda sin probar, declarado sin que nadie lo pida. Esa tercera sección suena a burocracia y resultó ser el texto más valioso de todo el proyecto. Es donde la IA me dijo cosas como “verifiqué que los archivos se movieron, pero no verifiqué que la app dejó de verlos; eso requiere un reinicio que solo tú puedes hacer”.

Las reglas se ganaron su lugar casi de inmediato, en dos momentos que no vi venir.

El primero: 21 de mis 35 skills resultaron no ser carpetas. Eran enlaces, gestionados por una herramienta externa que sincroniza la misma biblioteca de skills hacia una docena de aplicaciones de IA distintas. Moverlos como carpetas normales habría roto la biblioteca para todas las demás herramientas de mi máquina, o borrado archivos compartidos en silencio. La regla de planear antes de tocar lo detectó, y el arreglo se volvió quirúrgico: registrar cada enlace en un manifiesto, quitar solo el enlace, jamás tocar el destino. Verificado después confirmando que la carpeta destino tenía exactamente el mismo conteo de archivos que antes, archivo por archivo.

El segundo momento es mi favorito. En un punto le pedí a la IA que marcara como resuelta una contradicción documentada. Fue a verificar primero, encontró que la contradicción seguía siendo cierta y se negó. Marcarla como resuelta habría escrito una mentira dentro de la auditoría. Un checkpoint que solo sabe decir que sí no es un checkpoint. Este me contradijo, y tenía razón.

5. Reconstruir Bien a los Sobrevivientes

Un agente volvió del archivo, y reconstruirlo me dejó la lección más de diseñador de todo el proyecto.

La descripción de un agente es UX writing para una audiencia de exactamente un lector: el router. Todo lo que sabes de microcopy aplica directo. Las frases de activación son las palabras reales del usuario real. La cláusula de exclusión es el estado de error. La ambigüedad es el costo.

Mi primer borrador de la nueva descripción usaba frases que yo imaginaba que diría. La mejor versión, y no estuvo cerca, se construyó con frases que yo había dicho de verdad, citadas del transcript de la única vez que usé el agente. Cosas como “esto se ve como una nota legal pegada sin cuidado” y “la copy está aprobada, cambia solo cómo se ve”. La investigación real le gana a las personas inventadas. Esto ya lo sabes del trabajo de producto. Aquí es exactamente igual de cierto.

La descripción reconstruida sigue una plantilla que puedes robarte:

Usar cuando [frases que el usuario dijo de verdad, citadas del historial]. NO usar para [la confusión más probable que queda después de la limpieza]. En mi caso: este agente propone diseños visuales, nunca los implementa. La cláusula negativa no es decoración. Es la frontera que impide que el generalista y el especialista reclamen la misma petición.

Ya que estaba, cada pieza sobreviviente recibió una asignación de modelo: modelos baratos y rápidos para trabajo mecánico como buscar, gama media para implementación bien especificada, los caros reservados para decisiones de criterio. Antes de la limpieza, esa tabla de routing existía en mi archivo de reglas como un deseo. Ningún agente declaraba un modelo, así que nada la hacía cumplir. Ahora es una línea por archivo, y es la parte de este proyecto que más directamente se nota en la factura.

6. Qué te Compra Esto, en Términos de Producto

Déjame traducir el resultado fuera del lenguaje de configuración.

Antes: 56 agentes y 35 skills cargando sus descripciones en cada conversación, cerca del 90% de ellos sin uso registrado. Peticiones cayendo por defecto en un generalista. Un archivo de reglas con contradicciones que la IA resolvía a cara o cruz. Cero medición de todo eso.

Después: un agente con una descripción construida a partir de uso real, cinco skills que se ganan su lugar, plugins desactivados por proyecto donde no aplican, y un pequeño hook de logging que registra cada decisión de routing en un archivo. Esa última pieza es la victoria silenciosa. La próxima vez que sienta esa comezón de “algo anda raro”, no tendré que adivinar. Dos o tres semanas de logs la responderán con conteos.

La economía se acumula de una forma fácil de pasar por alto. Un contexto más limpio no solo cuesta menos tokens por mensaje. Reduce la cantidad de mensajes, porque la IA deja de “olvidar” instrucciones que estaban enterradas bajo el ruido, lo que significa menos rondas de corrección, que es donde se esconde el gasto real. Pagar menos por turno mientras tomas menos turnos: ese es todo el juego.

[!quote] La ventana es un presupuesto, no un balde. Cada cosa instalada gasta de ahí en cada mensaje, se use o no.

Y hay un argumento de calidad que no tiene nada que ver con dinero. Mi proyecto más sensible es un producto de agendamiento médico. Cuando una IA olvida una regla en un archivo de diseño, yo pierdo tiempo. Cuando olvida una regla en lógica que toca al paciente, alguien pierde una cita. Ahí la verificación y el routing limpio no son optimización. Son el piso.

7. Corre Esto en tu Propio Setup

No necesitas toda mi saga para conseguir la primera victoria. Tres pasos, en orden, y el primero toma diez segundos.

Mide. Abre Claude Code en tu proyecto más activo y corre /context. Muestra exactamente qué se carga en la ventana antes de que escribas una palabra: cuánto se va en definiciones de herramientas, cuánto en reglas, cuánto ya está gastado. Ese número es tu factura desglosada. La mía era fea.

Audita en solo lectura. Pídele a la IA que inventaríe tus agentes, skills y plugins, que marque los solapamientos de descripciones y que revise tus transcripts de sesión para sacar conteos reales de uso. Prohíbele explícitamente arreglar nada en esta pasada. Diagnóstico y tratamiento en el mismo paso es la forma en que las limpiezas rompen cosas.

Archiva por evidencia. Mueve lo que no tiene uso registrado a una carpeta de archivo. Conserva lo que los datos defienden, más lo que decidas respaldar conscientemente. Reescribe las descripciones de los sobrevivientes con tus frases reales. Cero sobrevivientes es un resultado válido; solo significa que el generalista fue todo tu equipo desde siempre, y ahora lo sabes.

La parte incómoda de esta historia nunca fue técnica. Fue admitir que había instalado capacidad como se instala abundancia: porque era gratis, porque se sentía como prepararse, porque más especialistas seguramente significaban más capacidad. Significaban lo contrario. Lo mejor que hice por mis herramientas de IA este año fue restar, midiendo dos veces.

8. Róbate la Skill

Después de la limpieza hice lo más natural para alguien que acaba de aprender un procedimiento repetible: convertí el método mismo en una skill. Un archivo, y Claude Code corre toda la auditoría por ti, con fases, checkpoints y todo. Aquí está, condensada. Guárdala como ~/.claude/skills/claude-detox/SKILL.md e invócala con /claude-detox, o simplemente dile a Claude “audita mi setup”.

---
name: claude-detox
description: >-
  Audita y limpia una configuración de Claude Code saturada de agentes,
  skills, plugins, MCPs y reglas que nadie usa. Usar cuando el usuario diga
  "Claude elige mal el agente", "tengo demasiados agentes", "mi contexto se
  llena de basura", "instalé un pack y ahora todo es ruido", "audita mi
  setup", "por qué gasto tantos tokens", o en inglés "clean up my Claude
  Code config", "too many agents". Funciona por fases con evidencia real
  de uso, archiva en vez de borrar, y exige aprobación humana por fase.
---

# claude-detox

## Las cinco reglas que gobiernan todo

1. **Evidencia antes de opinión.** Nunca propongas qué conservar por
   nombres o descriptions. Los transcripts en `~/.claude/projects/`
   registran qué se invocó de verdad. Declara siempre la ventana de
   retención (30 días por defecto): "cero uso registrado" significa cero
   en la ventana visible, no cero absoluto.
2. **Archivar, nunca borrar.** Todo va a una carpeta `-archive` hermana.
   Mover, no eliminar. El rollback debe ser arrastrar de vuelta.
3. **Checkpoint humano por fase.** Plan completo y aprobación explícita
   antes de escribir, ESPECIALMENTE si detectas bypassPermissions: ahí el
   checkpoint del prompt es la única aprobación que existe. Funciona en
   ambas direcciones: si el usuario pide algo que la evidencia contradice,
   díselo en vez de obedecer.
4. **Reporte en tres partes.** Qué cambió (conteos exactos), cómo lo probé
   (output real), qué queda sin probar (declarado sin que lo pidan). La
   tercera sección es la más valiosa.
5. **Instrumentar antes de limpiar.** Instala un hook de logging en
   SubagentStart/Stop que registre cada elección en routing.jsonl, para
   que los datos midan el sistema nuevo desde el día uno.

## Las fases

- **Fase 0, inventario (solo lectura):** agentes, skills, plugins, hooks,
  MCPs, CLAUDE.md y contradicciones entre ellos. Fechas de archivos
  idénticas delatan packs de terceros; una fecha distinta delata trabajo
  del usuario que NO se mueve sin que lo vea. Análisis de solapamiento:
  por cada par de descriptions que se pisen, una frase concreta que el
  usuario diría y qué agentes competirían. Todo a un archivo
  auditoria-claude-code.md, dirigido a la persona, no a un developer.
- **Fase 1, instrumentación con red:** backup del settings antes de
  tocarlo, hook de logging, validación post-escritura del JSON, y prueba
  en rojo: sabotea una COPIA del hook para confirmar que la diferencia es
  detectable. Nunca el script vivo. Borra los artefactos al terminar.
- **Fase 2, archivar con evidencia:** entra a la lista de conservación
  solo lo que tiene uso registrado o lo que el usuario confirme. Cero es
  válido. VERIFICA si algo es junction/symlink antes de mover: si lo es,
  manifiesto + quitar solo el enlace, jamás tocar el destino, y confirmar
  que el conteo de archivos del destino no cambió.
- **Fase 3, reconstruir lo que vuelve:** description como contrato de
  routing: "Usar cuando [frases reales citadas de transcripts]. NO usar
  para [la confusión más probable]". Asigna model leyendo el cuerpo, no
  el nombre. Kebab-case. Verifica con hash que el cuerpo quedó intacto.
- **Fase 4, configuración por proyecto:** lo que estorba en un proyecto
  se apaga en su settings.local.json, no se archiva global.
- **Fase 5, cierre:** comandos de verificación re-ejecutables, rollback
  por fase, cabos sueltos nombrados, advertir si ~/.claude se sincroniza
  a otra máquina, y prescribir 2-3 semanas de trabajo normal antes de
  leer routing.jsonl. La limpieza responde "qué sobra"; solo el log
  responde "qué falta".

## Trampas conocidas

- CLAUDE.md es contexto, no configuración: no garantiza cumplimiento.
- El router solo lee la description. Reglas de routing en CLAUDE.md son
  reglas que el router no ve.
- Si el 90% del uso cae en general-purpose, el problema no era misrouting:
  era pagar especialistas que nunca jugaron.
- Memorias que citan flujos retirados envenenan auditorías futuras:
  corrige la memoria, no el documento.
- Herramientas de conteo mienten distinto (líneas vacías, newlines):
  verifica números importantes con una segunda fuente.
- Artefactos de prueba con nombres alarmantes: bórralos al terminar y
  documenta qué fueron, con cronología.

La versión completa, con los scripts de logging listos para usar en Windows y macOS/Linux incluidos, vive en el paquete descargable de la skill enlazado al inicio de este post. Pero el bloque de arriba está lo bastante completo para correrlo: el método es el valor, y el método cabe en dos pantallas.

Una nota sobre por qué las propias reglas de la skill moldearon cómo se construyó. Cuando la empaqueté, probé el script de logging “en rojo” como exige la regla 5, alimentándolo deliberadamente con basura para confirmar que falla en silencio. La prueba en rojo cazó dos bugs reales antes de que nadie más lo corriera. Una skill sobre verificación que se publica sin verificar habría sido un chiste.

Tu setup está tomando decisiones de routing ahora mismo, en cada mensaje, basadas en descripciones que nunca has leído. Ve a leerlas. Cuenta lo que de verdad usas. Apostaría a que tu proporción aterriza cerca de la mía.