Les compétences d’agent é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 compétences prédéfinies et personnalisées 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 :

Liens rapides

Aperçu

Pour une analyse approfondie de l’architecture et des applications réelles des compétences d’agent, lisez notre blog d’ingénierie : Équiper les agents pour le monde réel avec les compétences d’agent.
Les compétences s’intègrent à l’API Messages via l’outil d’exécution de code. Que vous utilisiez des compétences prédéfinies gérées par Anthropic ou des compétences personnalisées que vous avez téléchargé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 compétences

Les compétences s’intègrent de manière identique dans l’API Messages quel que soit leur source. Vous spécifiez les compétences dans le paramètre container avec un skill_id, un type et une version optionnelle, et elles s’exécutent dans l’environnement d’exécution de code. Vous pouvez utiliser les compétences de deux sources :
AspectCompétences AnthropicCompétences personnalisées
Valeur de typeanthropiccustom
IDs de compétenceNoms courts : pptx, xlsx, docx, pdfGénérés : skill_01AbCdEfGhIjKlMnOpQrStUv
Format de versionBasé sur la date : 20251013 ou latestHorodatage d’époque : 1759178010641129 ou latest
GestionPrédéfinies et maintenues par AnthropicTéléchargées et gérées via API Skills
DisponibilitéDisponibles pour tous les utilisateursPrivées pour votre espace de travail
Les deux sources de compétences 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 est la provenance des compétences et leur gestion.

Prérequis

Pour utiliser les compétences, vous avez besoin de :
  1. Clé API Anthropic depuis la Console
  2. En-têtes bêta :
    • code-execution-2025-08-25 - Active l’exécution de code (obligatoire pour les compétences)
    • 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 conteneur
  3. Outil d’exécution de code activé dans vos requêtes

Utiliser les compétences dans Messages

Paramètre Container

Les compétences sont spécifiées à l’aide du paramètre container dans l’API Messages. Vous pouvez inclure jusqu’à 8 compétences par requête. La structure est identique pour les compétences Anthropic et personnalisées—spécifiez le type et le skill_id requis, et incluez optionnellement version pour épingler une version spécifique :
import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    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 compétences 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 :
  1. Les compétences créent des fichiers lors de l’exécution du code
  2. La réponse inclut file_id pour chaque fichier créé
  3. Utilisez l’API Files pour télécharger le contenu du fichier réel
  4. Enregistrez localement ou traitez selon vos besoins
Exemple : Créer et télécharger un fichier Excel
import anthropic

client = anthropic.Anthropic()

# Étape 1 : Utiliser une compétence pour créer un fichier
response = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    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 IDs 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':
                for file in content_item.content:
                    if hasattr(file, 'file_id'):
                        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,
        betas=["files-api-2025-04-14"]
    )
    file_content = client.beta.files.download(
        file_id=file_id,
        betas=["files-api-2025-04-14"]
    )

    # É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 :
# Obtenir les métadonnées du fichier
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")

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

# Supprimer un fichier
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 conteneur sur plusieurs messages en spécifiant l’ID du conteneur :
# La première requête crée le conteneur
response1 = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    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"}]
)

# Continuer 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.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "id": response1.container.id,  # Réutiliser le conteneur
        "skills": [
            {"type": "anthropic", "skill_id": "xlsx", "version": "latest"}
        ]
    },
    messages=messages,
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)

Opérations longues

Les compétences 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.messages.create(
    model="claude-sonnet-4-5-20250929",
    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.messages.create(
        model="claude-sonnet-4-5-20250929",
        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 compétence 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 compétences

Combinez plusieurs compétences dans une seule requête pour gérer des flux de travail complexes :
response = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    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 compétences personnalisées

Créer une compétence

Téléchargez votre compétence personnalisée pour la 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 : Utiliser l'assistant files_from_dir (Python uniquement, recommandé)
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 : Utiliser un fichier zip
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 : Utiliser des tuples de fichier (nom de fichier, contenu du fichier, type mime)
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
  • Préambule YAML : name (64 caractères max), description (1024 caractères max)
Pour les schémas complets de requête/réponse, consultez la référence API Create Skill.

Lister les compétences

Récupérez toutes les compétences disponibles pour votre espace de travail, y compris les compétences prédéfinies Anthropic et vos compétences personnalisées. Utilisez le paramètre source pour filtrer par type de compétence :
# Lister toutes les compétences
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})")

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

Obtenez les détails d’une compétence 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 une compétence

Pour supprimer une compétence, vous devez d’abord supprimer toutes ses versions :
# Étape 1 : Supprimer toutes les 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"]
    )

# Étape 2 : Supprimer la compétence
client.beta.skills.delete(
    skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
    betas=["skills-2025-10-02"]
)
Toute tentative de suppression d’une compétence avec des versions existantes renverra une erreur 400.

Versioning

Les compétences supportent le versioning pour gérer les mises à jour en toute sécurité : Compétences 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é
Compétences personnalisées :
  • Horodatages d’époque 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 compétence
# 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.messages.create(
    model="claude-sonnet-4-5-20250929",
    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 version la plus récente
response = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    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 Create Skill Version pour plus de détails.

Comment les compétences sont chargées

Lorsque vous spécifiez des compétences dans un conteneur :
  1. Découverte des métadonnées : Claude voit les métadonnées de chaque compétence (nom, description) dans l’invite système
  2. Chargement des fichiers : Les fichiers de compétence sont copiés dans le conteneur à /skills/{directory}/
  3. Utilisation automatique : Claude charge et utilise automatiquement les compétences lorsqu’elles sont pertinentes pour votre demande
  4. Composition : Plusieurs compétences se composent ensemble pour les flux de travail complexes
L’architecture de divulgation progressive garantit une utilisation efficace du contexte—Claude ne charge les instructions complètes de compétence que lorsque cela est nécessaire.

Cas d’utilisation

Compétences 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

Compétences personnelles

Création de contenu
  • Modèles de document 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 compétences Excel et d’analyse DCF personnalisée :
# Créer une compétence 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.messages.create(
    model="claude-sonnet-4-5-20250929",
    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

  • Compétences maximales par requête : 8
  • Taille maximale de téléchargement de compétence : 8 Mo (tous les fichiers combinés)
  • Limites du préambule YAML : name 64 caractères, description 1024 caractères

Contraintes d’environnement

Les compétences s’exécutent dans le conteneur d’exécution de code avec ces limitations :
  • Pas d’accès réseau - Impossible d’effectuer des appels API externes
  • Pas d’installation de package d’exécution - Seuls les packages préinstallés disponibles
  • Environnement isolé - Chaque requête obtient un conteneur frais
Consultez la documentation de l’outil d’exécution de code pour les packages disponibles.

Meilleures pratiques

Quand utiliser plusieurs compétences

Combinez les compétences 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 document
À éviter :
  • Inclure des compétences 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 compétences dans votre conteneur cassera le cache :
# La première requête crée le cache
response1 = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    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 compétences casse le cache
response2 = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    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 compétences cohérente entre les requêtes.

Gestion des erreurs

Gérez les erreurs liées aux compétences avec élégance :
try:
    response = client.messages.create(
        model="claude-sonnet-4-5-20250929",
        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

Prochaines étapes