Compétences d'agent

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 contenant des instructions, des scripts et des ressources. Ce guide vous montre comment utiliser à la fois les Skills pré-construits et les Skills personnalisés avec l'API Claude.

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

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

Liens rapides

Commencer avec les Agent Skills

Créez votre premier Skill

Créer des Skills personnalisés

Meilleures pratiques pour la création de Skills

Aperçu

Pour une analyse approfondie de l'architecture et des applications réelles des Agent Skills, lisez notre blog d'ingénierie : Équiper les agents pour le monde réel avec les 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échargés, 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 quel que soit leur source. Vous spécifiez les Skills dans le paramètre container avec un skill_id, un type, et optionnellement une version, et ils s'exécutent dans l'environnement d'exécution de code.

Vous pouvez utiliser les Skills de deux sources :

Aspect	Skills Anthropic	Skills personnalisés
Valeur 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`	Timestamp epoch : `1759178010641129` ou `latest`
Gestion	Pré-construits et maintenus par Anthropic	Téléchargez 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 retourné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 est d'où proviennent les Skills et comment ils sont gérés.

Prérequis

Pour utiliser les Skills, vous avez besoin de :

Clé API Anthropic depuis la Console
En-têtes Beta :
- 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écharger/télécharger des fichiers vers/depuis le container
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 en utilisant le 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 le type et le skill_id requis, et optionnellement incluez version pour épingler à une version spécifique :

import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-6",
    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), ils retournent 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 lors de l'exécution du code
La réponse inclut 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 les besoins

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

import anthropic

client = anthropic.Anthropic()

# Step 1: Use a Skill to create a file
response = client.beta.messages.create(
    model="claude-opus-4-6",
    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"}]
)

# Step 2: Extract file IDs from the response
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':
                for file in content_item.content:
                    if hasattr(file, 'file_id'):
                        file_ids.append(file.file_id)
    return file_ids

# Step 3: Download the file using Files API
for file_id in extract_file_ids(response):
    file_metadata = client.beta.files.retrieve_metadata(
        file_id=file_id,
        betas=["files-api-2025-04-14"]
    )
    file_content = client.beta.files.download(
        file_id=file_id,
        betas=["files-api-2025-04-14"]
    )

    # Step 4: Save to disk
    file_content.write_to_file(file_metadata.filename)
    print(f"Downloaded: {file_metadata.filename}")

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

# Get file metadata
file_info = client.beta.files.retrieve_metadata(
    file_id=file_id,
    betas=["files-api-2025-04-14"]
)
print(f"Filename: {file_info.filename}, Size: {file_info.size_bytes} bytes")

# List all files
files = client.beta.files.list(betas=["files-api-2025-04-14"])
for file in files.data:
    print(f"{file.filename} - {file.created_at}")

# Delete a file
client.beta.files.delete(
    file_id=file_id,
    betas=["files-api-2025-04-14"]
)

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

Conversations multi-tours

Réutilisez le même container sur plusieurs messages en spécifiant l'ID du container :

# First request creates container
response1 = client.beta.messages.create(
    model="claude-opus-4-6",
    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"}]
)

# Continue conversation with same container
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-6",
    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 longues

Les Skills peuvent effectuer des opérations qui nécessitent 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-6",
    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"}]
)

# Handle pause_turn for long operations
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-6",
        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 longue. Vous pouvez fournir la réponse telle quelle dans une requête ultérieure pour laisser Claude continuer son tour, ou modifier le contenu si vous souhaitez interrompre la conversation et fournir des conseils supplémentaires.

Utiliser 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-6",
    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és

Créer un Skill

Téléchargez votre Skill personnalisé pour le rendre disponible dans votre espace de travail. Vous pouvez télécharger en utilisant soit un chemin de répertoire, soit des objets de fichier individuels.

import anthropic

client = anthropic.Anthropic()

# Option 1: Using files_from_dir helper (Python only, recommended)
from anthropic.lib import files_from_dir

skill = client.beta.skills.create(
    display_title="Financial Analysis",
    files=files_from_dir("/path/to/financial_analysis_skill"),
    betas=["skills-2025-10-02"]
)

# Option 2: Using a zip file
skill = client.beta.skills.create(
    display_title="Financial Analysis",
    files=[("skill.zip", open("financial_analysis_skill.zip", "rb"))],
    betas=["skills-2025-10-02"]
)

# Option 3: Using file tuples (filename, file_content, mime_type)
skill = client.beta.skills.create(
    display_title="Financial Analysis",
    files=[
        ("financial_skill/SKILL.md", open("financial_skill/SKILL.md", "rb"), "text/markdown"),
        ("financial_skill/analyze.py", open("financial_skill/analyze.py", "rb"), "text/x-python"),
    ],
    betas=["skills-2025-10-02"]
)

print(f"Created skill: {skill.id}")
print(f"Latest version: {skill.latest_version}")

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échargement doit être inférieure à 8 Mo
Exigences du préambule YAML :
- name : Maximum 64 caractères, lettres minuscules/chiffres/tirets 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 API Create Skill.

Lister les Skills

Récupérez tous les Skills disponibles pour votre espace de travail, y compris les Skills pré-construits Anthropic et vos Skills personnalisés. Utilisez le paramètre source pour filtrer par type de skill :

# List all Skills
skills = client.beta.skills.list(
    betas=["skills-2025-10-02"]
)

for skill in skills.data:
    print(f"{skill.id}: {skill.display_title} (source: {skill.source})")

# List only custom Skills
custom_skills = client.beta.skills.list(
    source="custom",
    betas=["skills-2025-10-02"]
)

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

Récupérer un Skill

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

skill = client.beta.skills.retrieve(
    skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
    betas=["skills-2025-10-02"]
)

print(f"Skill: {skill.display_title}")
print(f"Latest version: {skill.latest_version}")
print(f"Created: {skill.created_at}")

Supprimer un Skill

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

# Step 1: Delete all versions
versions = client.beta.skills.versions.list(
    skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
    betas=["skills-2025-10-02"]
)

for version in versions.data:
    client.beta.skills.versions.delete(
        skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
        version=version.version,
        betas=["skills-2025-10-02"]
    )

# Step 2: Delete the Skill
client.beta.skills.delete(
    skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
    betas=["skills-2025-10-02"]
)

Toute tentative de suppression d'un Skill avec des versions existantes retournera une erreur 400.

Versioning

Les Skills supportent le versioning pour gérer les mises à jour en toute sécurité :

Skills gérées par Anthropic :

Les versions utilisent le format de date : 20251013
Les nouvelles versions sont publiées au fur et à mesure des mises à jour
Spécifiez les 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 Skill

# Créer une nouvelle version
from anthropic.lib import files_from_dir

new_version = client.beta.skills.versions.create(
    skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
    files=files_from_dir("/path/to/updated_skill"),
    betas=["skills-2025-10-02"]
)

# Utiliser une version spécifique
response = client.beta.messages.create(
    model="claude-opus-4-6",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [{
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": new_version.version
        }]
    },
    messages=[{"role": "user", "content": "Use updated Skill"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)

# Utiliser la dernière version
response = client.beta.messages.create(
    model="claude-opus-4-6",
    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": "Use latest Skill version"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)

Consultez la référence API Créer une version de Skill pour plus de 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 Skill sont copiés dans le conteneur à /skills/{directory}/
Utilisation automatique : Claude charge et utilise automatiquement les Skills lorsqu'elles sont pertinentes pour votre demande
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 de Skill que lorsque cela est nécessaire.

Cas d'usage

Skills organisationnelles

Marque et communications

Appliquer le formatage spécifique à l'entreprise (couleurs, polices, mises en page) aux documents
Générer des communications suivant les modèles organisationnels
Assurer la cohérence des directives de marque dans tous les résultats

Gestion de projet

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

Opérations commerciales

Créer des rapports, propositions et analyses conformes à 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
Formatage et style spécialisés
Génération de contenu spécifique au 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 à l'industrie

Développement et automatisation

Modèles de génération de code
Cadres de test
Flux de travail de déploiement

Exemple : Modélisation financière

Combinez les Skills Excel et analyse DCF personnalisée :

# Créer une Skill d'analyse DCF personnalisée
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"),
    betas=["skills-2025-10-02"]
)

# Utiliser avec Excel pour créer un modèle financier
response = client.beta.messages.create(
    model="claude-opus-4-6",
    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"}]
)

Limites et contraintes

Limites de requête

Nombre maximum de Skills par requête : 8
Taille maximale de téléchargement de Skill : 8 Mo (tous les fichiers combinés)
Exigences du frontmatter YAML :
- name : Maximum 64 caractères, lettres minuscules/chiffres/tirets uniquement, pas de balises XML, pas de mots réservés
- 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 ces limitations :

Pas d'accès réseau - Impossible de faire des appels API externes
Pas d'installation de paquets à l'exécution - Seuls les paquets préinstallés sont disponibles
Environnement isolé - Chaque requête obtient un conteneur frais

Consultez la documentation de l'outil d'exécution de code pour les paquets disponibles.

Bonnes pratiques

Quand utiliser plusieurs Skills

Combinez les 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 rapports (Word) + export en PDF
Logique de domaine personnalisée + génération de documents

À éviter :

Inclure des Skills inutilisées (affecte 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"  # Version spécifique
    }]
}

Pour le développement :

# Utiliser latest pour le développement actif
container={
    "skills": [{
        "type": "custom",
        "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
        "version": "latest"  # Toujours obtenir la plus récente
    }]
}

Considérations relatives à la mise en cache des invites

Lors de l'utilisation de la mise en cache des invites, notez que la modification de la liste des Skills dans votre conteneur cassera le cache :

# La première requête crée le cache
response1 = client.beta.messages.create(
    model="claude-opus-4-6",
    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/supprimer des Skills casse le cache
response2 = client.beta.messages.create(
    model="claude-opus-4-6",
    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 les 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 :

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

Étapes suivantes

Référence API

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

Guide de rédaction

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?

Compétences d'agent

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 incluant les schémas de requête/réponse et tous les paramètres, consultez :

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

Liens rapides

Commencer avec les Agent Skills

Créez votre premier Skill

Créer des Skills personnalisés

Meilleures pratiques pour la création de Skills

Aperçu

Pour une analyse approfondie de l'architecture et des applications réelles des Agent Skills, lisez notre blog d'ingénierie : Équiper les agents pour le monde réel avec les Agent Skills.

Utiliser les Skills

Vous pouvez utiliser les Skills de deux sources :

Aspect	Skills Anthropic	Skills personnalisés
Valeur 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`	Timestamp epoch : `1759178010641129` ou `latest`
Gestion	Pré-construits et maintenus par Anthropic	Téléchargez 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 :

Clé API Anthropic depuis la Console
En-têtes Beta :
- 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écharger/télécharger des fichiers vers/depuis le container
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 en utilisant le 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 le type et le skill_id requis, et optionnellement incluez version pour épingler à une version spécifique :

import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-6",
    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), ils retournent 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 lors de l'exécution du code
La réponse inclut 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 les besoins

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

import anthropic

client = anthropic.Anthropic()

# Step 1: Use a Skill to create a file
response = client.beta.messages.create(
    model="claude-opus-4-6",
    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"}]
)

# Step 2: Extract file IDs from the response
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':
                for file in content_item.content:
                    if hasattr(file, 'file_id'):
                        file_ids.append(file.file_id)
    return file_ids

# Step 3: Download the file using Files API
for file_id in extract_file_ids(response):
    file_metadata = client.beta.files.retrieve_metadata(
        file_id=file_id,
        betas=["files-api-2025-04-14"]
    )
    file_content = client.beta.files.download(
        file_id=file_id,
        betas=["files-api-2025-04-14"]
    )

    # Step 4: Save to disk
    file_content.write_to_file(file_metadata.filename)
    print(f"Downloaded: {file_metadata.filename}")

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

# Get file metadata
file_info = client.beta.files.retrieve_metadata(
    file_id=file_id,
    betas=["files-api-2025-04-14"]
)
print(f"Filename: {file_info.filename}, Size: {file_info.size_bytes} bytes")

# List all files
files = client.beta.files.list(betas=["files-api-2025-04-14"])
for file in files.data:
    print(f"{file.filename} - {file.created_at}")

# Delete a file
client.beta.files.delete(
    file_id=file_id,
    betas=["files-api-2025-04-14"]
)

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

Conversations multi-tours

Réutilisez le même container sur plusieurs messages en spécifiant l'ID du container :

# First request creates container
response1 = client.beta.messages.create(
    model="claude-opus-4-6",
    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"}]
)

# Continue conversation with same container
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-6",
    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 longues

Les Skills peuvent effectuer des opérations qui nécessitent 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-6",
    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"}]
)

# Handle pause_turn for long operations
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-6",
        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 :

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

Créer un Skill

import anthropic

client = anthropic.Anthropic()

# Option 1: Using files_from_dir helper (Python only, recommended)
from anthropic.lib import files_from_dir

skill = client.beta.skills.create(
    display_title="Financial Analysis",
    files=files_from_dir("/path/to/financial_analysis_skill"),
    betas=["skills-2025-10-02"]
)

# Option 2: Using a zip file
skill = client.beta.skills.create(
    display_title="Financial Analysis",
    files=[("skill.zip", open("financial_analysis_skill.zip", "rb"))],
    betas=["skills-2025-10-02"]
)

# Option 3: Using file tuples (filename, file_content, mime_type)
skill = client.beta.skills.create(
    display_title="Financial Analysis",
    files=[
        ("financial_skill/SKILL.md", open("financial_skill/SKILL.md", "rb"), "text/markdown"),
        ("financial_skill/analyze.py", open("financial_skill/analyze.py", "rb"), "text/x-python"),
    ],
    betas=["skills-2025-10-02"]
)

print(f"Created skill: {skill.id}")
print(f"Latest version: {skill.latest_version}")

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échargement doit être inférieure à 8 Mo
Exigences du préambule YAML :
- name : Maximum 64 caractères, lettres minuscules/chiffres/tirets 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 API Create Skill.

Lister les Skills

# List all Skills
skills = client.beta.skills.list(
    betas=["skills-2025-10-02"]
)

for skill in skills.data:
    print(f"{skill.id}: {skill.display_title} (source: {skill.source})")

# List only custom Skills
custom_skills = client.beta.skills.list(
    source="custom",
    betas=["skills-2025-10-02"]
)

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

Récupérer un Skill

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

skill = client.beta.skills.retrieve(
    skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
    betas=["skills-2025-10-02"]
)

print(f"Skill: {skill.display_title}")
print(f"Latest version: {skill.latest_version}")
print(f"Created: {skill.created_at}")

Supprimer un Skill

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

# Step 1: Delete all versions
versions = client.beta.skills.versions.list(
    skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
    betas=["skills-2025-10-02"]
)

for version in versions.data:
    client.beta.skills.versions.delete(
        skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
        version=version.version,
        betas=["skills-2025-10-02"]
    )

# Step 2: Delete the Skill
client.beta.skills.delete(
    skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
    betas=["skills-2025-10-02"]
)

Toute tentative de suppression d'un Skill avec des versions existantes retournera une erreur 400.

Versioning

Les Skills supportent le versioning pour gérer les mises à jour en toute sécurité :

Skills gérées par Anthropic :

Les versions utilisent le format de date : 20251013
Les nouvelles versions sont publiées au fur et à mesure des mises à jour
Spécifiez les 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 Skill

# Créer une nouvelle version
from anthropic.lib import files_from_dir

new_version = client.beta.skills.versions.create(
    skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
    files=files_from_dir("/path/to/updated_skill"),
    betas=["skills-2025-10-02"]
)

# Utiliser une version spécifique
response = client.beta.messages.create(
    model="claude-opus-4-6",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [{
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": new_version.version
        }]
    },
    messages=[{"role": "user", "content": "Use updated Skill"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)

# Utiliser la dernière version
response = client.beta.messages.create(
    model="claude-opus-4-6",
    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": "Use latest Skill version"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)

Consultez la référence API Créer une version de Skill pour plus de 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 Skill sont copiés dans le conteneur à /skills/{directory}/
Utilisation automatique : Claude charge et utilise automatiquement les Skills lorsqu'elles sont pertinentes pour votre demande
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 de Skill que lorsque cela est nécessaire.

Cas d'usage

Skills organisationnelles

Marque et communications

Appliquer le formatage spécifique à l'entreprise (couleurs, polices, mises en page) aux documents
Générer des communications suivant les modèles organisationnels
Assurer la cohérence des directives de marque dans tous les résultats

Gestion de projet

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

Opérations commerciales

Créer des rapports, propositions et analyses conformes à 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
Formatage et style spécialisés
Génération de contenu spécifique au 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 à l'industrie

Développement et automatisation

Modèles de génération de code
Cadres de test
Flux de travail de déploiement

Exemple : Modélisation financière

Combinez les Skills Excel et analyse DCF personnalisée :

# Créer une Skill d'analyse DCF personnalisée
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"),
    betas=["skills-2025-10-02"]
)

# Utiliser avec Excel pour créer un modèle financier
response = client.beta.messages.create(
    model="claude-opus-4-6",
    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"}]
)

Limites et contraintes

Limites de requête

Nombre maximum de Skills par requête : 8
Taille maximale de téléchargement de Skill : 8 Mo (tous les fichiers combinés)
Exigences du frontmatter YAML :
- name : Maximum 64 caractères, lettres minuscules/chiffres/tirets uniquement, pas de balises XML, pas de mots réservés
- 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 ces limitations :

Pas d'accès réseau - Impossible de faire des appels API externes
Pas d'installation de paquets à l'exécution - Seuls les paquets préinstallés sont disponibles
Environnement isolé - Chaque requête obtient un conteneur frais

Consultez la documentation de l'outil d'exécution de code pour les paquets disponibles.

Bonnes pratiques

Quand utiliser plusieurs Skills

Combinez les 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 rapports (Word) + export en PDF
Logique de domaine personnalisée + génération de documents

À éviter :

Inclure des Skills inutilisées (affecte 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"  # Version spécifique
    }]
}

Pour le développement :

# Utiliser latest pour le développement actif
container={
    "skills": [{
        "type": "custom",
        "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
        "version": "latest"  # Toujours obtenir la plus récente
    }]
}

Considérations relatives à la mise en cache des invites

Lors de l'utilisation de la mise en cache des invites, notez que la modification de la liste des Skills dans votre conteneur cassera le cache :

# La première requête crée le cache
response1 = client.beta.messages.create(
    model="claude-opus-4-6",
    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/supprimer des Skills casse le cache
response2 = client.beta.messages.create(
    model="claude-opus-4-6",
    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 les 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 :

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

Étapes suivantes

Référence API

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

Guide de rédaction

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?