Por qué Prompt Cache no reduce el costo: diagnostica agentes de código con prompt-cache-skills

Tu factura mensual de Claude Code o Cline puede ser entre un 30 % y un 50 % más alta de lo necesario. Quizá no usas demasiado la API: Prompt Cache puede no estar funcionando.

Muchos agentes de código con IA activan prompt caching por defecto, pero un cambio pequeño de configuración puede invalidar todo el prefijo en caché: una marca de tiempo dentro del system prompt, una cache key mal calculada, un interruptor desactivado o un TTL demasiado corto. Estos problemas no siempre generan errores y la factura tampoco muestra la causa; el costo de API simplemente se mantiene alto.

prompt-cache-skills es una biblioteca de skills drop-in para corregir estos fallos silenciosos. En cargas adecuadas puede elevar la tasa de aciertos desde casi cero hasta un 80 % o más. A continuación se explican la facturación, las cuatro causas principales, correcciones típicas y un método de verificación.

Cómo Prompt Cache ahorra dinero

El principio es sencillo: un prefijo estable puede almacenarse en caché y reutilizarse por mucho menos que procesar de nuevo tokens de entrada normales.

Cada proveedor usa campos de facturación distintos, pero la lógica es la misma:

Tipo de facturación	Comportamiento	Caso adecuado	Proveedor representativo
cache_creation_input_tokens	Crea la caché en la primera solicitud y suele costar más que la entrada normal	Primera solicitud con prefijo largo	Anthropic
cache_read_input_tokens	Un acierto cuesta mucho menos, cerca del 10 % de la entrada ordinaria	Reutilización de un prefijo estable	Anthropic
Tokens de entrada normales	Se cobran a la tarifa habitual	Solicitudes cortas o prefijos que cambian	Todos los proveedores
cached_tokens (OpenAI)	La entrada almacenada reduce su costo cerca del 50 %	Reutilización de un prefijo estable	OpenAI
cached content (Gemini)	Se cobra según el tiempo de almacenamiento	Contextos largos	Google Gemini

Por ejemplo, si un system prompt de Anthropic tiene 2.000 tokens y el mismo agente lo reutiliza 100 veces al día, un acierto factura esos tokens como cache_read, cerca del 10 % de la entrada normal. Esa parte del costo puede bajar aproximadamente un 90 %.

La condición es que el prefijo se mantenga estable y se reutilice. Si cambia en cada solicitud por una marca de tiempo o un ID aleatorio, la caché se crea de nuevo. La creación repetida puede costar más que la entrada normal.

Por qué la caché de tu agente siempre falla

Estos fallos no siempre muestran un error. Ves la factura, pero no el origen del gasto:

1. Los mensajes variables rompen el prefijo. Una marca de tiempo, un ID aleatorio o cualquier valor que cambie en cada solicitud invalida todo el prefijo. Es la causa más frecuente.

2. La cache key falta o es incorrecta. Algunas herramientas no marcan bien el contenido o calculan mal su clave personalizada. El prefijo es estable, pero la API no lo reconoce como reutilizable.

3. La caché está desactivada por defecto. Algunos agentes requieren activarla explícitamente en el archivo de configuración. Aunque esperes que lo resuelvan solos, cada llamada sigue facturándose como entrada normal.

4. El TTL es demasiado corto. Si la caché caduca tras una hora y tus solicitudes están más separadas, ya no existe cuando llega la siguiente.

El síntoma exacto depende del agente. El README de prompt-cache-skills los agrupa por herramienta. Antes de modificar nada, verifica que el SKILL.md correspondiente se aplique a tu configuración.

Qué es prompt-cache-skills

prompt-cache-skills es un conjunto de skills drop-in que un agente de código con IA puede leer y aplicar:

Dimensión	Detalle
Posición	Correcciones drop-in que un agente de código con IA puede leer y aplicar
Objetivo	Elevar una caché rota o parcial al 80 %–99 % de aciertos en cargas adecuadas
Agentes relevantes	Claude Code, Codex, Cline, Cursor, Devin, Gemini CLI, OpenCode, Aider, Continue, Roo Code y otros
Repositorio	https://github.com/OnlyTerp/prompt-cache-skills
Flujo	Indicar el repositorio → aplicar skills coincidentes → verificar aciertos, o aplicar manualmente los patches de skills/
Ahorro de tiempo	Evitar investigar desde cero los detalles de caché de cada proveedor

El proyecto tiene actualmente unas 99 stars. La lista y los nombres pueden cambiar, así que usa el README del repositorio como referencia.

La investigación manual exige leer la documentación de cada proveedor, comparar configuraciones de agentes y adivinar qué campo vuelve inestable el prefijo. Cada skill identifica un fallo concreto, proporciona el diff y describe su verificación.

Cómo corregir tu agente con prompt-cache-skills

Puedes dejar que el agente aplique la corrección o modificar la configuración manualmente.

Método 1: dejar que el agente corrija automáticamente (recomendado)

Primero, indica el repositorio y envía esta instrucción:

Lee https://github.com/OnlyTerp/prompt-cache-skills y aplica todos los skills de skills/ que coincidan con el harness que uso: confirma el objetivo → aplica el diff → verifica según SKILL.md

El agente identifica después tu herramienta, como Cline, Continue o Aider, y enumera los skills correspondientes y el fallo que corrige cada uno.

Revisa el diff. Cada directorio contiene un SKILL.md con el objetivo y el cambio exacto. Confirma que la modificación es segura para tu entorno.

Tras aprobarlo, deja que el agente aplique el diff a la configuración local o del proyecto. Guarda antes una copia del archivo original.

Por último, usa tools/check_cache.py para confirmar el acierto. El procedimiento completo aparece en «Cómo verificar un acierto real de caché».

Método 2: corregir manualmente

Si no quieres que un agente edite la configuración, aplica tú mismo el cambio.

Abre primero el repositorio: https://github.com/OnlyTerp/prompt-cache-skills

Explora skills/ y encuentra el skill para tu herramienta, como cline-fix-volatile-msg o continue-enable-defaults.

Lee SKILL.md. Describe objetivo, síntoma, corrección y verificación.

Modifica el archivo de configuración según las instrucciones.

Finalmente, verifica el acierto con tools/check_cache.py.

Nota de seguridad

La aplicación automática de un diff cambia directamente la configuración local o del proyecto. Lee SKILL.md, entiende cada cambio y guarda el archivo original antes de aprobarlo.

Correcciones típicas de la biblioteca

Cada skill es una corrección completa con agente objetivo, síntoma, diff y verificación. Estos son algunos ejemplos:

Skill	Agente objetivo	Síntoma	Corrección
cline-fix-volatile-msg	Cline	El prefijo del system prompt contiene una marca de tiempo y cambia en cada solicitud	Eliminar o estabilizar el mensaje variable
cline-openai-cache-key	Cline + OpenAI	La cache key de OpenAI se calcula mal	Corregir la generación de la cache key
cline-pin-timestamp	Cline	Una marca de tiempo invalida la caché	Fijar o eliminar la marca de tiempo
continue-fix-volatile-msg	Continue	El system prompt contiene campos variables	Eliminar el mensaje variable
continue-enable-defaults	Continue	Prompt caching está desactivado por defecto	Activar la caché en la configuración inicial
continue-gemini-explicit	Continue + Gemini	Falta la configuración de caché de Gemini	Definir explícitamente los parámetros
aider-1h-ttl	Aider	Un TTL de una hora caduca con frecuencia	Ampliar el TTL o ajustar la frecuencia
aider-cache-default-on	Aider	La caché está desactivada por defecto	Activar el interruptor predeterminado
opencode-detect-openai-compat	OpenCode	La caché falla en modo compatible con OpenAI	Detectar y tratar bien la API compatible
opencode-bedrock-doc-blocks	OpenCode + Bedrock	Los bloques de documentos de Bedrock tienen problemas	Corregir su estrategia de caché

La lista sigue creciendo y los nombres pueden variar. Revisa README y skills/. Si tu agente no aparece, usa los SKILL.md y patches existentes como referencia para investigar un problema parecido.

Cómo verificar un acierto real de caché

prompt-cache-skills incluye tools/check_cache.py. La herramienta compara una solicitud fría con otra caliente y calcula la tasa de aciertos.

Pasos de verificación

Descarga check_cache.py desde:
https://github.com/OnlyTerp/prompt-cache-skills/blob/main/tools/check_cache.py

Configura después las credenciales como variables de entorno:

• Anthropic: ANTHROPIC_API_KEY
• OpenAI: OPENAI_API_KEY
• Google Gemini: GOOGLE_API_KEY

Ejecuta la solicitud fría:

python check_cache.py --provider anthropic --prompt "tu system prompt" --message "tu mensaje de usuario"

Observa cache_creation_input_tokens:

• Un valor positivo indica que se creó una caché
• Anota input_tokens

Espera un segundo y repite con exactamente el mismo prompt y mensaje.

Comprueba:

• cache_read_input_tokens: un valor mayor que 0 confirma el acierto
• cache_creation_input_tokens: debe ser 0 o no aparecer
• input_tokens: debe caer de forma clara porque la parte almacenada deja de contar como entrada normal

Calcula la tasa:

Tasa de aciertos = cache_read_input_tokens / (cache_read_input_tokens + input_tokens)

Ejemplo:

• Solicitud fría: input_tokens=2000, cache_creation_input_tokens=1800
• Solicitud caliente: cache_read_input_tokens=1800, input_tokens=200
• Tasa = 1800 / (1800 + 200) = 90%

Interpreta el resultado:

• Caché activa: cache_read_input_tokens de la solicitud caliente > 0
• Caché inactiva: cache_read_input_tokens = 0 o el campo no existe

Referencia de métricas

• cache_creation_input_tokens: tokens usados por Anthropic para crear la caché
• cache_read_input_tokens: tokens leídos de la caché de Anthropic
• cached_tokens: tokens de entrada en caché de OpenAI
• input_tokens: tokens de entrada ordinarios sin caché

Si cache_read_input_tokens sigue en 0, revisa los cuatro fallos: mensajes variables, cache key incorrecta, configuración desactivada o TTL corto.

Cuándo usar esta biblioteca

La biblioteca corrige fallos conocidos, pero no sirve para todas las cargas:

Carga	Recomendación	Motivo
System prompt largo + muchas solicitudes similares	Recomendada	Un prefijo estable puede reutilizarse
Herramientas Agent como Claude Code y Cline	Recomendada	El proyecto está dirigido a ellas
Factura mensual superior a 50 dólares	Recomendada	El ahorro potencial justifica el trabajo
Configuración existente con resultado incierto	Recomendada	La herramienta confirma si realmente funciona
Prompt corto + una sola solicitud	No recomendada	El costo del cache puede superar el beneficio
System prompt con datos en tiempo real y cambios frecuentes	No recomendada	Un prefijo inestable no puede reutilizarse
Intervalos superiores al TTL, como pocas llamadas diarias	Evaluar primero	La caché puede caducar antes de reutilizarse
Agente ausente del repositorio	Evaluar primero	Requiere adaptación manual o un futuro skill

Si tu factura supera 50 dólares y usas un agente listado, el diagnóstico puede compensar. Si las solicitudes son escasas o el prefijo cambia constantemente, estima primero las reutilizaciones.

Riesgos y precauciones

Revisa estos puntos antes de aplicar cambios:

1. El proyecto es reciente. Tiene unas 99 stars y la cobertura puede variar. El README actual es la referencia.

2. Los cambios automáticos requieren revisión. Un agente modifica archivos locales o del proyecto. Lee SKILL.md y confirma cada corrección.

3. Los campos de facturación varían. Anthropic usa cache_creation/cache_read, OpenAI cached_tokens y Gemini cached content. Consulta la documentación actual.

4. La caché no sirve siempre. Las llamadas cortas y únicas o los prefijos variables obtienen poco beneficio e incluso pueden costar más. No la fuerces.

5. La herramienta de verificación tiene límites. check_cache.py está pensada principalmente para Anthropic. Consulta también la documentación de OpenAI y Gemini.

6. La tasa no está garantizada. El 80 %–99 % es el objetivo declarado. El resultado depende del prefijo, frecuencia, TTL y otros factores.

Siguientes pasos y lecturas

Para reducir aún más el costo del código con IA:

• Centraliza monitoreo, caché y failover con un AI Gateway — administra varios proveedores y reduce costos evitables

• Técnicas de Prompt Engineering para mejorar las respuestas — mejora los prompts y evita tokens innecesarios

• Computer-Use Agent: permite que la IA controle tu computadora — entiende estos agentes y mejora el flujo

Recursos oficiales:

• Repositorio GitHub prompt-cache-skills
• Documentación de Prompt Caching de Anthropic
• Documentación de Prompt Caching de OpenAI
• Documentación de Context Caching de Google Gemini