Pourquoi le Prompt Cache ne réduit pas la facture : diagnostiquer vos agents avec prompt-cache-skills

Votre facture mensuelle Claude Code ou Cline peut être 30 à 50 % plus élevée que nécessaire. Le problème n’est peut-être pas le volume d’utilisation : le Prompt Cache peut simplement ne pas fonctionner.

De nombreux agents de code IA activent le prompt caching par défaut, mais un petit changement de configuration suffit à invalider tout le préfixe mis en cache : un horodatage dans le system prompt, une cache key mal calculée, une option non activée ou un TTL trop court. Ces problèmes ne provoquent pas forcément d’erreur et la facture n’en précise pas la cause ; le coût de l’API reste simplement élevé.

prompt-cache-skills est une bibliothèque de skills drop-in qui corrige ces échecs silencieux. Pour une charge adaptée, elle peut faire passer le taux de hit de presque zéro à 80 % ou davantage. Voici le principe de facturation, les quatre causes principales, des correctifs typiques et une méthode de validation.

Comment le Prompt Cache réduit les coûts

Le principe est simple : un préfixe stable peut être mis en cache, puis réutilisé à un coût nettement inférieur à celui des tokens d’entrée ordinaires.

Les noms de champs diffèrent selon les API, mais le mécanisme reste le même :

Type de facturation	Fonctionnement	Cas adapté	Fournisseur représentatif
cache_creation_input_tokens	Crée le cache au premier appel et coûte souvent plus cher que les tokens ordinaires	Premier appel avec un long préfixe	Anthropic
cache_read_input_tokens	Un hit coûte beaucoup moins, environ 10 % du tarif d’entrée normal	Réutilisation d’un préfixe stable	Anthropic
Tokens d’entrée ordinaires	Facturés au tarif normal	Requêtes courtes ou préfixes souvent modifiés	Tous les fournisseurs
cached_tokens (OpenAI)	Le coût des tokens mis en cache baisse d’environ 50 %	Réutilisation d’un préfixe stable	OpenAI
cached content (Gemini)	Facturé selon la durée de stockage du cache	Contextes longs	Google Gemini

Prenons Anthropic : si votre system prompt contient 2 000 tokens et que le même agent le réutilise 100 fois par jour, un hit facture ces 2 000 tokens en cache_read, soit environ 10 % du coût normal. Cette partie de la facture d’entrée peut donc baisser d’environ 90 %.

Le préfixe doit toutefois rester stable et être réutilisé. Si le system prompt change à chaque appel à cause d’un horodatage ou d’un identifiant aléatoire, le cache est recréé à chaque fois. Des créations répétées peuvent coûter plus cher que l’entrée ordinaire.

Pourquoi le cache de votre agent échoue

Ces échecs ne déclenchent pas forcément d’erreur. Vous voyez la facture, pas la source du gaspillage :

1. Un message variable détruit le préfixe. Un horodatage, un identifiant aléatoire ou toute valeur qui change à chaque requête invalide l’ensemble du préfixe mis en cache. C’est la cause la plus fréquente.

2. La cache key est absente ou incorrecte. Certains outils ne marquent pas correctement le contenu ou calculent mal leur clé personnalisée. Le préfixe est stable, mais l’API ne le reconnaît pas comme contenu réutilisable.

3. Le cache est désactivé par défaut. Certains agents exigent une activation explicite dans le fichier de configuration. Vous pensez que l’outil s’en charge, alors que chaque appel reste facturé comme entrée ordinaire.

4. Le TTL est trop court. Si le cache expire après une heure alors que vos appels sont plus espacés, il n’existe déjà plus lors de la requête suivante.

Le symptôme précis varie selon l’agent. Le README de prompt-cache-skills les regroupe par outil. Avant toute modification, vérifiez que le SKILL.md correspondant s’applique vraiment à votre configuration.

Qu’est-ce que prompt-cache-skills ?

prompt-cache-skills est un ensemble de skills drop-in qu’un agent de code IA peut lire et appliquer :

Dimension	Détail
Positionnement	Correctifs drop-in qu’un agent de code IA peut lire et appliquer
Objectif	Porter un cache défaillant ou partiel à 80–99 % de hits dans les charges adaptées
Agents concernés	Claude Code, Codex, Cline, Cursor, Devin, Gemini CLI, OpenCode, Aider, Continue, Roo Code et autres
Dépôt	https://github.com/OnlyTerp/prompt-cache-skills
Utilisation	Indiquer le dépôt → appliquer les skills correspondants → valider les hits, ou appliquer manuellement les patches de skills/
Temps gagné	Éviter de rechercher soi-même tous les détails du caching de chaque fournisseur

Le projet compte actuellement environ 99 stars. La liste et le nom des skills peuvent évoluer ; le README du dépôt reste la référence.

Une recherche manuelle impose de lire la documentation de chaque fournisseur, de comparer les différences entre agents et de deviner quel champ déstabilise le préfixe. Chaque skill isole une panne concrète, fournit le diff et décrit la validation.

Corriger votre agent avec prompt-cache-skills

Deux méthodes sont possibles : laisser l’agent appliquer le correctif ou modifier les fichiers vous-même.

Méthode 1 : laisser l’agent corriger automatiquement (recommandé)

Commencez par lui indiquer le dépôt et envoyez cette consigne :

Lisez https://github.com/OnlyTerp/prompt-cache-skills et appliquez chaque skill de skills/ correspondant au harness que j’utilise : confirmez la cible → appliquez le diff → validez selon SKILL.md

L’agent identifie ensuite l’outil utilisé, par exemple Cline, Continue ou Aider, puis liste les skills correspondants et la panne traitée par chacun.

Examinez le diff. Chaque dossier contient un SKILL.md qui précise la cible et le changement exact. Vérifiez que la modification convient à votre environnement.

Après validation, laissez l’agent appliquer le diff à la configuration locale ou au projet. Sauvegardez le fichier d’origine auparavant.

Enfin, utilisez tools/check_cache.py pour confirmer le hit. La procédure détaillée figure dans « Vérifier qu’un hit de cache a vraiment eu lieu ».

Méthode 2 : corriger manuellement

Si vous ne voulez pas qu’un agent modifie la configuration, appliquez vous-même le correctif.

Ouvrez d’abord le dépôt : https://github.com/OnlyTerp/prompt-cache-skills

Parcourez ensuite skills/ et trouvez celui de votre outil, par exemple cline-fix-volatile-msg ou continue-enable-defaults.

Lisez SKILL.md : cible, symptôme, correctif et validation y sont décrits.

Modifiez le fichier de configuration selon ces indications.

Validez enfin le hit avec tools/check_cache.py.

Précaution de sécurité

L’application automatique d’un diff modifie directement une configuration locale ou de projet. Lisez SKILL.md, comprenez chaque changement et sauvegardez le fichier d’origine avant d’autoriser l’opération.

Correctifs typiques de la bibliothèque

Chaque skill est un correctif complet avec agent cible, symptôme, diff et méthode de validation. Quelques exemples :

Skill	Agent cible	Symptôme	Correctif
cline-fix-volatile-msg	Cline	Le préfixe du system prompt contient un horodatage et change à chaque appel	Supprimer ou stabiliser le message variable
cline-openai-cache-key	Cline + OpenAI	La cache key OpenAI est mal calculée	Corriger la génération de la cache key
cline-pin-timestamp	Cline	Un horodatage invalide le cache	Fixer ou supprimer l’horodatage
continue-fix-volatile-msg	Continue	Le system prompt contient des champs variables	Retirer le message variable
continue-enable-defaults	Continue	Le prompt caching est désactivé par défaut	Activer le cache dans la configuration initiale
continue-gemini-explicit	Continue + Gemini	La configuration de cache Gemini manque	Définir explicitement les paramètres
aider-1h-ttl	Aider	Un TTL d’une heure provoque des expirations fréquentes	Allonger le TTL ou rapprocher les requêtes
aider-cache-default-on	Aider	Le cache est désactivé par défaut	Activer l’option par défaut
opencode-detect-openai-compat	OpenCode	Le cache échoue en mode compatible OpenAI	Détecter et traiter correctement l’API compatible
opencode-bedrock-doc-blocks	OpenCode + Bedrock	Les blocs de document Bedrock posent problème	Corriger leur stratégie de cache

La liste continue de grandir et les noms peuvent changer. Consultez le README et skills/. Si votre agent n’est pas présent, utilisez les SKILL.md et patches existants comme modèles de diagnostic.

Vérifier qu’un hit de cache a vraiment eu lieu

prompt-cache-skills fournit tools/check_cache.py. Il compare un appel froid à un appel chaud et calcule le taux de hit.

Étapes de vérification

Téléchargez check_cache.py ici :
https://github.com/OnlyTerp/prompt-cache-skills/blob/main/tools/check_cache.py

Configurez ensuite les identifiants API comme variables d’environnement :

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

Exécutez l’appel froid :

python check_cache.py --provider anthropic --prompt "votre system prompt" --message "votre message utilisateur"

Observez cache_creation_input_tokens :

• Une valeur positive indique la création du cache
• Notez la valeur input_tokens

Attendez une seconde et répétez l’appel avec exactement le même prompt et le même message.

Contrôlez ces champs :

• cache_read_input_tokens : une valeur supérieure à 0 confirme le hit
• cache_creation_input_tokens : doit être nul ou absent
• input_tokens : doit nettement baisser, car la partie cachée n’est plus facturée comme entrée ordinaire

Calculez ensuite le taux de hit :

Taux de hit = cache_read_input_tokens / (cache_read_input_tokens + input_tokens)

Exemple :

• Appel froid : input_tokens=2000, cache_creation_input_tokens=1800
• Appel chaud : cache_read_input_tokens=1800, input_tokens=200
• Taux de hit = 1800 / (1800 + 200) = 90%

Interprétez enfin le résultat :

• Cache actif : cache_read_input_tokens de l’appel chaud > 0
• Cache inactif : cache_read_input_tokens = 0 ou champ absent

Signification des métriques

• cache_creation_input_tokens : tokens utilisés par Anthropic pour créer le cache
• cache_read_input_tokens : tokens lus dans le cache Anthropic
• cached_tokens : tokens d’entrée mis en cache par OpenAI
• input_tokens : tokens d’entrée ordinaires non cachés

Si cache_read_input_tokens reste à 0 sur l’appel chaud, revenez aux quatre causes : message variable, cache key incorrecte, option désactivée ou TTL trop court.

Quand utiliser cette bibliothèque

La bibliothèque corrige des erreurs connues, mais ne convient pas à toutes les charges :

Charge	Recommandation	Raison
Long system prompt + nombreuses requêtes similaires	Recommandé	Un préfixe stable peut être réutilisé
Outils Agent de code comme Claude Code et Cline	Recommandé	Le projet cible ces outils
Facture mensuelle supérieure à 50 dollars	Recommandé	L’économie potentielle justifie l’effort
Configuration existante au résultat incertain	Recommandé	L’outil de validation confirme le fonctionnement
Prompt court + un seul appel	Non recommandé	Le coût du cache peut dépasser le gain
System prompt souvent modifié par des données en temps réel	Non recommandé	Le préfixe instable ne peut pas être réutilisé
Intervalles supérieurs au TTL, par exemple quelques appels par jour	À évaluer	Le cache peut expirer avant sa réutilisation
Agent absent de la liste	À évaluer	Adaptation manuelle ou futur skill communautaire nécessaire

Si votre facture dépasse 50 dollars et que l’agent figure dans la liste, le diagnostic peut être rentable. Si les appels sont rares ou le préfixe change sans cesse, estimez d’abord le nombre de réutilisations.

Risques et précautions

Examinez ces points avant application :

1. Le projet est récent. Il compte environ 99 stars et sa couverture peut évoluer. Le README actuel reste la référence.

2. Les changements automatiques exigent un contrôle. Un agent modifie des fichiers locaux ou de projet. Lisez SKILL.md et vérifiez que chaque changement convient.

3. Les champs de facturation varient. Anthropic utilise cache_creation/cache_read, OpenAI cached_tokens et Gemini cached content. Consultez les documentations à jour.

4. Le cache n’est pas universel. Les appels courts et uniques ou les préfixes variables gagnent peu et peuvent coûter davantage. Ne l’imposez pas partout.

5. L’outil de validation a des limites. check_cache.py vise surtout l’API Anthropic. Pour OpenAI et Gemini, consultez aussi la documentation officielle.

6. Le taux n’est pas garanti. Les 80–99 % sont l’objectif annoncé du projet. Le résultat dépend du préfixe, de la fréquence, du TTL et du contexte.

Étapes suivantes et lectures associées

Pour réduire davantage les coûts du code avec l’IA :

• Centraliser monitoring, cache et failover avec un AI Gateway — gérer plusieurs fournisseurs et réduire les coûts évitables

• Techniques de Prompt Engineering pour améliorer les réponses — mieux structurer les prompts et éviter des tokens inutiles

• Computer-Use Agent : laisser l’IA contrôler votre ordinateur — comprendre ces agents et améliorer le workflow

Ressources officielles :

• Dépôt GitHub prompt-cache-skills
• Documentation Anthropic sur le Prompt Caching
• Documentation OpenAI sur le Prompt Caching
• Documentation Google Gemini sur le Context Caching