Claude Code devient beaucoup plus utile lorsqu’il sait comment fonctionne votre couche de routage IA. La configuration SKILL.md est la manière la plus propre de lui enseigner ce flux de travail : où se trouve le routeur de Flatkey, comment découvrir les identifiants de modèles actifs, comment appeler les modèles et outils pris en charge, et quelles règles de sécurité suivre avant de dépenser du solde ou de toucher à des systèmes de production.
Il y a d’emblée une réserve importante. La boucle de raisonnement propre à Claude Code continue de s’exécuter sur Claude. La documentation de la passerelle d’Anthropic indique que Claude Code peut se connecter à une passerelle LLM, mais elle ne prend pas en charge le routage de Claude Code lui-même vers des modèles non Claude via une passerelle. Utilisez ce guide pour la version pratique de Comment utiliser Claude Code avec n’importe quel modèle : la configuration SKILL.md : gardez Claude Code comme agent de codage, puis donnez-lui une compétence Flatkey afin qu’il puisse découvrir et appeler n’importe quel modèle ou outil facturé pris en charge par Flatkey depuis votre projet, lorsque la tâche l’exige.
Le SKILL.md public de Flatkey est conçu pour cette tâche. Il indique aux agents d’utiliser https://router.flatkey.ai, l’URL de base compatible OpenAI https://router.flatkey.ai/v1, le catalogue de modèles en direct, la place de marché des outils, de petits premiers appels, des identifiants de requête, et des validations obligatoires pour les écritures, envois, achats, suppressions, publications ou changements d’autorisations.
Si vous découvrez le routeur lui-même, gardez le guide de démarrage rapide de l’API Flatkey ouvert à côté de ce guide. Si vous comparez cela à une migration plus large de fournisseur, les guides alternative à l’API OpenAI et flux de travail d’API IA unifiée expliquent plus en détail le modèle d’URL de base.
La réponse rapide
Utilisez cette configuration lorsque vous voulez que Claude Code exploite Flatkey depuis votre dépôt :
- Créez une clé API Flatkey dans la console Flatkey.
- Installez la compétence Flatkey dans Claude Code sous la forme
~/.claude/skills/flatkey/SKILL.mdou.claude/skills/flatkey/SKILL.md. - Stockez
FLATKEY_API_KEYdans votre shell ou votre gestionnaire de secrets local, et non dans un fichier commité. - Demandez à Claude Code d’utiliser la compétence Flatkey, de récupérer le catalogue de modèles en direct et d’exécuter un petit appel de vérification via
https://router.flatkey.ai/v1. - Vérifiez les journaux d’utilisation Flatkey pour le modèle, le nombre de jetons, la latence, le statut et le coût.
Si vous voulez que le trafic Claude Code de la famille Claude passe par Flatkey, utilisez le guide Flatkey pour Claude Code plutôt que l’URL de base /v1 compatible OpenAI :
export ANTHROPIC_BASE_URL="https://router.flatkey.ai"
export ANTHROPIC_API_KEY="$FLATKEY_API_KEY"
Ce chemin sert au routage de la passerelle Claude Code. Le chemin SKILL.md sert à apprendre à Claude Code comment utiliser les modèles et outils Flatkey depuis le projet.
Ce que SKILL.md change dans Claude Code
Une compétence Claude Code est un répertoire contenant un fichier SKILL.md. Claude Code charge les métadonnées de la compétence au démarrage, puis ne lit le corps de la compétence que lorsque la tâche correspond ou lorsque vous invoquez directement la compétence. Cela fait d’une compétence un meilleur emplacement que CLAUDE.md pour des procédures répétables telles que « découvrir les modèles Flatkey, sélectionner une route prise en charge, exécuter un petit appel et vérifier les journaux d’utilisation ».
Avec Flatkey, le skill doit amener Claude Code à faire cinq choses de façon cohérente :
| Étape | Ce que Claude Code doit faire | Pourquoi c’est important |
|---|---|---|
| Lire les règles de configuration | Charger le SKILL.md Flatkey avant d’appeler le routeur |
Évite les ID de modèle devinés, les entrées d’outil devinées et les fuites de secrets |
| Utiliser le catalogue en direct | Appeler /v1/models avant de sélectionner un modèle |
La liste des modèles change, donc les exemples statiques peuvent devenir obsolètes |
| Garder les secrets en local | Utiliser FLATKEY_API_KEY sans l’imprimer ni le committer |
Empêche l’exposition des identifiants dans le chat, les journaux et git |
| Commencer petit | Exécuter un petit appel de test avant un travail coûteux | Confirme l’authentification, l’URL de base, la route et la forme de la réponse |
| Vérifier le registre | Vérifier les journaux d’utilisation ou le résultat de la requête après un appel | Donne à l’équipe la preuve du modèle, de la latence, des jetons et du coût |
C’est le cœur pratique de Comment utiliser Claude Code avec n’importe quel modèle : la configuration SKILL.md. Claude Code reste l’orchestrateur. Flatkey devient la couche modèle et outil qu’il peut utiliser de manière délibérée.
Étape 1 : choisir une installation personnelle ou projet
Installez le skill globalement si vous voulez qu’il soit disponible dans chaque dépôt :
mkdir -p ~/.claude/skills/flatkey
curl -fsSL https://flatkey.ai/SKILL.md \
-o ~/.claude/skills/flatkey/SKILL.md
Installez-le dans un dépôt si vous voulez que l’équipe partage le même workflow Flatkey :
mkdir -p .claude/skills/flatkey
curl -fsSL https://flatkey.ai/SKILL.md \
-o .claude/skills/flatkey/SKILL.md
Pour un skill de projet partagé, examinez le fichier avant de le committer :
sed -n '1,200p' .claude/skills/flatkey/SKILL.md
Ne transformez pas la commande d’installation en script shell à exécution automatique. Un skill est un contenu d’instructions. Traitez-le comme l’ajout de n’importe quelle autre procédure de développement à votre dépôt : récupérez-le, examinez-le, puis commitez-le seulement si l’équipe est d’accord.
Étape 2 : définir la clé Flatkey en toute sécurité
Utilisez une variable d’environnement :
export FLATKEY_API_KEY="sk-fk-your-key"
Si vous avez besoin que la variable persiste, placez-la dans le profil de votre shell, votre gestionnaire de secrets ou un fichier d’environnement local ignoré par git. Ne mettez pas la clé dans .claude/settings.json, CLAUDE.md, un SKILL.md committé, ni dans un prompt que vous collez dans un fil partagé.
La propre règle du skill Flatkey est simple : utiliser un FLATKEY_API_KEY existant lorsqu’il est déjà configuré, et ne jamais imprimer, journaliser, committer ou envoyer cette clé ailleurs qu’à router.flatkey.ai ou à la console Flatkey authentifiée.
Étape 3 : confirmer que Claude Code voit le skill
Démarrez Claude Code depuis le dépôt ou le terminal où le skill est disponible :
claude
Vérifiez ensuite les skills disponibles :
/skills
Vous devriez voir flatkey dans la liste des skills. Si vous avez installé le skill pendant une session Claude Code en cours et qu’il n’apparaît pas, redémarrez Claude Code. Claude Code peut détecter de nombreuses modifications de skill pendant une session, mais le redémarrage est la solution la plus simple pour lever toute ambiguïté pendant la configuration.
Demandez maintenant une première tâche sans danger :
Utilisez le skill flatkey. Vérifiez que FLATKEY_API_KEY est disponible sans l’afficher, récupérez le catalogue de modèles en direct depuis Flatkey, et résumez les cinq premiers identifiants de modèles capables de traiter du texte que vous voyez. N’exécutez pas encore de génération.
Cela teste la découverte sans dépenser de budget de génération.
Étape 4 : Récupérer le catalogue de modèles en direct
Le skill Flatkey indique à Claude Code de récupérer le catalogue de modèles en direct avant de sélectionner un modèle. La commande directe est :
curl -fsS https://router.flatkey.ai/v1/models \
-H "Authorization: Bearer $FLATKEY_API_KEY"
Pour un vrai flux de travail, demandez à Claude Code de choisir uniquement parmi les identifiants renvoyés :
Utilisez le skill flatkey. Récupérez le catalogue de modèles en direct, choisissez un modèle texte à faible coût renvoyé par le catalogue pour un test de bon fonctionnement en une phrase, et expliquez pourquoi vous l’avez choisi avant d’exécuter la requête.
Cela évite une erreur courante de l’agent : utiliser un nom de modèle tiré de la mémoire ou d’un ancien article. Le catalogue est la source de vérité pour savoir ce que votre clé peut appeler à cet instant.
Étape 5 : Exécuter un minuscule appel de test compatible OpenAI
Une fois le catalogue renvoyé, exécutez une petite requête via l’API compatible OpenAI de Flatkey :
curl https://router.flatkey.ai/v1/chat/completions \
-H "Authorization: Bearer $FLATKEY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "replace-with-a-model-id-from-the-live-catalog",
"messages": [
{
"role": "user",
"content": "Répondez en une phrase : le test de bon fonctionnement Flatkey a réussi."
}
],
"max_tokens": 40
}'
Gardez le premier appel simple. Vous testez l’authentification, l’identifiant du modèle, l’URL de base, la forme de la réponse et la visibilité du ledger. Réservez les prompts à long contexte, les appels d’outils, la génération d’images et les tâches par lot jusqu’à ce que le chemin de base fonctionne.
Étape 6 : Laisser Claude Code appeler n’importe quel modèle pris en charge depuis une tâche
Une fois le test de bon fonctionnement réussi, vous pouvez demander à Claude Code d’acheminer le travail vers un modèle adapté à la tâche.
Par exemple :
Utilisez le skill flatkey. J’ai besoin d’une relecture par un deuxième modèle de cette fonction. Récupérez le catalogue en direct, sélectionnez un modèle capable de coder renvoyé par le catalogue, exécutez une petite requête de relecture via Flatkey, et indiquez l’identifiant du modèle, le résultat de la requête, ainsi que tout identifiant de requête ou champ d’utilisation renvoyé. N’imprimez pas de secrets.
Ou :
Utilisez le skill flatkey. Comparez deux modèles texte pris en charge par Flatkey sur cette invite. Limitez les deux appels à moins de 200 jetons de sortie. Affichez les réponses côte à côte et dites-moi lequel je devrais utiliser pour cette tâche interne de résumé à faible risque.
C’est le schéma « n’importe quel modèle » qui fonctionne bien avec Claude Code : Claude Code coordonne la tâche, lit les fichiers, applique le contexte du dépôt et utilise Flatkey comme route externe contrôlée vers un modèle lorsqu’un deuxième modèle ou une famille de modèles différente est utile.
Pour le choix du modèle en production, associez cela au guide du catalogue des modèles d’IA afin que Claude Code examine le type d’endpoint, l’unité tarifaire, la disponibilité et le statut de vérification avant de recommander une route.
Étape 7 : Utiliser les outils Flatkey uniquement après inspection
Le SKILL.md de Flatkey couvre également les outils à usage facturé. La règle importante est que Claude Code doit inspecter un outil avant de l’exécuter. Il ne doit pas inventer d’identifiants d’outils, de champs obligatoires, de prix, de noms de fournisseurs ou d’unités de facturation.
Une bonne première invite est :
Use the flatkey skill. Open the Flatkey tools marketplace in the browser, inspect the search-related tools available to my account, and summarize the required fields and billing unit for one candidate tool. Do not execute the tool yet.
Puis, lorsque vous êtes prêt :
Use the flatkey skill. Run the inspected tool with a small limit and an idempotency key. Before execution, repeat the exact tool, required fields, expected billing unit, and maximum budget for my approval.
Cela permet à Claude Code de rester utile sans laisser un agent dériver vers des appels payants incontrôlés.
Étape 8 : Acheminer le trafic Claude de Claude Code via Flatkey lorsque nécessaire
La configuration SKILL.md n’est pas la même chose que le fait d’acheminer Claude Code lui-même via une passerelle. Si votre objectif est de faire passer les requêtes de Claude Code vers la famille Claude par Flatkey, configurez Claude Code comme un client de passerelle au format Anthropic :
export ANTHROPIC_BASE_URL="https://router.flatkey.ai"
export ANTHROPIC_API_KEY="$FLATKEY_API_KEY"
N’utilisez pas de /v1 final pour ce chemin. Claude Code et le SDK Anthropic ajoutent la route requise. Après avoir défini les variables, lancez Claude Code depuis le même shell et exécutez :
/status
Recherchez l’URL de base Anthropic et la source des identifiants. Envoyez ensuite une courte invite et vérifiez les journaux d’utilisation Flatkey. Si l’URL de base n’apparaît pas, Claude Code n’a pas reçu la variable d’environnement.
Utilisez ce chemin lorsque vous souhaitez que l’utilisation de Claude par Claude Code alimente le solde et le grand livre de Flatkey. Utilisez le chemin via la skill lorsque vous souhaitez que Claude Code appelle des modèles et des outils pris en charge par Flatkey depuis votre dépôt.
Pour des décisions de routage voisines, consultez routage API Claude vs GPT. Si votre cas d’usage est un agent qui appelle des outils externes, la liste de contrôle Gemini API pour les agents IA est utile même lorsque la famille de modèles change, car les contrôles sont similaires : identifiants de modèle exacts, nouvelles tentatives bornées, validation des outils et revue de l’utilisation.
Erreurs courantes
Erreur 1 : supposer que SKILL.md change le cerveau de Claude Code
Ce n’est pas le cas. Une skill donne à Claude Code des instructions et des procédures réutilisables. Elle ne transforme pas la boucle d’agent propre à Claude Code en GPT, Gemini, DeepSeek, Qwen ou un autre modèle.
Erreur 2 : utiliser /v1 avec ANTHROPIC_BASE_URL
L’URL de base compatible OpenAI de Flatkey est :
https://router.flatkey.ai/v1
Le routage via la passerelle de Claude Code utilise :
https://router.flatkey.ai
Gardez ces deux éléments séparés.
Erreur 3 : commettre des identifiants dans les paramètres de Claude
Le fichier de projet .claude/settings.json est généralement partagé avec le dépôt. N’y mettez pas de clés. Utilisez des exports shell, un coffre-fort, ou .claude/settings.local.json uniquement si votre dépôt l’ignore et que votre équipe accepte ce flux de travail local.
Erreur 4 : laisser l’agent deviner les identifiants de modèle
Récupérez toujours d’abord /v1/models. Si un identifiant de modèle n’apparaît pas dans la réponse du catalogue en direct pour votre clé, ne l’utilisez pas.
Erreur 5 : exécuter des outils payants avant de les inspecter
Pour les outils Flatkey, inspectez d’abord les champs requis, les exemples, l’unité de facturation et le prix exact. Utilisez ensuite une clé d’idempotence et demandez une approbation avant l’exécution.
Une checklist de configuration à copier
Utilisez cette checklist pour une machine de développeur :
# 1. Installez la skill Flatkey pour Claude Code
mkdir -p ~/.claude/skills/flatkey
curl -fsSL https://flatkey.ai/SKILL.md \
-o ~/.claude/skills/flatkey/SKILL.md
# 2. Vérifiez-la
sed -n '1,200p' ~/.claude/skills/flatkey/SKILL.md
# 3. Exportez votre clé Flatkey
export FLATKEY_API_KEY="sk-fk-your-key"
# 4. Démarrez Claude Code
claude
Puis demandez :
Utilise la skill flatkey. Confirme que la skill Flatkey est chargée, vérifie que FLATKEY_API_KEY est disponible sans l’afficher, récupère le catalogue de modèles en direct et exécute un minuscule test de fumée chat-completions via https://router.flatkey.ai/v1 en utilisant un identifiant de modèle renvoyé par le catalogue.
Après l’appel, ouvrez Flatkey Usage Logs et confirmez que la requête apparaît avec le modèle attendu, le statut, les nombres de jetons, la latence et le coût.
FAQ
Claude Code peut-il utiliser n’importe quel modèle via SKILL.md ?
Claude Code lui-même fonctionne toujours sur Claude. La configuration SKILL.md permet à Claude Code de découvrir et d’appeler des modèles et des outils pris en charge par Flatkey depuis votre projet, afin qu’une tâche puisse utiliser d’autres modèles via l’API de Flatkey lorsque c’est approprié.
Est-ce la même chose que de modifier ANTHROPIC_BASE_URL ?
Non. ANTHROPIC_BASE_URL=https://router.flatkey.ai route le trafic Claude de Claude Code via une passerelle. Installer https://flatkey.ai/SKILL.md apprend à Claude Code comment utiliser les API et les outils Flatkey pendant une tâche.
Dois-je installer la skill Flatkey globalement ou dans le dépôt ?
Utilisez ~/.claude/skills/flatkey/ pour un usage personnel entre différents projets. Utilisez .claude/skills/flatkey/ lorsque le dépôt doit porter un workflow d’équipe partagé. Ne commitez que le fichier de skill relu et approuvé, jamais un identifiant ou un secret.
Pourquoi le guide interroge-t-il d’abord /v1/models ?
Parce que la disponibilité des modèles change. Le catalogue Flatkey en direct est plus fiable qu’un nom de modèle recopié de mémoire, qu’une réponse de chat ou qu’un ancien document.
Que dois-je vérifier après la configuration ?
Vérifiez trois choses : Claude Code voit le skill, la requête au catalogue Flatkey réussit, et les Usage Logs affichent la requête de test avec le modèle, le statut, les jetons, la latence et le coût.
Références officielles
- Flatkey SKILL.md : https://flatkey.ai/SKILL.md
- Guide de démarrage rapide Flatkey : https://docs.flatkey.ai/quickstart.md
- Guide Flatkey Claude Code : https://docs.flatkey.ai/guides/claude-code.md
- Guide Flatkey OpenAI SDK : https://docs.flatkey.ai/guides/openai-sdk.md
- Compétences Claude Code d’Anthropic : https://code.claude.com/docs/en/skills
- Documentation du gateway Claude Code d’Anthropic : https://docs.anthropic.com/en/docs/claude-code/llm-gateway.md
- Guide de connexion au gateway d’Anthropic : https://docs.anthropic.com/en/docs/claude-code/llm-gateway-connect.md
- Présentation d’Anthropic Agent Skills : https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview
