Utilisation des Agent Skills avec l'API

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

This feature is not eligible for Zero Data Retention (ZDR). Data is retained according to the feature's standard retention policy.

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 plongée profonde dans l'architecture et les applications réelles 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é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.

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 les Skills de deux sources :

Aspect	Skills Anthropic	Skills personnalisés
Valeur Type	`anthropic`	`custom`
IDs des Skills	Noms courts : `pptx`, `xlsx`, `docx`, `pdf`	Générés : `skill_01AbCdEfGhIjKlMnOpQrStUv`
Format de version	Basé sur la date : `20251013` ou `latest`	Timestamp d'époque : `1759178010641129` ou `latest`

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 la provenance des Skills et la façon dont ils sont gérés.

Prérequis

Pour utiliser les Skills, vous avez besoin de :

Clé API Claude 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 conteneur
Outil d'exécution de code activé dans vos requêtes

Utilisation des Skills dans Messages

Paramètre Container

Les Skills sont spécifiés à l'aide du paramètre container dans l'API Messages. Vous pouvez inclure jusqu'à 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 incluez optionnellement version pour épingler une version spécifique :

Téléchargement des 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.

Fonctionnement :

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 vos besoins

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

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

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 :

Opérations longues

Les Skills peuvent effectuer des opérations qui nécessitent plusieurs tours. Gérez les raisons d'arrêt pause_turn :

La réponse peut inclure une raison d'arrêt pause_turn, qui indique que l'API a mis en pause une opération 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.

Utilisation de plusieurs compétences

Combinez plusieurs compétences dans une seule demande pour gérer des flux de travail complexes :

Gestion des compétences personnalisées

Création d'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 fichiers individuels.

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 à 30 MB
Exigences du frontmatter 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 demande/réponse, consultez la référence API Créer une compétence.

Énumération des compétences

Récupérez toutes les compétences disponibles dans 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 :

Consultez la référence API Énumérer les compétences pour les options de pagination et de filtrage.

Récupération d'une compétence

Obtenez les détails d'une compétence spécifique :

Suppression d'une Skill

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

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

Versioning

Les Skills supportent le versioning pour gérer les mises à jour de manière sécurisée :

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 auto-générés : 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

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écisions)
Générer des tâches suivant les conventions de l'équipe
Créer des résumés 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 Excel et l'analyse DCF personnalisée Skills :

Limites et contraintes

Limites des requêtes

Nombre maximum de Skills par requête : 8
Taille maximale du téléchargement de Skill : 30 MB (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és (affecte les performances)

Stratégie de gestion des versions

Pour la production :

# Pin to specific versions for stability
container = {
    "skills": [
        {
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": "1759178010641129",  # Specific version
        }
    ]
}

Pour le développement :

# Use latest for active development
container = {
    "skills": [
        {
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": "latest",  # Always get newest
        }
    ]
}

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 casse le cache :

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 :

Rétention des données

Les Agent Skills ne sont pas couverts par les arrangements ZDR. Les définitions de Skills et les données d'exécution sont conservées conformément à la politique standard de rétention des données d'Anthropic.

Pour l'admissibilité ZDR dans toutes les fonctionnalités, consultez Rétention des données et API.

Étapes suivantes

Référence API

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

Guide de rédaction

Meilleures pratiques pour rédiger des Skills efficaces

client = anthropic.Anthropic()

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

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

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

messages = [{"role": "user", "content": "Process this large dataset"}]
max_retries = 10

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

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

# Option 1: Upload individual files (one --file flag per file)
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: Upload a zip archive
ant beta:skills create \
  --display-title "Financial Analysis" \
  --file financial_analysis_skill.zip \
  --beta skills-2025-10-02

# Step 1: Delete all versions
ant beta:skills:versions list \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --transform version --format yaml \
  | tr -d '"' \
  | while read -r VERSION; do
      ant beta:skills:versions delete \
        --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
        --version "$VERSION" >/dev/null
    done

# Step 2: Delete the Skill
ant beta:skills delete \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv >/dev/null

# Create a new version
VERSION_NUMBER=$(ant beta:skills:versions create \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --file updated_skill/SKILL.md \
  --transform version --format yaml)

# Use specific version
ant beta:messages create \
  --beta code-execution-2025-08-25 \
  --beta skills-2025-10-02 <<YAML
model: claude-opus-4-7
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

# Use latest version
ant beta:messages create \
  --beta code-execution-2025-08-25 \
  --beta skills-2025-10-02 <<'YAML'
model: claude-opus-4-7
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

# Create custom DCF analysis Skill
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"],
)

# Use with Excel to create financial model
response = client.beta.messages.create(
    model="claude-opus-4-7",
    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"}],
)

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

# Adding/removing Skills breaks cache
response2 = client.beta.messages.create(
    model="claude-opus-4-7",
    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"}],
)

client = anthropic.Anthropic()

try:
    response = client.beta.messages.create(
        model="claude-opus-4-7",
        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}")
        # Handle skill-specific errors
    else:
        raise