MessagesCompétences

Utiliser les Agent Skills avec l'API

Découvrez comment 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 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.

Pour une référence API complète incluant 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 premier Skill

Créer des Skills personnalisés

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

Aspect	Skills Anthropic	Skills personnalisés
Valeur du type	`anthropic`	`custom`
Identifiants 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éconstruits et maintenus par Anthropic	Téléversez et gérez via l'API Skills
Disponibilité	Disponibles pour tous les utilisateurs	Privés à 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 ils sont gérés.

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 les Messages

Paramètre container

Les Skills sont spécifiés à 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é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-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é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 :

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éation et téléchargement d'un fichier Excel

client = anthropic.Anthropic()

# Étape 1 : Utiliser une compétence 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 identifiants 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":
                # liste à type concret : List[BashCodeExecutionOutputBlock]
                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_abc123"
# 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
files = client.beta.files.list()
for file in files.data:
    print(f"{file.filename} - {file.created_at}")

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

Pour des détails complets 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'identifiant du conteneur :

# 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": "Analyze this sales data"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# Poursuivre la conversation avec le même conteneur
messages = [
    {"role": "user", "content": "Analyze this sales data"},
    {"role": "assistant", "content": response1.content},
    {"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 :

messages = [{"role": "user", "content": "Process this large 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 i 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 permettre à Claude de poursuivre son tour, ou modifier le contenu si vous souhaitez interrompre la conversation et fournir des indications supplémentaires.

Utilisation de plusieurs Skills

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

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

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 connaître 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 en outre une fonction d'aide files_from_dir qui accepte un chemin de répertoire.

# Option 1 : Téléverser des fichiers individuels (un indicateur --file par fichier)
ant beta:skills create \
  --display-title "Financial Analysis" \
  --file financial_skill/SKILL.md \
  --file financial_skill/analyze.py \
  --beta skills-2025-10-02

# Option 2 : Téléverser une archive zip
ant beta:skills create \
  --display-title "Financial Analysis" \
  --file financial_analysis_skill.zip \
  --beta skills-2025-10-02

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
La taille totale du téléversement doit être inférieure à 30 Mo
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 d'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ération d'un Skill

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

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

Suppression d'un Skill

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

# Étape 1 : Supprimer toutes les versions
ant beta:skills:versions list \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --transform version --raw-output \
  | while read -r VERSION; do
      ant beta:skills:versions delete \
        --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
        --version "$VERSION" >/dev/null
    done

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

Tenter de supprimer un 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 un format de date : 20251013
De nouvelles versions sont publiées au fur et à mesure des mises à jour
Spécifiez des versions exactes pour garantir la stabilité

Skills personnalisés :

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

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

# Utiliser une version spécifique
ant beta:messages create \
  --beta code-execution-2025-08-25 \
  --beta 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 \
  --beta 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 des détails complets.

Comment les Skills sont chargés

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 du Skill sont copiés dans le conteneur à l'emplacement /skills/{directory}/
Utilisation automatique : Claude charge et utilise automatiquement les Skills lorsqu'ils sont pertinents pour votre requête
Composition : plusieurs Skills se composent ensemble pour des flux de travail complexes

L'architecture de « progressive disclosure » (divulgation progressive) garantit une utilisation efficace du contexte : Claude ne charge les instructions complètes d'un Skill que lorsque cela est nécessaire.

Cas d'usage

Skills organisationnels

Marque et communications

Appliquer un formatage spécifique à l'entreprise (couleurs, polices, mises en page) aux documents
Générer des communications suivant les modèles organisationnels
Garantir la cohérence des directives de marque 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 standards 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 personnels

Création de contenu

Modèles de documents personnalisés
Formatage et style spécialisés
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 :

# Créer un Skill personnalisé d'analyse DCF
from anthropic.lib import files_from_dir

dcf_skill = client.beta.skills.create(
    display_title="DCF Analysis",
    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 with the attached financials",
        }
    ],
    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'un Skill : 30 Mo (tous fichiers combiné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é : les conteneurs sont isolés ; un nouveau conteneur est créé sauf si vous spécifiez un identifiant de conteneur existant

Consultez Outil d'exécution de code pour connaître 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

Pour la production :

# Épinglez à 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 relatives à la mise en cache des prompts

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

# 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",
        "prompt-caching-2024-07-31",
    ],
    container={
        "skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}]
    },
    messages=[{"role": "user", "content": "Analyze sales data"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# Ajouter ou supprimer des 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",
        "prompt-caching-2024-07-31",
    ],
    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, maintenez votre liste de Skills cohérente entre les requêtes.

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-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 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 sur l'ensemble des 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

Guide de création

Bonnes pratiques pour rédiger des Skills efficaces

Outil d'exécution de code

En savoir plus sur l'environnement d'exécution de code

Was this page helpful?

MessagesCompétences

Utiliser les Agent Skills avec l'API

Découvrez comment utiliser les Agent Skills pour étendre les capacités de Claude via l'API.

Pour une référence API complète incluant 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 premier Skill

Créer des Skills personnalisés

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.

Utilisation des Skills

Vous pouvez utiliser des Skills provenant de deux sources :

Aspect	Skills Anthropic	Skills personnalisés
Valeur du type	`anthropic`	`custom`
Identifiants 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éconstruits et maintenus par Anthropic	Téléversez et gérez via l'API Skills
Disponibilité	Disponibles pour tous les utilisateurs	Privés à 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 les Messages

Paramètre container

Les Skills sont spécifiés à 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é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 :

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éation et téléchargement d'un fichier Excel

client = anthropic.Anthropic()

# Étape 1 : Utiliser une compétence 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 identifiants 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":
                # liste à type concret : List[BashCodeExecutionOutputBlock]
                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_abc123"
# 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
files = client.beta.files.list()
for file in files.data:
    print(f"{file.filename} - {file.created_at}")

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

Pour des détails complets 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'identifiant du conteneur :

# 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": "Analyze this sales data"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# Poursuivre la conversation avec le même conteneur
messages = [
    {"role": "user", "content": "Analyze this sales data"},
    {"role": "assistant", "content": response1.content},
    {"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 :

messages = [{"role": "user", "content": "Process this large 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 i 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"}],
    )

Utilisation de plusieurs Skills

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

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

Gestion des Skills personnalisés

Création d'un Skill

# Option 1 : Téléverser des fichiers individuels (un indicateur --file par fichier)
ant beta:skills create \
  --display-title "Financial Analysis" \
  --file financial_skill/SKILL.md \
  --file financial_skill/analyze.py \
  --beta skills-2025-10-02

# Option 2 : Téléverser une archive zip
ant beta:skills create \
  --display-title "Financial Analysis" \
  --file financial_analysis_skill.zip \
  --beta skills-2025-10-02

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
La taille totale du téléversement doit être inférieure à 30 Mo
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

# 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ération d'un Skill

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

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

Suppression d'un Skill

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

# Étape 1 : Supprimer toutes les versions
ant beta:skills:versions list \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --transform version --raw-output \
  | while read -r VERSION; do
      ant beta:skills:versions delete \
        --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
        --version "$VERSION" >/dev/null
    done

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

Tenter de supprimer un 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 un format de date : 20251013
De nouvelles versions sont publiées au fur et à mesure des mises à jour
Spécifiez des versions exactes pour garantir la stabilité

Skills personnalisés :

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

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

# Utiliser une version spécifique
ant beta:messages create \
  --beta code-execution-2025-08-25 \
  --beta 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 \
  --beta 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 des détails complets.

Comment les Skills sont chargés

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 du Skill sont copiés dans le conteneur à l'emplacement /skills/{directory}/
Utilisation automatique : Claude charge et utilise automatiquement les Skills lorsqu'ils sont pertinents pour votre requête
Composition : plusieurs Skills se composent ensemble pour des flux de travail complexes

Cas d'usage

Skills organisationnels

Marque et communications

Appliquer un formatage spécifique à l'entreprise (couleurs, polices, mises en page) aux documents
Générer des communications suivant les modèles organisationnels
Garantir la cohérence des directives de marque 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 standards 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 personnels

Création de contenu

Modèles de documents personnalisés
Formatage et style spécialisés
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 :

# Créer un Skill personnalisé d'analyse DCF
from anthropic.lib import files_from_dir

dcf_skill = client.beta.skills.create(
    display_title="DCF Analysis",
    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 with the attached financials",
        }
    ],
    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'un Skill : 30 Mo (tous fichiers combiné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é : les conteneurs sont isolés ; un nouveau conteneur est créé sauf si vous spécifiez un identifiant de conteneur existant

Consultez Outil d'exécution de code pour connaître 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

Pour la production :

# Épinglez à 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 relatives à la mise en cache des prompts

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

# 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",
        "prompt-caching-2024-07-31",
    ],
    container={
        "skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}]
    },
    messages=[{"role": "user", "content": "Analyze sales data"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# Ajouter ou supprimer des 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",
        "prompt-caching-2024-07-31",
    ],
    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, maintenez votre liste de Skills cohérente entre les requêtes.

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-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 sur l'ensemble des 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

Guide de création

Bonnes pratiques pour rédiger des Skills efficaces

Outil d'exécution de code

En savoir plus sur l'environnement d'exécution de code

Was this page helpful?

Liens rapides

Vue d'ensemble

Utilisation des Skills

Prérequis

Utiliser les Skills dans les Messages

Paramètre container

Téléchargement des fichiers générés

Conversations multi-tours

Opérations de longue durée

Utilisation de plusieurs Skills

Gestion des Skills personnalisés

Création d'un Skill

Lister les Skills

Récupération d'un Skill

Suppression d'un Skill

Gestion des versions

Comment les Skills sont chargés

Cas d'usage

Skills organisationnels

Skills personnels

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 relatives à la mise en cache des prompts

Gestion des erreurs

Conservation des données

Prochaines étapes

Liens rapides

Vue d'ensemble

Utilisation des Skills

Prérequis

Utiliser les Skills dans les Messages

Paramètre container

Téléchargement des fichiers générés

Conversations multi-tours

Opérations de longue durée

Utilisation de plusieurs Skills

Gestion des Skills personnalisés

Création d'un Skill

Lister les Skills

Récupération d'un Skill

Suppression d'un Skill

Gestion des versions

Comment les Skills sont chargés

Cas d'usage

Skills organisationnels

Skills personnels

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 relatives à la mise en cache des prompts

Gestion des erreurs

Conservation des données

Prochaines étapes

Liens rapides

Vue d'ensemble

Utilisation des Skills

Prérequis

Utiliser les Skills dans les Messages

Paramètre container

Téléchargement des fichiers générés

Conversations multi-tours

Opérations de longue durée

Utilisation de plusieurs Skills

Gestion des Skills personnalisés

Création d'un Skill

Lister les Skills

Récupération d'un Skill

Suppression d'un Skill

Gestion des versions

Comment les Skills sont chargés

Cas d'usage

Skills organisationnels

Skills personnels

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 relatives à la mise en cache des prompts

Gestion des erreurs

Conservation des données

Prochaines étapes

Liens rapides

Vue d'ensemble

Utilisation des Skills

Prérequis

Utiliser les Skills dans les Messages

Paramètre container

Téléchargement des fichiers générés

Conversations multi-tours

Opérations de longue durée

Utilisation de plusieurs Skills

Gestion des Skills personnalisés

Création d'un Skill

Lister les Skills

Récupération d'un Skill

Suppression d'un Skill

Gestion des versions

Comment les Skills sont chargés

Cas d'usage

Skills organisationnels

Skills personnels

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 relatives à la mise en cache des prompts

Gestion des erreurs

Conservation des données

Prochaines étapes