MessagesSkills

Utiliser les Agent Skills avec l'API

Apprenez à utiliser les Agent Skills pour étendre les capacités de Claude via 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 des Skills préconçues et personnalisées avec l'API Claude.

Pour la référence API complète, y compris les schémas de requête/réponse et tous les paramètres, consultez :

Référence de l'API de gestion des Skills - Opérations CRUD pour les Skills
Référence de l'API des versions de Skills - Gestion des versions

Cette fonctionnalité n'est pas éligible à la Zero Data Retention (ZDR). Les données sont conservées conformément à la politique de conservation standard de la fonctionnalité.

Liens rapides

Démarrer avec les Agent Skills

Créez votre première Skill

Créer des Skills personnalisées

Bonnes pratiques pour la création de Skills

Vue d'ensemble

Pour une analyse approfondie de l'architecture et des applications concrètes des Agent Skills, lisez l'article du blog d'ingénierie : Equipping agents for the real world with Agent Skills.

Les Skills s'intègrent à l'API Messages via l'outil d'exécution de code. Que vous utilisiez des Skills préconçues 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 :

Aspect	Skills Anthropic	Skills personnalisées
Valeur de type	`anthropic`	`custom`
IDs de Skill	Noms courts : `pptx`, `xlsx`, `docx`, `pdf`	Générés : `skill_01AbCdEfGhIjKlMnOpQrStUv`
Format de version	Basé sur la date : `20251013` ou `latest`	Horodatage epoch : `1759178010641129` ou `latest`
Gestion	Préconçues et maintenues par Anthropic	Téléversement et gestion via l'API Skills
Disponibilité	Disponibles pour tous les utilisateurs	Privées pour votre espace de travail

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 :

Une clé API Claude depuis la Console
Des en-têtes bêta :
- code-execution-2025-08-25 - Active l'exécution de code (requis pour les Skills)
- skills-2025-10-02 - Active l'API Skills
- files-api-2025-04-14 - Pour téléverser/télécharger des fichiers vers/depuis le conteneur
L'outil d'exécution de code activé dans vos requêtes

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'à 8 Skills par requête.

La structure est identique pour les Skills Anthropic et personnalisées. Spécifiez les champs requis 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-4-8",
    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é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.

Comment cela fonctionne :

Les Skills créent des fichiers pendant l'exécution du code.
La réponse inclut un file_id pour chaque fichier créé.
Utilisez l'API Files pour télécharger le contenu réel du fichier.
Enregistrez localement ou traitez selon vos besoins.

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

client = anthropic.Anthropic()

# Étape 1 : utiliser un Skill pour créer un fichier
response = client.beta.messages.create(
    model="claude-opus-4-8",
    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 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 à l'aide de 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 d'un 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)

Pour tous les détails sur l'API Files, consultez la documentation de l'API Files.

Conversations multi-tours

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-4-8",
    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"},
    {
        # Reporter le texte de l'assistant ; container.id porte 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-4-8",
    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 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.beta.messages.create(
    model="claude-opus-4-8",
    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-4-8",
        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"}],
    )

La réponse peut inclure une raison d'arrêt pause_turn, qui indique que l'API a mis en pause une opération de Skill de longue durée. Vous pouvez renvoyer la réponse telle quelle dans une requête ultérieure pour laisser Claude poursuivre son tour, ou modifier le contenu si vous souhaitez interrompre la conversation et fournir des indications supplémentaires.

Utiliser 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-4-8",
    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"}],
)

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 de support. Consultez Démarrer avec les Agent Skills dans l'API pour en créer une, et la liste des 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 fichiers individuels ; le SDK Python fournit en plus un assistant files_from_dir qui accepte un chemin de répertoire.

Les fichiers sont identifiés par le nom de fichier que vous attachez. Les téléversements fichier par fichier doivent conserver un répertoire de niveau supérieur commun dans leurs chemins (le suffixe ;filename= dans l'exemple cURL et les arguments de nom de fichier dans les exemples SDK), et une archive zip doit contenir le répertoire de la skill comme unique entrée de niveau supérieur.

ant beta:skills create \
  --file example_skill.zip \
  --beta skills-2025-10-02

# Le téléversement fichier par fichier nécessite des noms de fichiers qualifiés par chemin, ce que la CLI
# ne peut pas définir actuellement. Téléversez plutôt une archive zip.

Exigences :

Doit inclure un fichier SKILL.md au niveau supérieur
Tous les fichiers doivent spécifier un répertoire racine commun dans leurs chemins
Le nom du répertoire de niveau supérieur doit correspondre au name dans le frontmatter de SKILL.md (insensible à la casse et aux traits de soulignement : Financial_Skill correspond à financial-skill)
display_title est facultatif : lorsqu'il est omis, il est dérivé du name de SKILL.md ; une valeur explicite doit être unique parmi les skills personnalisées de votre espace de travail
La taille totale du téléversement doit être inférieure à 30 Mo
Exigences du frontmatter YAML :
- name : Maximum 64 caractères, lettres minuscules/chiffres/traits d'union uniquement, 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 toutes les Skills disponibles dans votre espace de travail, y compris les Skills préconçues d'Anthropic et vos Skills personnalisées. Utilisez le paramètre source pour filtrer par type de skill :

# Lister toutes les compétences
ant beta:skills list

# Lister uniquement les compétences 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 une Skill

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

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

Supprimer une Skill

Pour supprimer une Skill, vous devez d'abord supprimer toutes ses versions :

# Étape 1 : Lister les versions, puis supprimer chacune d'elles
ant beta:skills:versions list \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --transform version --raw-output

# Répéter pour chaque identifiant de version retourné par la liste
ant beta:skills:versions delete \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --version 1759178010641129 >/dev/null

# Étape 2 : Supprimer la Skill
ant beta:skills delete \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv >/dev/null

Tenter de supprimer une Skill ayant des versions existantes renvoie une erreur 400.

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 le 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ées :

Horodatages epoch générés automatiquement : 1759178010641129
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

# Créer une nouvelle version
VERSION_NUMBER=$(ant beta:skills:versions create \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --file updated_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-4-8
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-4-8
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 :

Découverte des métadonnées : Claude voit les métadonnées de chaque Skill (nom, description) dans l'invite système.
Chargement des fichiers : Les fichiers de la Skill sont copiés dans le conteneur à /skills/{directory}/.
Utilisation automatique : Claude charge et utilise automatiquement les Skills lorsqu'elles sont pertinentes pour votre requête.
Composition : Plusieurs Skills se composent ensemble pour des flux de travail complexes.

L'architecture de divulgation progressive garantit une utilisation efficace du contexte : Claude ne charge les instructions complètes d'une Skill que lorsque c'est nécessaire.

Cas d'utilisation

Skills organisationnelles

Marque et communications

Appliquer une mise en forme spécifique à l'entreprise (couleurs, polices, mises en page) aux documents
Générer des communications suivant les modèles organisationnels
Garantir des directives de marque cohérentes dans toutes les productions

Gestion de projet

Structurer les notes avec des formats spécifiques à l'entreprise (OKR, journaux de décisions)
Générer des tâches suivant les conventions de l'équipe
Créer des comptes rendus de réunion et des mises à jour de statut standardisés

Opérations commerciales

Créer des rapports, propositions et analyses conformes aux normes de l'entreprise
Exécuter des procédures analytiques spécifiques à l'entreprise
Générer des modèles financiers suivant les modèles organisationnels

Skills personnelles

Création de contenu

Modèles de documents personnalisés
Mise en forme et stylisation spécialisées
Génération de contenu spécifique à un domaine

Analyse de données

Pipelines de traitement de données personnalisés
Modèles de visualisation spécialisés
Méthodes analytiques spécifiques à un secteur

Développement et automatisation

Modèles de génération de code
Frameworks de test
Flux de travail 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 compétence personnalisée 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-4-8",
    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 : 8
Taille maximale de téléversement d'une Skill : 30 Mo (tous fichiers combinés)
Exigences du frontmatter YAML :
- name : Maximum 64 caractères, lettres minuscules/chiffres/traits d'union uniquement, 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 paquets à l'exécution : Seuls les paquets préinstallés sont disponibles
Environnement isolé : Les conteneurs sont isolés ; un nouveau conteneur est créé sauf si vous spécifiez un ID de conteneur existant

Consultez l'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 de domaine personnalisée + génération de documents

À éviter :

Inclure des Skills inutilisées (impacte les performances)

Stratégie de gestion des versions

Pour la production :

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

Pour le développement :

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

Considérations sur la mise en cache des prompts

Lorsque vous utilisez la mise en cache des prompts, notez que la modification de la liste des Skills dans votre conteneur invalide le cache :

client = anthropic.Anthropic()

# La première requête crée le cache
response1 = client.beta.messages.create(
    model="claude-opus-4-8",
    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"}],
)

# L'ajout/la suppression de Skills invalide le cache
response2 = client.beta.messages.create(
    model="claude-opus-4-8",
    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",
            },  # 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 cohérente entre les requêtes.

Gestion des erreurs

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

client = anthropic.Anthropic()

try:
    response = client.beta.messages.create(
        model="claude-opus-4-8",
        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 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 toutes les fonctionnalités, consultez API et conservation des données.

Prochaines étapes

Référence API

Référence API complète avec tous les points de terminaison

Bonnes pratiques de création de Skills

Apprenez à écrire des Skills efficaces que Claude peut découvrir et utiliser avec succès

Outil d'exécution de code

Exécutez du code Python et bash dans un conteneur en bac à sable pour analyser des données, générer des fichiers et itérer sur des solutions

Was this page helpful?

MessagesSkills

Utiliser les Agent Skills avec l'API

Apprenez à utiliser les Agent Skills pour étendre les capacités de Claude via l'API.

Pour la référence API complète, y compris les schémas de requête/réponse et tous les paramètres, consultez :

Référence de l'API de gestion des Skills - Opérations CRUD pour les Skills
Référence de l'API des versions de Skills - Gestion des versions

Cette fonctionnalité n'est pas éligible à la Zero Data Retention (ZDR). Les données sont conservées conformément à la politique de conservation standard de la fonctionnalité.

Liens rapides

Démarrer avec les Agent Skills

Créez votre première Skill

Créer des Skills personnalisées

Bonnes pratiques pour la création de Skills

Vue d'ensemble

Pour une analyse approfondie de l'architecture et des applications concrètes des Agent Skills, lisez l'article du blog d'ingénierie : Equipping agents for the real world with Agent Skills.

Utiliser les Skills

Vous pouvez utiliser des Skills provenant de deux sources :

Aspect	Skills Anthropic	Skills personnalisées
Valeur de type	`anthropic`	`custom`
IDs de Skill	Noms courts : `pptx`, `xlsx`, `docx`, `pdf`	Générés : `skill_01AbCdEfGhIjKlMnOpQrStUv`
Format de version	Basé sur la date : `20251013` ou `latest`	Horodatage epoch : `1759178010641129` ou `latest`
Gestion	Préconçues et maintenues par Anthropic	Téléversement et gestion via l'API Skills
Disponibilité	Disponibles pour tous les utilisateurs	Privées pour votre espace de travail

Prérequis

Pour utiliser les Skills, vous avez besoin de :

Une clé API Claude depuis la Console
Des en-têtes bêta :
- code-execution-2025-08-25 - Active l'exécution de code (requis pour les Skills)
- skills-2025-10-02 - Active l'API Skills
- files-api-2025-04-14 - Pour téléverser/télécharger des fichiers vers/depuis le conteneur
L'outil d'exécution de code activé dans vos requêtes

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'à 8 Skills par requête.

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-8",
    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é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.

Comment cela fonctionne :

Les Skills créent des fichiers pendant l'exécution du code.
La réponse inclut un file_id pour chaque fichier créé.
Utilisez l'API Files pour télécharger le contenu réel du fichier.
Enregistrez localement ou traitez selon vos besoins.

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

client = anthropic.Anthropic()

# Étape 1 : utiliser un Skill pour créer un fichier
response = client.beta.messages.create(
    model="claude-opus-4-8",
    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 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 à l'aide de 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 d'un 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)

Pour tous les détails sur l'API Files, consultez la documentation de l'API Files.

Conversations multi-tours

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-4-8",
    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"},
    {
        # Reporter le texte de l'assistant ; container.id porte 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-4-8",
    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 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.beta.messages.create(
    model="claude-opus-4-8",
    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-4-8",
        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"}],
    )

Utiliser 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-4-8",
    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"}],
)

Gérer les Skills personnalisées

Créer une Skill

ant beta:skills create \
  --file example_skill.zip \
  --beta skills-2025-10-02

# Le téléversement fichier par fichier nécessite des noms de fichiers qualifiés par chemin, ce que la CLI
# ne peut pas définir actuellement. Téléversez plutôt une archive zip.

Exigences :

Doit inclure un fichier SKILL.md au niveau supérieur
Tous les fichiers doivent spécifier un répertoire racine commun dans leurs chemins
Le nom du répertoire de niveau supérieur doit correspondre au name dans le frontmatter de SKILL.md (insensible à la casse et aux traits de soulignement : Financial_Skill correspond à financial-skill)
display_title est facultatif : lorsqu'il est omis, il est dérivé du name de SKILL.md ; une valeur explicite doit être unique parmi les skills personnalisées de votre espace de travail
La taille totale du téléversement doit être inférieure à 30 Mo
Exigences du frontmatter YAML :
- name : Maximum 64 caractères, lettres minuscules/chiffres/traits d'union uniquement, 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

# Lister toutes les compétences
ant beta:skills list

# Lister uniquement les compétences 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 une Skill

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

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

Supprimer une Skill

Pour supprimer une Skill, vous devez d'abord supprimer toutes ses versions :

# Étape 1 : Lister les versions, puis supprimer chacune d'elles
ant beta:skills:versions list \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --transform version --raw-output

# Répéter pour chaque identifiant de version retourné par la liste
ant beta:skills:versions delete \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --version 1759178010641129 >/dev/null

# Étape 2 : Supprimer la Skill
ant beta:skills delete \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv >/dev/null

Tenter de supprimer une Skill ayant des versions existantes renvoie une erreur 400.

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 le 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ées :

Horodatages epoch générés automatiquement : 1759178010641129
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

# Créer une nouvelle version
VERSION_NUMBER=$(ant beta:skills:versions create \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --file updated_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-4-8
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-4-8
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 :

Découverte des métadonnées : Claude voit les métadonnées de chaque Skill (nom, description) dans l'invite système.
Chargement des fichiers : Les fichiers de la Skill sont copiés dans le conteneur à /skills/{directory}/.
Utilisation automatique : Claude charge et utilise automatiquement les Skills lorsqu'elles sont pertinentes pour votre requête.
Composition : Plusieurs Skills se composent ensemble pour des flux de travail complexes.

L'architecture de divulgation progressive garantit une utilisation efficace du contexte : Claude ne charge les instructions complètes d'une Skill que lorsque c'est nécessaire.

Cas d'utilisation

Skills organisationnelles

Marque et communications

Appliquer une mise en forme spécifique à l'entreprise (couleurs, polices, mises en page) aux documents
Générer des communications suivant les modèles organisationnels
Garantir des directives de marque cohérentes dans toutes les productions

Gestion de projet

Structurer les notes avec des formats spécifiques à l'entreprise (OKR, journaux de décisions)
Générer des tâches suivant les conventions de l'équipe
Créer des comptes rendus de réunion et des mises à jour de statut standardisés

Opérations commerciales

Créer des rapports, propositions et analyses conformes aux normes de l'entreprise
Exécuter des procédures analytiques spécifiques à l'entreprise
Générer des modèles financiers suivant les modèles organisationnels

Skills personnelles

Création de contenu

Modèles de documents personnalisés
Mise en forme et stylisation spécialisées
Génération de contenu spécifique à un domaine

Analyse de données

Pipelines de traitement de données personnalisés
Modèles de visualisation spécialisés
Méthodes analytiques spécifiques à un secteur

Développement et automatisation

Modèles de génération de code
Frameworks de test
Flux de travail 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 compétence personnalisée 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-4-8",
    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 : 8
Taille maximale de téléversement d'une Skill : 30 Mo (tous fichiers combinés)
Exigences du frontmatter YAML :
- name : Maximum 64 caractères, lettres minuscules/chiffres/traits d'union uniquement, 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 paquets à l'exécution : Seuls les paquets préinstallés sont disponibles
Environnement isolé : Les conteneurs sont isolés ; un nouveau conteneur est créé sauf si vous spécifiez un ID de conteneur existant

Consultez l'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 de domaine personnalisée + génération de documents

À éviter :

Inclure des Skills inutilisées (impacte les performances)

Stratégie de gestion des versions

Pour la production :

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

Pour le développement :

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

Considérations sur la mise en cache des prompts

Lorsque vous utilisez la mise en cache des prompts, notez que la modification de la liste des Skills dans votre conteneur invalide le cache :

client = anthropic.Anthropic()

# La première requête crée le cache
response1 = client.beta.messages.create(
    model="claude-opus-4-8",
    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"}],
)

# L'ajout/la suppression de Skills invalide le cache
response2 = client.beta.messages.create(
    model="claude-opus-4-8",
    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",
            },  # 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 cohérente entre les requêtes.

Gestion des erreurs

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

client = anthropic.Anthropic()

try:
    response = client.beta.messages.create(
        model="claude-opus-4-8",
        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

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

Prochaines étapes

Référence API

Référence API complète avec tous les points de terminaison

Bonnes pratiques de création de Skills

Apprenez à écrire des Skills efficaces que Claude peut découvrir et utiliser avec succès

Outil d'exécution de code

Exécutez du code Python et bash dans un conteneur en bac à sable pour analyser des données, générer des fichiers et itérer sur des solutions

Was this page helpful?

Liens rapides

Vue d'ensemble

Utiliser les Skills

Prérequis

Utiliser les Skills dans Messages

Paramètre container

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

Conversations multi-tours

Opérations de longue durée

Utiliser plusieurs Skills

Gérer les Skills personnalisées

Créer une Skill

Lister les Skills

Récupérer une Skill

Supprimer une Skill

Gestion des versions

Comment les Skills sont chargées

Cas d'utilisation

Skills organisationnelles

Skills personnelles

Exemple : modélisation financière

Limites et contraintes

Limites de requête

Contraintes d'environnement

Bonnes pratiques

Quand utiliser plusieurs Skills

Stratégie de gestion des versions

Considérations sur la mise en cache des prompts

Gestion des erreurs

Conservation des données

Prochaines étapes

Liens rapides

Vue d'ensemble

Utiliser les Skills

Prérequis

Utiliser les Skills dans Messages

Paramètre container

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

Conversations multi-tours

Opérations de longue durée

Utiliser plusieurs Skills

Gérer les Skills personnalisées

Créer une Skill

Lister les Skills

Récupérer une Skill

Supprimer une Skill

Gestion des versions

Comment les Skills sont chargées

Cas d'utilisation

Skills organisationnelles

Skills personnelles

Exemple : modélisation financière

Limites et contraintes

Limites de requête

Contraintes d'environnement

Bonnes pratiques

Quand utiliser plusieurs Skills

Stratégie de gestion des versions

Considérations sur la mise en cache des prompts

Gestion des erreurs

Conservation des données

Prochaines étapes

Liens rapides

Vue d'ensemble

Utiliser les Skills

Prérequis

Utiliser les Skills dans Messages

Paramètre container

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

Conversations multi-tours

Opérations de longue durée

Utiliser plusieurs Skills

Gérer les Skills personnalisées

Créer une Skill

Lister les Skills

Récupérer une Skill

Supprimer une Skill

Gestion des versions

Comment les Skills sont chargées

Cas d'utilisation

Skills organisationnelles

Skills personnelles

Exemple : modélisation financière

Limites et contraintes

Limites de requête

Contraintes d'environnement

Bonnes pratiques

Quand utiliser plusieurs Skills

Stratégie de gestion des versions

Considérations sur la mise en cache des prompts

Gestion des erreurs

Conservation des données

Prochaines étapes

Liens rapides

Vue d'ensemble

Utiliser les Skills

Prérequis

Utiliser les Skills dans Messages

Paramètre container

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

Conversations multi-tours

Opérations de longue durée

Utiliser plusieurs Skills

Gérer les Skills personnalisées

Créer une Skill

Lister les Skills

Récupérer une Skill

Supprimer une Skill

Gestion des versions

Comment les Skills sont chargées

Cas d'utilisation

Skills organisationnelles

Skills personnelles

Exemple : modélisation financière

Limites et contraintes

Limites de requête

Contraintes d'environnement

Bonnes pratiques

Quand utiliser plusieurs Skills

Stratégie de gestion des versions

Considérations sur la mise en cache des prompts

Gestion des erreurs

Conservation des données

Prochaines étapes