Utilisation des compétences d'agent avec l'API
Les compétences d'agent étendent les capacités de Claude par le biais de 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 :
- Référence API de gestion des compétences - Opérations CRUD pour les compétences
- Référence API des versions de compétences - Gestion des versions
Liens rapides
Commencer avec les compétences d'agent
Créez votre première compétence
Créer des compétences personnalisées
Meilleures pratiques pour la création de compétences
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.
Utilisation des compétences
Les compétences s'intègrent de manière identique dans l'API Messages indépendamment de la 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 des compétences de deux sources :
| Aspect | Compétences Anthropic | Compétences personnalisées |
|---|---|---|
| Valeur de type | anthropic | custom |
| IDs de compétence | 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 |
| Gestion | Prédéfinies et maintenues par Anthropic | Téléchargées et gérées via API Skills |
| Disponibilité | Disponibles pour tous les utilisateurs | Privé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 :
- Clé API Anthropic de la Console
- En-têtes bêta :
code-execution-2025-08-25- Active l'exécution de code (requis pour les compétences)skills-2025-10-02- Active l'API Skillsfiles-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 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 éventuellement version pour épingler une version spécifique :
import anthropic
client = anthropic.Anthropic()
response = client.beta.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"
}]
)import Anthropic from '@anthropic-ai/sdk';
const client = new Anthropic();
const response = await client.beta.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'
}]
});curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: code-execution-2025-08-25,skills-2025-10-02" \
-H "content-type: application/json" \
-d '{
"model": "claude-sonnet-4-5-20250929",
"max_tokens": 4096,
"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 compétences créent des documents (Excel, PowerPoint, PDF, Word), elles 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 compétences créent des fichiers lors de l'exécution du code
- La réponse inclut
file_idpour chaque fichier créé - Utilisez l'API Files pour télécharger le contenu du fichier réel
- 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-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"}]
)
# 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 conteneur sur plusieurs messages en spécifiant l'ID du conteneur :
# First request creates container
response1 = client.beta.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"}]
)
# 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-sonnet-4-5-20250929",
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 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.beta.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"}]
)
# 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-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 de longue durée. 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 requête pour gérer des flux de travail complexes :
response = client.beta.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"
}]
)Gestion des 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: 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 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 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 :
# 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 une compétence
Obtenez des détails sur 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 :
# 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'une compétence avec des versions existantes retournera une erreur 400.
Versioning
Les compétences prennent en charge 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 que les mises à jour sont effectuées
- Spécifiez les versions exactes pour la stabilité
Compétences personnalisées :
- Timestamps 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
# Create a new 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"]
)
# Use specific version
response = client.beta.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"}]
)
# Use latest version
response = client.beta.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 :
- Découverte des métadonnées : Claude voit les métadonnées de chaque compétence (nom, description) dans l'invite système
- Chargement des fichiers : Les fichiers de compétence sont copiés dans le conteneur à
/skills/{directory}/ - Utilisation automatique : Claude charge et utilise automatiquement les compétences lorsqu'elles sont pertinentes pour votre demande
- Composition : Plusieurs compétences 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 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 :
# 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-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
- Nombre maximum de compétences par requête : 8
- Taille maximale du téléchargement de compétence : 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ésdescription: Maximum 1024 caractères, non vide, pas de balises XML
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 de faire des appels API externes
- Pas d'installation de paquets d'exécution - Seuls les paquets 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 paquets 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 :
# 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 compétences dans votre conteneur cassera le cache :
# First request creates cache
response1 = client.beta.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"}]
)
# Adding/removing Skills breaks cache
response2 = client.beta.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.beta.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}")
# Handle skill-specific errors
else:
raise