Utiliser les Agent Skills avec l'API

Les Agent Skills étendent les capacités de Claude grâce à des dossiers organisés d'instructions, de scripts et de ressources. Ce guide vous montre comment utiliser à la fois les Skills préconstruites et les Skills personnalisées avec l'API Claude.

Liens rapides

Vue d'ensemble

Les Skills s'intègrent à l'API Messages via l'outil d'exécution de code. Que vous utilisiez des Skills préconstruites gérées par Anthropic ou des Skills personnalisées que vous avez téléversées, la forme d'intégration est identique : les deux nécessitent l'exécution de code et utilisent la même structure container.

Utiliser les Skills

Les Skills s'intègrent de manière identique dans l'API Messages, quelle que soit leur source. Vous spécifiez les Skills dans le paramètre container avec un skill_id, un type et une version facultative, et elles s'exécutent dans l'environnement d'exécution de code.

Vous pouvez utiliser des Skills provenant de deux sources :

Les deux sources de Skills sont renvoyées par le point de terminaison List Skills (utilisez le paramètre source pour filtrer). La forme d'intégration et l'environnement d'exécution sont identiques. La seule différence réside dans la provenance des Skills et la manière dont elles sont gérées.

Prérequis

Pour utiliser les Skills, vous avez besoin de :

1. Une clé API Claude provenant de la Claude Console
2. L'outil d'exécution de code activé dans vos requêtes

Les Skills nécessitent l'outil d'exécution de code ; utilisez donc un modèle figurant dans sa liste de compatibilité des modèles.

Utiliser les Skills dans Messages

Paramètre container

Les Skills sont spécifiées à l'aide du paramètre container dans l'API Messages. Vous pouvez inclure jusqu'à 20 Skills par requête.

La structure est identique pour les Skills Anthropic et les Skills personnalisées. Spécifiez les champs obligatoires type et skill_id, et incluez éventuellement version pour épingler une version spécifique :

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    container={
        "skills": [{"type": "anthropic", "skill_id": "pptx", "version": "latest"}]
    },
    messages=[
        {"role": "user", "content": "Create a presentation about renewable energy"}
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

Télécharger les fichiers générés

Lorsque les Skills créent des documents (Excel, PowerPoint, PDF, Word), elles renvoient des attributs file_id dans la réponse. Vous devez utiliser l'API Files pour télécharger ces fichiers.

Fonctionnement :

1. Les Skills créent des fichiers pendant l'exécution de code.
2. La réponse inclut un file_id pour chaque fichier créé, à l'intérieur des blocs de résultat de l'outil d'exécution de code (voir Format de réponse).
3. Utilisez l'API Files pour télécharger le contenu réel du fichier.
4. Enregistrez-le localement ou traitez-le selon vos besoins.

Pour fournir des fichiers d'entrée sur lesquels les Skills peuvent travailler, téléversez-les avec l'API Files et référencez-les dans votre requête avec un bloc container upload.

Exemple : créer et télécharger un fichier Excel

client = anthropic.Anthropic()

# Étape 1 : utiliser une Skill pour créer un fichier
response = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    container={
        "skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}]
    },
    messages=[
        {
            "role": "user",
            "content": "Create an Excel file with a simple budget spreadsheet",
        }
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)


# Étape 2 : extraire les ID de fichiers de la réponse
def extract_file_ids(response):
    file_ids = []
    for item in response.content:
        if item.type == "bash_code_execution_tool_result":
            content_item = item.content
            if content_item.type == "bash_code_execution_result":
                # chaque élément de contenu est un bloc bash_code_execution_output contenant un file_id
                for file in content_item.content:
                    file_ids.append(file.file_id)
    return file_ids


# Étape 3 : télécharger le fichier via l'API Files
for file_id in extract_file_ids(response):
    file_metadata = client.files.retrieve_metadata(file_id=file_id)
    file_content = client.files.download(file_id=file_id)

    # Étape 4 : enregistrer sur le disque
    file_content.write_to_file(file_metadata.filename)
    print(f"Downloaded: {file_metadata.filename}")

Opérations supplémentaires de l'API Files :

client = anthropic.Anthropic()
file_id = "file_011CNha8iCJcU1wXNR6q4V8w"
# Obtenir les métadonnées du fichier
file_info = client.files.retrieve_metadata(file_id=file_id)
print(f"Filename: {file_info.filename}, Size: {file_info.size_bytes} bytes")

# Lister tous les fichiers
for file in client.files.list():
    print(f"{file.filename} - {file.created_at}")

# Supprimer un fichier
client.files.delete(file_id=file_id)

Conversations multi-tours

L'objet container de la réponse contient l'id du conteneur et l'horodatage expires_at (voir Réutilisation du conteneur pour les détails sur la durée de vie). Réutilisez le même conteneur sur plusieurs messages en spécifiant l'identifiant du conteneur :

client = anthropic.Anthropic()

# La première requête crée le conteneur
response1 = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    container={
        "skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}]
    },
    messages=[
        {"role": "user", "content": "Create a sample sales dataset and analyze it"}
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# Poursuivre la conversation avec le même conteneur
messages = [
    {"role": "user", "content": "Create a sample sales dataset and analyze it"},
    {
        # Reporter le texte de l'assistant ; container.id conserve l'état d'exécution
        "role": "assistant",
        "content": "\n".join(
            block.text for block in response1.content if block.type == "text"
        ),
    },
    {"role": "user", "content": "What was the total revenue?"},
]

response2 = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    container={
        "id": response1.container.id,  # Reuse container
        "skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}],
    },
    messages=messages,
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

Opérations de longue durée

Les Skills peuvent effectuer des opérations nécessitant plusieurs tours. Gérez les raisons d'arrêt pause_turn :

client = anthropic.Anthropic()

messages = [{"role": "user", "content": "Generate and process a large sample dataset"}]
max_retries = 10

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    container={
        "skills": [
            {
                "type": "custom",
                "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
                "version": "latest",
            }
        ]
    },
    messages=messages,
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# Gérer pause_turn pour les opérations longues
for _ in range(max_retries):
    if response.stop_reason != "pause_turn":
        break

    messages.append({"role": "assistant", "content": response.content})
    response = client.messages.create(
        model="claude-opus-5",
        max_tokens=4096,
        container={
            "id": response.container.id,
            "skills": [
                {
                    "type": "custom",
                    "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
                    "version": "latest",
                }
            ],
        },
        messages=messages,
        tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
    )

Utiliser plusieurs Skills

Combinez plusieurs Skills dans une seule requête pour gérer des flux de travail complexes :

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "xlsx", "version": "latest"},
            {"type": "anthropic", "skill_id": "pptx", "version": "latest"},
            {
                "type": "custom",
                "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
                "version": "latest",
            },
        ]
    },
    messages=[
        {"role": "user", "content": "Analyze sales data and create a presentation"}
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

Gérer les Skills personnalisées

Créer une Skill

Un bundle de Skill est un répertoire contenant un fichier SKILL.md au niveau supérieur avec un frontmatter YAML name et description, ainsi que tous les scripts ou ressources d'accompagnement. Consultez Démarrer avec les Agent Skills dans l'API pour en créer une, et la liste Exigences qui suit les exemples pour l'ensemble des contraintes.

Téléversez votre Skill personnalisée pour la rendre disponible dans votre espace de travail. Vous pouvez téléverser une archive zip ou des objets fichier individuels. Le SDK Python fournit également un utilitaire files_from_dir qui accepte un chemin de répertoire.

Les fichiers sont identifiés par le nom de fichier que vous attachez (le suffixe ;filename= dans l'exemple cURL et les arguments de nom de fichier dans les exemples SDK). Pour la Skill du tutoriel, créez un zip avec zip -r financial_skill.zip financial_skill/ et substituez-le à l'espace réservé example_skill.zip dans les options de téléversement zip.

zip -r financial_skill.zip financial_skill/
ant skills create --file financial_skill.zip

---
name: financial-skill
description: Docs example skill.
---

print("financial analysis helper")

Exigences :

• Doit inclure un fichier SKILL.md à la racine du téléversement (ou au sommet d'un unique dossier englobant)
• display_name est facultatif : lorsqu'il est omis, il est dérivé du name de SKILL.md ; une valeur explicite peut comporter jusqu'à 255 caractères et n'a pas besoin d'être unique au sein de l'espace de travail
• La taille totale du téléversement doit être inférieure à 30 Mo (non compressé)
• Exigences du frontmatter YAML :
  • name : 64 caractères maximum, lettres minuscules/chiffres/tirets uniquement, pas de balises XML, pas de mots réservés (« anthropic », « claude »)
  • description : 1024 caractères maximum, non vide, pas de balises XML

Pour les schémas complets de requête/réponse, consultez la référence de l'API Create Skill.

Lister les Skills

Récupérez toutes les Skills disponibles dans votre espace de travail, y compris les Skills préconstruites d'Anthropic et vos Skills personnalisées. Utilisez le paramètre source pour filtrer par type de Skill :

# Lister toutes les Skills
ant skills list

# Lister uniquement les Skills personnalisées
ant skills list --source custom

Consultez la référence de l'API List Skills pour les options de pagination et de filtrage.

Récupérer une Skill

Obtenez les détails d'une Skill spécifique :

ant skills retrieve --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv

Supprimer une Skill

La suppression d'une Skill supprime également toutes ses versions.

ant skills delete --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv >/dev/null

Gestion des versions

Les Skills prennent en charge la gestion des versions pour gérer les mises à jour en toute sécurité :

Skills Anthropic :

• Les versions utilisent un format de date : 20251013
• De nouvelles versions sont publiées au fil des mises à jour
• Spécifiez des versions exactes pour la stabilité

Skills personnalisées :

• Identifiants de version générés automatiquement : skver_01AbCdEfGhIjKlMnOpQrStUv
• Utilisez "latest" pour toujours obtenir la version la plus récente
• Créez de nouvelles versions lors de la mise à jour des fichiers de la Skill

Une nouvelle version est un instantané complet, et non un delta : téléversez l'ensemble complet des fichiers de la Skill à chaque fois. Les fichiers que vous omettez ne sont pas reportés, et le name dans le SKILL.md de la nouvelle version doit correspondre au nom existant de la Skill. Les exemples suivants téléversent à nouveau le bundle complet financial_skill/ de Créer une Skill.

# Créer une nouvelle version
VERSION_ID=$(ant skills:versions create \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --file financial_skill.zip \
  --transform id \
  --raw-output)

# Utiliser une version spécifique
ant messages create <<YAML
model: claude-opus-5
max_tokens: 4096
container:
  skills:
    - type: custom
      skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
      version: "$VERSION_ID"
messages:
  - role: user
    content: Use updated Skill
tools:
  - type: code_execution_20250825
    name: code_execution
YAML

# Utiliser la dernière version
ant messages create <<YAML
model: claude-opus-5
max_tokens: 4096
container:
  skills:
    - type: custom
      skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
      version: latest
messages:
  - role: user
    content: Use latest Skill version
tools:
  - type: code_execution_20250825
    name: code_execution
YAML

Consultez la référence de l'API Create Skill Version pour tous les détails.

Comment les Skills sont chargées

Lorsque vous spécifiez des Skills dans un conteneur :

1. Découverte des métadonnées : Claude voit les métadonnées de chaque Skill (nom, description) dans l'invite système.
2. Chargement des fichiers : les fichiers de la Skill sont copiés dans le conteneur à l'emplacement /skills/{skill-name}/. Le répertoire correspond au nom de la Skill (pptx pour une Skill Anthropic, le name de SKILL.md pour une Skill personnalisée), et non à son identifiant skill_01....
3. Utilisation automatique : Claude charge et utilise automatiquement les Skills lorsqu'elles sont pertinentes pour votre requête.
4. Composition : plusieurs Skills se composent ensemble pour des flux de travail complexes.

Claude ne charge les instructions complètes d'une Skill que lorsque c'est nécessaire.

Cas d'utilisation

Les Skills conviennent aussi bien au travail organisationnel que personnel. Les organisations les utilisent pour appliquer la mise en forme de leur marque aux documents, structurer les notes et rapports autour de modèles d'entreprise, et exécuter des procédures analytiques propres à l'entreprise. Les particuliers les utilisent pour des modèles de documents personnalisés, des pipelines de données spécialisés, et des conventions de génération de code ou de déploiement.

Exemple : modélisation financière

Combinez les Skills Excel et d'analyse DCF personnalisée :

from anthropic.lib import files_from_dir

client = anthropic.Anthropic()

# Créer une Skill personnalisée d'analyse DCF

dcf_skill = client.skills.create(
    files=files_from_dir("/path/to/dcf_skill"),
)

# Utiliser avec Excel pour créer un modèle financier
response = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "xlsx", "version": "latest"},
            {"type": "custom", "skill_id": dcf_skill.id, "version": "latest"},
        ]
    },
    messages=[
        {
            "role": "user",
            "content": "Build a DCF valuation model for a SaaS company",
        }
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
print(response)

Limites et contraintes

Limites des requêtes

• Nombre maximal de Skills par requête : 20
• Taille maximale de téléversement d'une Skill : 30 Mo (tous fichiers combinés, non compressés)
• Exigences du frontmatter YAML :
  • name : 64 caractères maximum, lettres minuscules/chiffres/tirets uniquement, pas de balises XML, pas de mots réservés (« anthropic », « claude »)
  • description : 1024 caractères maximum, non vide, pas de balises XML

Contraintes d'environnement

Les Skills s'exécutent dans le conteneur d'exécution de code avec les limitations suivantes :

• Pas d'accès réseau : impossible d'effectuer des appels API externes
• Pas d'installation de paquets à l'exécution : seuls les paquets préinstallés sont disponibles
• Environnement isolé : un nouveau conteneur est créé, sauf si vous spécifiez un identifiant de conteneur existant

Consultez Outil d'exécution de code pour les paquets disponibles.

Bonnes pratiques

Quand utiliser plusieurs Skills

Combinez des Skills lorsque les tâches impliquent plusieurs types de documents ou domaines :

Bons cas d'utilisation :

• Analyse de données (Excel) + création de présentation (PowerPoint)
• Génération de rapport (Word) + export en PDF
• Logique métier personnalisée + génération de documents

À éviter :

• Inclure des Skills inutilisées (impact sur les performances)

Stratégie de gestion des versions

Les onglets SDK de cette section montrent la valeur container à inclure dans une requête Messages. Les onglets cURL et CLI montrent la requête complète.

Pour la production : épinglez une version spécifique, afin que les mises à jour de Skill ne modifient jamais le comportement déployé. Si vous omettez version ou la définissez sur "latest", les requêtes utilisent la version la plus récente de la Skill ; une version téléversée par n'importe qui dans l'espace de travail modifie donc immédiatement ce que vos agents de production exécutent. L'identifiant de version provient de la réponse de création de version dans Gestion des versions ou de l'API List Skill Versions. L'identifiant est toujours une chaîne de caractères ; mettez-le donc entre guillemets en JSON ou YAML même lorsqu'il semble numérique.

# Épinglez des versions spécifiques pour plus de stabilité
container = {
    "skills": [
        {
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": "skver_01AbCdEfGhIjKlMnOpQrStUv",
        }
    ]
}

Pour le développement : utilisez latest pour récupérer automatiquement la version la plus récente au fil de vos itérations.

# Utilisez latest pour le développement actif
container = {
    "skills": [
        {
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": "latest",
        }
    ]
}

Considérations relatives à la mise en cache des prompts

Si vous utilisez la mise en cache des prompts, modifier la liste des Skills dans votre conteneur invalide le cache. Les Skills sont rendues dans l'invite système dans un ordre fixe, de sorte que la même liste produit le même préfixe pouvant être mis en cache :

client = anthropic.Anthropic()

# Les Skills sont rendues dans l'invite système dans un ordre fixe, favorable au cache
response1 = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    container={
        "skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}]
    },
    messages=[{"role": "user", "content": "Analyze sales data"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# Modifier la liste des Skills ([xlsx] vs [xlsx, pptx]) change le préfixe : échec de cache, alors qu'une liste identique donne un succès de cache
response2 = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "xlsx", "version": "latest"},
            {
                "type": "anthropic",
                "skill_id": "pptx",
                "version": "latest",
            },  # prefix change: cache miss
        ]
    },
    messages=[{"role": "user", "content": "Create a presentation"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

Pour de meilleures performances de mise en cache, gardez votre liste de Skills, y compris son ordre, cohérente d'une requête à l'autre. Épingler les versions des Skills personnalisées aide également : avec "latest", la publication d'une nouvelle version peut invalider le préfixe mis en cache si elle modifie la description de la Skill.

Gestion des erreurs

Gérez les erreurs liées aux Skills avec élégance :

client = anthropic.Anthropic()

try:
    response = client.messages.create(
        model="claude-opus-5",
        max_tokens=4096,
        container={
            "skills": [
                {
                    "type": "custom",
                    "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
                    "version": "latest",
                }
            ]
        },
        messages=[{"role": "user", "content": "Process data"}],
        tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
    )
except anthropic.BadRequestError as e:
    if "skill" in str(e):
        print(f"Skill error: {e}")
        # Gérer les erreurs spécifiques aux skills
    else:
        raise

Migrer depuis skills-2025-10-02

L'API Skills n'est plus en bêta et ne nécessite aucun en-tête bêta. La migration depuis skills-2025-10-02 est facultative : les requêtes qui l'envoient encore continuent de fonctionner et de renvoyer les formes de réponse bêta, de sorte qu'une intégration existante continue de fonctionner jusqu'à ce que vous la modifiiez. Supprimer l'en-tête fait basculer ces requêtes vers les formes documentées sur cette page :

Pour migrer :

1. Supprimez l'en-tête bêta. Retirez anthropic-beta: skills-2025-10-02 de vos requêtes. Dans les SDK, appelez client.skills au lieu de client.beta.skills ; conserver client.beta.skills ne fonctionne que sur les versions de SDK qui n'envoient plus l'en-tête. Les versions antérieures l'envoient depuis client.beta.skills même sans argument betas.
2. Renommez les champs dans votre code : display_title en display_name, latest_version en latest_version_id, et lisez source.type au lieu de comparer source à une chaîne.
3. Utilisez les identifiants de version. Partout où vous stockiez une version en microsecondes epoch, stockez plutôt l'id de la version, ou utilisez latest. Les références de Skill dans les requêtes Messages acceptent un identifiant de version, latest, ou (pour les Skills Anthropic) la version du catalogue.
4. Vérifiez les appels de suppression. DELETE /v1/skills/{skill_id} supprime désormais toutes les versions avec la Skill. Si vous comptiez sur le refus de la bêta comme garde-fou, ajoutez votre propre vérification.

Une Skill dont toutes les versions ont été supprimées sous la bêta n'a aucune version courante à renvoyer : GET /v1/skills/{skill_id} renvoie une erreur 400 et la Skill est omise des réponses de liste jusqu'à ce que vous y téléversiez une version. Vous pouvez toujours la supprimer.

Espace de noms bêta du SDK

À partir du SDK Python 1.2.0, du SDK TypeScript 0.122.0, du SDK Go 1.68.0, du SDK Java 2.59.0, du SDK Ruby 1.67.0 et du SDK C# 12.44.0, client.beta.skills n'envoie plus skills-2025-10-02 et renvoie les mêmes formes que client.skills, avec des noms de types préfixés par Beta (BetaSkill, BetaSkillVersion, BetaDeletedSkill, BetaDeletedSkillVersion). Il accepte un argument betas pour les fonctionnalités Skills encore en bêta. Dans les types Messages bêta, le type de référence de Skill du conteneur est renommé de BetaSkill en BetaContainerSkill (mêmes champs : type, skill_id, version) ; BetaSkill désigne désormais la ressource Skill, en cohérence avec Skill et ContainerSkill dans les types non bêta. Les versions antérieures des SDK sont typées selon les formes bêta ; si vous dépendez de ces types, restez sur une version antérieure jusqu'à votre migration.

Conservation des données

Les Agent Skills ne sont pas couvertes par les accords ZDR. Les définitions de Skills et les données d'exécution sont conservées conformément à la politique standard de conservation des données d'Anthropic.

Pour l'éligibilité ZDR de l'ensemble des fonctionnalités, consultez API et conservation des données.

Journalisation d'audit

Si votre organisation a activé l'API Compliance, son flux d'activité enregistre la création et la suppression des Skills et des versions de Skills effectuées avec une clé API Claude ou depuis la Claude Console. Les opérations qui ont lieu pendant que l'API Compliance est désactivée ne sont pas enregistrées et ne peuvent pas être récupérées ultérieurement ; configurez donc l'API Compliance avant de vous appuyer sur cette piste d'audit.

Étapes suivantes