Utiliser les Agent Skills avec l'API

Les Agent Skills étendent les capacités de Claude grâce à des dossiers organisés contenant des instructions, des scripts et des ressources. Ce guide vous montre comment utiliser des Skills préconstruits et personnalisés 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éconstruits gérés par Anthropic ou des Skills personnalisés que vous avez téléversés, la forme d'intégration est identique : les deux nécessitent l'exécution de code et utilisent la même structure container.



Utilisation des 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 optionnelle, et ils 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 ils sont gérés.



Prérequis

Pour utiliser les Skills, vous avez besoin de :

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

Les Skills sont en disponibilité générale sur l'API Claude et ne nécessitent pas d'en-tête anthropic-beta, que ce soit pour l'API Skills ou pour container.skills dans les requêtes Messages. Les exemples de ce guide envoient néanmoins l'en-tête bêta skills-2025-10-02 (ainsi que code-execution-2025-08-25 dans les requêtes Messages) et utilisent l'espace de noms beta des SDK. Les deux en-têtes restent des options d'activation valides, de sorte que les exemples fonctionnent tels quels, et vous pouvez les omettre dans vos propres 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.



Utilisation des Skills dans Messages



Paramètre container

Les Skills sont spécifiés à 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 personnalisés. Spécifiez les champs obligatoires type et skill_id, et incluez éventuellement version pour épingler une version spécifique :

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    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échargement des fichiers générés

Lorsque les Skills créent des documents (Excel, PowerPoint, PDF, Word), ils 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 du 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 localement ou traitez selon vos besoins.

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

Exemple : création et téléchargement d'un fichier Excel

client = anthropic.Anthropic()

# Étape 1 : Utiliser une Skill pour créer un fichier
response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    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 fichier 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 portant 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.beta.files.retrieve_metadata(file_id=file_id)
    file_content = client.beta.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.beta.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.beta.files.list():
    print(f"{file.filename} - {file.created_at}")

# Supprimer un fichier
client.beta.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'ID du conteneur :

client = anthropic.Anthropic()

# La première requête crée le conteneur
response1 = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    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"},
    {
        # Transmettre 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.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    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 motifs d'arrêt pause_turn :

client = anthropic.Anthropic()

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

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    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.beta.messages.create(
        model="claude-opus-5",
        max_tokens=4096,
        betas=["code-execution-2025-08-25", "skills-2025-10-02"],
        container={
            "id": response.container.id,
            "skills": [
                {
                    "type": "custom",
                    "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
                    "version": "latest",
                }
            ],
        },
        messages=messages,
        tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
    )



Utilisation de plusieurs Skills

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

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    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"}],
)



Gestion des Skills personnalisés



Création d'un 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 de support. Consultez Démarrer avec les Agent Skills dans l'API pour en créer un, et la liste Exigences suivant les exemples pour l'ensemble des contraintes.

Téléversez votre Skill personnalisé pour le rendre disponible dans votre espace de travail. Vous pouvez téléverser une archive zip ou des objets fichiers individuels. Le SDK Python fournit également une fonction d'aide 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 le Skill de ce 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 beta:skills create \
  --file financial_skill.zip \
  --beta skills-2025-10-02

---
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 optionnel : 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 : maximum 64 caractères, uniquement des lettres minuscules/chiffres/tirets, pas de balises XML, pas de mots réservés (« anthropic », « claude »)
  • description : maximum 1024 caractères, 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 tous les Skills disponibles dans votre espace de travail, y compris les Skills préconstruits Anthropic et vos Skills personnalisés. Utilisez le paramètre source pour filtrer par type de Skill :

# Lister toutes les Skills
ant beta:skills list

# Lister uniquement les Skills personnalisées
ant beta: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 un Skill

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

ant beta:skills retrieve \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv



Supprimer un Skill

La suppression d'un Skill supprime également toutes ses versions. Cette cascade est un comportement propre à la disponibilité générale (GA), donc contrairement aux autres exemples de ce guide, ceux-ci appellent directement la surface GA plutôt que l'espace de noms beta.

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 fur et à mesure des mises à jour
• Spécifiez des versions exactes pour la stabilité

Skills personnalisés :

• ID 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 du Skill

Une nouvelle version est un instantané complet, pas un delta : téléversez l'ensemble complet des fichiers du 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 du Skill. Les exemples suivants retéléversent le bundle complet financial_skill/ de la section Création d'un Skill.

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

# Utiliser une version spécifique
ant beta:messages create \
  --beta code-execution-2025-08-25,skills-2025-10-02 <<YAML
model: claude-opus-5
max_tokens: 4096
container:
  skills:
    - type: custom
      skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
      version: "$VERSION_NUMBER"
messages:
  - role: user
    content: Use updated Skill
tools:
  - type: code_execution_20250825
    name: code_execution
YAML

# Utiliser la dernière version
ant beta:messages create \
  --beta code-execution-2025-08-25,skills-2025-10-02 <<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.



Chargement des Skills

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 du Skill sont copiés dans le conteneur à l'emplacement /skills/{skill-name}/. Le répertoire correspond au nom du Skill (pptx pour un Skill Anthropic, le name de SKILL.md pour un Skill personnalisé), et non à son ID skill_01....
3. Utilisation automatique : Claude charge et utilise automatiquement les Skills lorsqu'ils sont pertinents 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'un Skill que lorsque c'est nécessaire.



Cas d'usage

Les Skills conviennent aussi bien au travail organisationnel que personnel. Les organisations les utilisent pour appliquer une mise en forme de marque aux documents, structurer des notes et des 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 un Skill personnalisé d'analyse DCF

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

# Utiliser avec Excel pour créer un modèle financier
response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    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 de requête

• Nombre maximum de Skills par requête : 20
• Taille maximale de téléversement d'un Skill : 30 Mo (tous fichiers combinés, non compressés)
• Exigences du frontmatter YAML :
  • name : maximum 64 caractères, uniquement des lettres minuscules/chiffres/tirets, pas de balises XML, pas de mots réservés (« anthropic », « claude »)
  • description : maximum 1024 caractères, 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 packages à l'exécution : seuls les packages préinstallés sont disponibles
• Environnement isolé : un nouveau conteneur est créé, sauf si vous spécifiez un ID de conteneur existant

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



Bonnes pratiques



Quand utiliser plusieurs Skills

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

Bons cas d'usage :

• 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és (impacte 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 votre comportement déployé. Si vous omettez version ou la définissez à "latest", les requêtes utilisent la version la plus récente du Skill, de sorte qu'une version téléversée par n'importe qui dans l'espace de travail modifie immédiatement ce que vos agents de production exécutent. L'ID de version provient de la réponse de création de version dans Gestion des versions ou de l'API List Skill Versions. L'ID est toujours une chaîne de caractères : mettez les ID d'horodatage epoch entre guillemets en JSON ou YAML.

# Épingler à des versions spécifiques pour la stabilité
container = {
    "skills": [
        {
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": "1759178010641129",
        }
    ]
}

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 sur 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 rendus 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.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=[
        "code-execution-2025-08-25",
        "skills-2025-10-02",
    ],
    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 de Skills ([xlsx] vs [xlsx, pptx]) modifie le préfixe : un échec de cache, tandis qu'une liste identique est un succès de cache
response2 = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=[
        "code-execution-2025-08-25",
        "skills-2025-10-02",
    ],
    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 entre les requêtes. Épingler les versions des Skills personnalisés aide également : avec "latest", la publication d'une nouvelle version peut invalider le préfixe mis en cache si elle modifie la description du Skill.



Gestion des erreurs

Gérez les erreurs liées aux Skills de manière élégante :

client = anthropic.Anthropic()

try:
    response = client.beta.messages.create(
        model="claude-opus-5",
        max_tokens=4096,
        betas=["code-execution-2025-08-25", "skills-2025-10-02"],
        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 compétences
    else:
        raise



Conservation des données

Les Agent Skills ne sont pas couverts 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 toutes les 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 de Skills et de versions de Skills effectuées avec une clé API Claude ou depuis la Claude Console. Les opérations qui se produisent lorsque l'API Compliance est désactivée ne sont pas enregistrées et ne peuvent pas être récupérées ultérieurement, donc configurez l'API Compliance avant de vous appuyer sur cette piste d'audit.



Étapes suivantes