Creamos una skill de disciplina de tokens para Claude Code

Nos pasamos el día midiendo las skills de Claude de otros, y en la telemetría aparecía siempre el mismo patrón: las sesiones que salían caras no se encarecían porque Claude escribiera respuestas largas. Se encarecían por lo que Claude leía. Archivos enteros abiertos para encontrar una sola función. Archivos releídos justo después de una edición exitosa, "solo para verificar". Un JSON de 16.000 registros metido en el contexto como si fuera una entrada de blog.

Así que construimos una skill que ataca justo ese lado de la factura, la publicamos bajo licencia MIT, e hicimos lo que le pedimos a cada skill de nuestro catálogo: la medimos contra una línea base con ejecuciones controladas y publicamos los números — incluidos los que no la dejan bien parada.

La skill se llama token-discipline. Es gratis: github.com/Skillproofdev/token-discipline.

El vacío en todas las skills de tokens que revisamos

Antes de escribir una sola línea, revisamos ocho skills y protocolos publicados para ahorrar tokens — desde el conjunto de reglas de verbosidad de salida con 5.800 estrellas que domina el nicho, hasta skills de "emergencia" que se activan al 40% de contexto, pasando por protocolos que prometen ahorros del 76–93% sin ningún mecanismo detrás ni telemetría que pudiéramos encontrar.

Casi todos comparten el mismo punto ciego: optimizan la salida. Eliminar el preámbulo, acortar las respuestas, dejar de repetir el plan. Eso es real, pero es la mitad más pequeña de la factura. En sesiones de agente — Claude Code haciendo trabajo real en un repositorio — domina la entrada: cada archivo leído, cada resultado de búsqueda, cada salida de herramienta cae en el contexto y se reenvía con cada solicitud posterior.

Tres técnicas del lado de la entrada no aparecían como reglas obligatorias en ninguna de las ocho:

1. Busca antes de leer. Localiza primero con grep/glob y lee solo la región que coincide. Nunca abras un archivo entero para encontrar algo.
2. Agrupa las llamadas a herramientas independientes. Si tres lecturas no dependen entre sí, van en un solo mensaje. Cada turno extra vuelve a pagar tokens de razonamiento y narración entre llamadas.
3. Confía en el estado que ya tienes. Después de tu propia edición exitosa, no releas el archivo para verificar — la herramienta de edición falla de forma ruidosa cuando algo sale mal. Las relecturas son para cambios externos, no para los tuyos.

Esas tres se convirtieron en el núcleo de la skill. Alrededor hay seis reglas más: leer fragmentos en vez de archivos completos, consultar JSON o logs grandes con python o jq en vez de abrirlos, resumir y luego descartar las salidas largas, delegar la exploración amplia a subagentes, mantener el contexto compatible con la caché (prefijo estable intacto — el propio blog de ingeniería de Anthropic llama al prompt caching el factor de coste con más apalancamiento), y sí, también salida concisa. Nueve reglas, cada una formulada como regla dura con una alternativa indicada, de modo que seguirla nunca cuesta corrección.

Cómo lo medimos

Mismo protocolo que nuestra serie Skill Bench: mismo modelo, mismo prompt, una sola variable. Cada tarea se ejecutó dos veces — un agente Claude Sonnet sin skill, y otro que leyó primero el SKILL.md y recibió la instrucción de seguirlo al pie de la letra. Los totales del agente con skill incluyen el coste de leer la propia skill. El banco de pruebas fue nuestro propio codebase: un sitio Astro con unas 9.000 líneas de plantillas más un dataset JSON de 16.682 registros — lo bastante grande como para que leer sin disciplina realmente duela.

Cinco pares de tareas, elegidos para cubrir el espectro entre lo trivial y lo genuinamente multi-paso:

Tarea	Línea base	Con skill	Δ
Preguntas sobre el codebase — 8 preguntas en varios subsistemas	88.419	71.636	−19.0%
Edición multiarchivo — 4 cambios coordinados	68.219	54.637	−19.9%
Rastreo de código — un solo paso	53.986	52.850	−2.1%
Barrido de auditoría — un solo paso	44.691	44.705	+0.0%
Digerir un JSON grande — un solo paso	42.726	45.164	+5.7%

Lo que dicen los números

En trabajo real multi-paso, la skill ahorra alrededor de un 20%. Las 8 preguntas sobre el codebase son lo más parecido a una sesión de trabajo normal — rastrear el flujo de autenticación, explicar el webhook, encontrar la lógica de ordenamiento. El agente base respondió correctamente, pero por el camino leyó de más y verificó de forma redundante. El agente disciplinado respondió las mismas preguntas, con la misma precisión (comprobamos cada referencia file:line de ambos), usando 16.783 tokens menos.

La edición multiarchivo es el resultado más interesante. Cuatro cambios coordinados en cuatro archivos. El agente base terminó y luego — citando su propio informe — "verificó releyendo las regiones editadas". Ese solo hábito es una quinta parte de la factura. El agente con skill aplicó los mismos cuatro cambios, se saltó las relecturas ceremoniales, y reportó que había terminado. Comparamos ambos árboles de trabajo: las ediciones fueron equivalentes y correctas en ambos casos. No se perdió nada por confiar en que la herramienta falle cuando algo sale mal, porque para eso están las herramientas.

En tareas triviales de un solo paso, queda en tablas — y lo publicamos igual. La tarea de digerir el JSON costó en realidad un 5.7% más con la skill. Dos razones, ambas instructivas. Primero, la propia skill cuesta unos 1.400 tokens leerla, y una tarea que termina en dos llamadas a herramientas no le da a ese sobrecoste dónde amortizarse. Segundo, un modelo de la generación actual ya se comporta bien en tareas fáciles: el agente base le echó un vistazo a un JSON de 16.682 registros y fue directo a python en vez de abrirlo. No hizo falta ninguna skill. La disciplina rinde donde la indisciplina es posible — sesiones largas, muchos archivos, contexto que se acumula — no donde no hay nada que desperdiciar.

Si tus sesiones son mayormente de una línea, la skill trae su propia respuesta: un bloque destilado de 60 tokens que pegas en tu CLAUDE.md en vez de instalar la skill completa. Siempre activo, cuesta más o menos lo mismo que esta frase, y con evitar una sola lectura de archivo completo ya se paga muchas veces. (Construimos una calculadora justo para este impuesto de estar siempre activo — la cuenta sobre las descripciones de activación también aplica a los bloques de reglas.)

Las nueve reglas, en breve

El SKILL.md completo tiene ~1.400 tokens y se lee en una sola pantalla; esta es su forma:

1. Busca antes de leer. Primero grep; luego lee el resultado ±30 líneas. Leer más de ~200 líneas exige una razón que puedas expresar en una frase.
2. Lee el fragmento, no el archivo. Offset+limit para todo lo largo; python/jq para todo lo estructurado. Un JSON grande es una base de datos, no un documento.
3. Agrupa las llamadas a herramientas independientes. Un mensaje, varias llamadas, siempre que las salidas de unas no alimenten las entradas de otras.
4. Confía en el estado que ya tienes. Nada de relecturas de verificación después de tus propias ediciones; nada de repetir búsquedas cuyos resultados ya están en el contexto.
5. No repitas código citándolo. Referencia file:line. Pega solo lo que el humano necesita ver para decidir.
6. Resume y luego descarta. Después de una salida larga de herramienta, quédate con los 2–5 datos clave, nunca vuelvas a pedir el log.
7. Delega la exploración pesada. Los barridos amplios van a un subagente; las lecturas pesadas mueren en su contexto, no en el tuyo.
8. Mantén el contexto compatible con la caché. Prefijo estable intacto; añade, no reescribas; presta atención al TTL de la caché.
9. Disciplina en la salida. Responde primero, sin preámbulo, sin ensayos de diff.

Además hay un punto de autoauditoría (tres preguntas antes de cualquier relectura grande) y una lista explícita de cosas que no hacer, porque una skill de tokens que hace que un agente se salte una verificación necesaria no te ahorra nada — solo aplaza el retrabajo. Si una caza de bugs real necesita el archivo entero, la regla dice que lo leas, con la razón indicada.

Dónde encaja esto en el panorama de costes más amplio

Reglas como estas son la mitad variable de tu factura. La mitad fija — el preámbulo de 30.000 tokens de servidores MCP, los archivos CLAUDE.md hinchados y las descripciones de skills siempre activas que se reenvían literalmente con cada solicitud — es un problema distinto con arreglos distintos, y suele ser la ganancia mayor para los usuarios intensivos. Escribimos esa auditoría en Cómo reducir los costes de tokens de Claude Code; las dos piezas son complementarias: arregla los costes fijos una vez, y luego deja que token-discipline mantenga planos los costes variables durante toda la sesión.

Y si te preguntas si las skills en general ahorran tokens: nuestra serie Skill Bench midió cuatro skills populares y descubrió que en su mayoría no lo hacen — cuestan tokens extra y a cambio compran calidad y disciplina. token-discipline se construyó específicamente para ser la excepción, y aun así solo se gana el sustento en trabajo multi-paso. Ese es el límite honesto, y preferimos trazarlo nosotros antes de que lo encuentres tú en tu factura.

Instalación

git clone https://github.com/Skillproofdev/token-discipline ~/.claude/skills/token-discipline

Reinicia Claude Code. Se activa con "reducir el uso de tokens", "trabajar con eficiencia de tokens", quejas de límite de contexto y preguntas sobre coste — o aplícalo a toda la sesión con el bloque de CLAUDE.md que incluye.

Preguntas frecuentes

¿Esto reemplaza a las skills de verbosidad de salida? No — incluye su núcleo (la Regla 9) y añade el lado de la entrada que ellas se saltan. Si ya usas un conjunto de reglas de salida concisa, token-discipline se solapa con él en una regla de nueve.

¿Hará que Claude sea más descuidado? El benchmark dice que no: la edición multiarchivo salió equivalente y correcta en ambos lados, y la lista de cosas que no hacer de la skill protege explícitamente la verificación que sí es necesaria. Las reglas reemplazan las lecturas ceremoniales, no las necesarias.

¿Por qué la skill en sí es tan corta? Porque una skill de ahorro de tokens que costara miles de tokens por sesión cargarla sería una autoparodia. El SKILL.md tiene ~1.400 tokens que se cargan bajo demanda; el bloque de CLAUDE.md siempre activo tiene ~60.

Tengo una suscripción Pro/Max, no uso la API. ¿Esto importa? Sí, en la moneda de los límites: los mismos tokens que facturan a los usuarios de la API consumen tus topes de uso. Un 20% menos de tokens en sesiones de trabajo significa proporcionalmente más trabajo antes de chocar con el techo.

¿El benchmark estaba manipulado a propósito? Las cinco tareas se diseñaron antes de ejecutar cualquiera de las dos variantes, y publicamos los dos resultados en los que la skill perdió. La telemetría en bruto — recuentos de tokens y de llamadas a herramientas por ejecución — está en el README del repo.