L'API Claude Skills en Disponibilité Générale : Nouveautés et guide d'utilisation

L'API Claude Skills est généralement disponible à partir du 20 août 2026. Vous pouvez désormais créer, versionner et gérer des compétences personnalisées via https://api.anthropic.com/v1/skills avec des en-têtes standard, sans drapeau bêta requis, et les exécuter dans le bac à sable de code de Claude sans rien avoir à héberger vous-même. Anthropic a lancé la disponibilité générale en une seule fois, incluant l'utilisation de l'ordinateur, le nouvel outil de navigation et l'API Files, présentés dans l'annonce comme la pile de production pour la création d'agents sur la plateforme Claude.

Si le concept de compétences est nouveau pour vous, notre guide sur les compétences Claude couvre l'idée de A à Z. Cet article porte sur la couche API : les points de terminaison, le modèle de versionnement, la forme de la requête qui charge les compétences dans un appel Messages, et les aspects complexes (définition de la portée de l'espace de travail, versionnement par instantané) que la disponibilité générale n'a pas aplanis. Comme tout est basé sur HTTP, chaque appel ici peut être construit et testé en régression dans Apidog pendant que vous suivez.

bouton

Un rappel de 30 secondes : ce qu'est une compétence

Une compétence est un dossier. À son niveau le plus élevé se trouve un fichier SKILL.md avec un en-tête YAML contenant un name (nom) et une description ; autour de lui se trouvent tous les scripts, modèles et fichiers de référence dont la tâche a besoin. Lorsqu'une requête inclut la compétence, Claude charge les instructions uniquement lorsque la tâche l'exige, et exécute tous les scripts regroupés dans son environnement de code en bac à sable.

L'en-tête YAML a de véritables règles de validation :

name : 64 caractères maximum, lettres minuscules, chiffres et tirets uniquement. Pas de balises XML, et les mots réservés « anthropic » et « claude » sont refusés.
description : non vide, 1024 caractères maximum.
Un display_name (nom d'affichage) facultatif (jusqu'à 255 caractères) peut être convivial.
L'ensemble du téléchargement doit rester sous 30 Mo non compressé.

Les compétences proviennent de deux sources. Les compétences gérées par Anthropic (type: "anthropic") sont livrées pré-construites avec des ID courts comme pptx, xlsx, docx et pdf, et utilisent des versions basées sur la date comme 20251013. Les compétences personnalisées (type: "custom") vous appartiennent : téléchargées via l'API, privées pour votre espace de travail, avec des ID générés comme skill_01AbCdEfGhIjKlMnOpQrStUv.

Ce que la disponibilité générale a réellement changé

Trois choses sont nouvelles ou consolidées à partir du 20 août 2026 :

Pas d'en-tête bêta. L'API Skills fonctionne sur l'API Claude avec juste x-api-key et anthropic-version: 2023-06-01.
Un flux de téléchargement et de versionnement plus simple. Anthropic décrit la disponibilité générale comme apportant « une API plus simple pour le téléchargement et le versionnement » des compétences personnalisées. Les versions sont des ressources de première classe avec leurs propres points de terminaison.
Plus de plateformes. L'API Skills est disponible via Microsoft Foundry ainsi que l'API Claude. Les compétences s'exécutent dans le bac à sable géré par Claude, il n'y a donc toujours pas d'infrastructure de votre côté.

Le reste de la vague de disponibilité générale est également important pour les utilisateurs de compétences : les compétences génèrent fréquemment des fichiers (une présentation, une feuille de calcul remplie), et ces sorties sont renvoyées via l'API Files récemment rendue disponible.

La surface des points de terminaison

Tout se trouve sous /v1/skills :

Opération	Point de terminaison
Créer une compétence	`POST /v1/skills`
Lister les compétences	`GET /v1/skills`
Récupérer une compétence	`GET /v1/skills/{skill_id}`
Supprimer une compétence	`DELETE /v1/skills/{skill_id}`
Créer une nouvelle version	`POST /v1/skills/{skill_id}/versions`
Lister les versions	`GET /v1/skills/{skill_id}/versions`

La création d'une compétence télécharge son ensemble complet de fichiers ; la création d'une version fait de même pour un ID de compétence existant. Dans un projet Apidog, cela se traduit clairement par un dossier de six requêtes enregistrées avec {{skill_id}} et {{skill_version}} comme variables d'environnement, de sorte que la promotion d'une nouvelle version à travers les environnements de développement et de production est un changement de variable, pas une modification de requête.

Télécharger une compétence personnalisée

Une compétence personnalisée minimale comprend deux éléments : le dossier et l'appel de téléchargement. Supposons que vous conserviez une compétence de rapport de marque dans votre dépôt :

brand-report/
  SKILL.md
  templates/report.html
  scripts/build_report.py

Avec SKILL.md commençant ainsi :

---
name: brand-report
description: Generates the weekly brand performance report as a formatted HTML document from a CSV of metrics. Use when asked for a brand report, weekly summary deck, or performance writeup.
---

Téléchargez-le en envoyant les fichiers sous forme de données de formulaire multipart :

curl -X POST https://api.anthropic.com/v1/skills \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -F 'files[]=@brand-report/SKILL.md;filename=brand-report/SKILL.md' \
  -F 'files[]=@brand-report/templates/report.html;filename=brand-report/templates/report.html' \
  -F 'files[]=@brand-report/scripts/build_report.py;filename=brand-report/scripts/build_report.py'

La réponse renvoie l'skill_id généré et l'ID skver_* de la première version. Stockez les deux ; l'ID de compétence figure dans vos requêtes Messages, et l'ID de version est votre point d'ancrage pour la restauration. Vérifiez les noms exacts des champs multipart par rapport à la référence de l'API Skills pour votre version SDK, car les assistants SDK typés encapsulent cet appel dans la plupart des langages.

Remarquez la description : elle se lit comme une règle de routage. Claude décide de charger une compétence en lisant ce champ, donc une description listant les phrases déclencheuses que vos utilisateurs prononcent est toujours plus performante qu'une étiquette d'une seule ligne.

Utiliser une compétence dans une requête Messages

Les compétences ne s'attachent pas seules à une requête. Elles s'appuient sur l'outil d'exécution de code, déclaré via le paramètre container :

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "pptx", "version": "latest"},
            {"type": "custom", "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv", "version": "latest"}
        ]
    },
    messages=[{"role": "user", "content": "Build the Q3 revenue deck from the attached numbers"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

Les règles qui régissent ce bloc :

L'outil d'exécution de code doit être activé dans tools, car les compétences s'exécutent à l'intérieur de ce bac à sable. La prise en charge des modèles suit la liste de compatibilité de l'outil d'exécution de code.
Jusqu'à 20 compétences par requête. Claude lit la description de chaque compétence et charge les instructions uniquement pour celles dont la tâche a besoin.
Le verrouillage de version est sous votre contrôle. "latest" pointe vers la version la plus récente ; un ID skver_* verrouillé (ou une version de date pour les compétences Anthropic) fige le comportement. Verrouillez en production, utilisez la dernière en développement.

Lorsqu'une compétence produit un document, la réponse contient un file_id que vous téléchargez via GET /v1/files/{file_id}/content de l'API Files. Cette poignée de main entre deux API (Skills pour générer, Files pour récupérer) est la boucle de production principale.

Gestion des versions : instantanés, pas de différences

Le modèle de versionnement est la partie que la plupart des équipes appréhendent mal à la première tentative. Une nouvelle version est un instantané complet, pas un delta. Lorsque vous effectuez un POST /v1/skills/{skill_id}/versions, vous téléchargez à nouveau l'ensemble complet des fichiers de la compétence ; les fichiers que vous omettez ne sont pas reportés de la version précédente. Le name dans le SKILL.md de la nouvelle version doit également correspondre au nom existant de la compétence.

Traitez les dossiers de compétences comme des artefacts de build : conservez la source de vérité dans votre dépôt, packagez le dossier entier en CI, et poussez-le comme une nouvelle version. Le retour arrière est alors trivial, puisque les anciennes versions restent accessibles par leurs ID skver_* et qu'un incident de production est résolu en réassignant une seule chaîne de caractères.

Définition de la portée de l'espace de travail : le piège multi-locataires

Les compétences personnalisées sont accessibles à l'ensemble de votre espace de travail. Elles ne sont pas limitées à un utilisateur final, une conversation ou une session, et chaque clé API de l'espace de travail les partage. Si vous exploitez un produit multi-locataires où les locataires téléchargent leurs propres compétences, un seul espace de travail est une fuite de données potentielle.

La solution est la même que pour l'API Files : créez un espace de travail distinct par locataire. L'espace de travail est la limite d'isolation, et chaque organisation peut avoir jusqu'à 100 espaces de travail avant de devoir contacter une équipe de compte. Les clés, les fichiers et les compétences héritent tous de cette limite, de sorte qu'une seule décision isole les trois.

Compétences de longue durée : pause_turn et réutilisation de conteneurs

Les exécutions de compétences peuvent durer plus longtemps qu'un seul tour de modèle. Deux mécanismes gèrent cela :

pause_turn : lorsqu'une réponse s'arrête avec stop_reason: "pause_turn", ajoutez le contenu de l'assistant à votre historique de messages et rappelez la fonction, en passant le même container.id. Le bac à sable reprend là où il s'était arrêté.
Réutilisation de conteneur : l'objet container accepte un id d'une réponse précédente, gardant les fichiers installés et l'état vivants tout au long d'une conversation à plusieurs tours. Cela signifie qu'une compétence peut construire une feuille de calcul au premier tour et la réviser au troisième tour sans la regénérer à partir de zéro.

Ces deux modèles sont des séquences HTTP avec état, ce qui les rend difficiles à tester manuellement et agréables à tester en tant que scénario Apidog : la première requête vérifie stop_reason, un script extrait container.id dans une variable, la deuxième requête le réutilise, et la dernière étape confirme que le file_id généré se télécharge correctement. L'interface de ligne de commande Apidog exécute le même scénario en intégration continue, de sorte qu'une mise à jour de version de compétence ne peut pas rompre silencieusement votre pipeline. Si vous souhaitez voir comment les compétences se comportent au sein de l'écosystème d'un autre fournisseur pour comparaison, nous avons examiné en détail la compétence Claude de Postman dans une précédente critique.

Où ça s'exécute

Lors de la disponibilité générale, l'API Skills est disponible sur l'API Claude et via Microsoft Foundry. Les compétences s'exécutent dans le bac à sable d'Anthropic quoi qu'il arrive, donc le « déploiement » est un téléchargement, et il n'y a pas d'image de conteneur, pas de patch de runtime, et pas de bouton de mise à l'échelle de votre côté. Notez la dépendance au modèle plutôt qu'à la plateforme : la requête doit utiliser un modèle pris en charge par l'outil d'exécution de code, comme claude-opus-5 dans les exemples ci-dessus. Notre guide de l'API Claude Opus 5 couvre les bases des requêtes de ce modèle si vous débutez.

FAQ

Ai-je toujours besoin de l'en-tête bêta des compétences ? Non. Depuis le 20 août 2026, /v1/skills et le paramètre container.skills fonctionnent avec des en-têtes standard sur l'API Claude. Supprimez tout drapeau bêta épinglé lorsque vous mettez à niveau votre SDK.

Une compétence peut-elle appeler des API externes pendant son exécution ? Les compétences s'exécutent dans le bac à sable de code de Claude avec les contraintes réseau de l'outil d'exécution de code. Regroupez ce dont la compétence a besoin dans son dossier plutôt que de supposer une sortie ouverte, et maintenez la logique d'appel d'API dans la couche de votre application où vous pouvez la tester correctement.

Combien de compétences une requête peut-elle charger ? Jusqu'à 20. Claude lit l'en-tête description de chaque compétence pour décider lesquelles la tâche nécessite, donc les descriptions sont essentielles : rédigez-les comme des règles de routage, pas comme du texte marketing.

Quelle est la différence entre ceci et les compétences Claude Code ? Même concept, environnement d'exécution différent. Claude Code découvre les dossiers de compétences sur votre système de fichiers ; l'API Skills les héberge côté serveur, versionnés, pour les appels d'API Messages. Le format de dossier avec l'en-tête SKILL.md est partagé, donc une compétence que vous avez écrite pour Claude Code se porte généralement avec peu de modifications.

En résumé

La disponibilité générale transforme les compétences d'une expérience en une surface opérationnelle : six points de terminaison, gestion des versions par instantané, isolation de l'espace de travail et un transfert propre vers l'API Files pour les sorties. Les équipes qui obtiennent de la valeur le plus rapidement traitent les compétences comme n'importe quel autre artefact déployable, ce qui signifie un empaquetage CI, des versions épinglées en production et des tests automatisés autour du cycle de vie du conteneur. Modélisez les six points de terminaison dans Apidog, intégrez la mise à jour de version dans un scénario de test, et vous saurez qu'une mauvaise version de compétence a cassé votre générateur de présentations avant même que vos utilisateurs ne le découvrent. Téléchargez Apidog gratuitement et construisez le harnais en un après-midi.