Agent Skills dans le SDK
Étendez Claude avec des capacités spécialisées en utilisant Agent Skills dans le Claude Agent SDK
Aperçu
Agent Skills étendent Claude avec des capacités spécialisées que Claude invoque de manière autonome lorsque c'est pertinent. Les Skills sont empaquetés sous forme de fichiers SKILL.md contenant des instructions, des descriptions et des ressources de support optionnelles.
Pour des informations complètes sur les Skills, y compris les avantages, l'architecture et les directives de création, consultez l'aperçu d'Agent Skills.
Comment les Skills fonctionnent avec le SDK
Lors de l'utilisation du Claude Agent SDK, les Skills sont :
- Définis comme des artefacts du système de fichiers : Créés sous forme de fichiers
SKILL.mddans des répertoires spécifiques (.claude/skills/) - Chargés à partir du système de fichiers : Les Skills sont chargés à partir des emplacements du système de fichiers régis par
settingSources(TypeScript) ousetting_sources(Python) - Découverts automatiquement : Une fois que les paramètres du système de fichiers sont chargés, les métadonnées des Skills sont découvertes au démarrage à partir des répertoires utilisateur et projet ; le contenu complet est chargé lorsqu'il est déclenché
- Invoqués par le modèle : Claude choisit de manière autonome quand les utiliser en fonction du contexte
- Filtrés via l'option
skills: Les Skills découverts sont activés par défaut. Passez une liste de noms de Skills,"all", ou[]pour contrôler lesquels sont disponibles dans la session
Contrairement aux sous-agents (qui peuvent être définis par programmation), les Skills doivent être créés comme des artefacts du système de fichiers. Le SDK ne fournit pas d'API programmatique pour enregistrer les Skills.
Utilisation des Skills avec le SDK
Définissez l'option skills sur query() pour contrôler quels Skills sont disponibles pour la session. Lorsqu'elle est omise, les Skills découverts sont activés et l'outil Skill est disponible, ce qui correspond au comportement de la CLI. Passez "all" pour activer chaque Skill découvert, une liste de noms de Skills pour activer uniquement ceux-ci, ou [] pour désactiver tous les Skills. Lorsque vous définissez skills, le SDK active automatiquement l'outil Skill, vous n'avez donc pas besoin de le lister dans allowedTools.
Une fois configuré, Claude découvre automatiquement les Skills à partir du système de fichiers et les invoque lorsque c'est pertinent pour la demande de l'utilisateur.
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
options = ClaudeAgentOptions(
cwd="/path/to/project", # Project with .claude/skills/
setting_sources=["user", "project"], # Load Skills from filesystem
skills="all", # Enable every discovered Skill
allowed_tools=["Read", "Write", "Bash"],
)
async for message in query(
prompt="Help me process this PDF document", options=options
):
print(message)
asyncio.run(main())
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "Help me process this PDF document",
options: {
cwd: "/path/to/project", // Project with .claude/skills/
settingSources: ["user", "project"], // Load Skills from filesystem
skills: "all", // Enable every discovered Skill
allowedTools: ["Read", "Write", "Bash"]
}
})) {
console.log(message);
}
Pour activer uniquement des Skills spécifiques, passez leurs noms. Les noms correspondent au champ name dans SKILL.md ou au nom du répertoire du Skill. Utilisez plugin:skill pour les Skills fournis par les plugins.
options = ClaudeAgentOptions(skills=["pdf", "docx"])
const options = { skills: ["pdf", "docx"] };
L'option skills est un filtre de contexte, pas un bac à sable. Les Skills non listés sont masqués au modèle et rejetés par l'outil Skill, mais leurs fichiers restent sur le disque et sont accessibles via Read et Bash.
Emplacements des Skills
Les Skills sont chargés à partir des répertoires du système de fichiers en fonction de votre configuration settingSources/setting_sources :
- Project Skills (
.claude/skills/) : Partagés avec votre équipe via git - chargés lorsquesetting_sourcesinclut"project" - User Skills (
~/.claude/skills/) : Skills personnels dans tous les projets - chargés lorsquesetting_sourcesinclut"user" - Plugin Skills : Fournis avec les plugins Claude Code installés
Création de Skills
Les Skills sont définis comme des répertoires contenant un fichier SKILL.md avec un frontmatter YAML et du contenu Markdown. Le champ description détermine quand Claude invoque votre Skill.
Exemple de structure de répertoire :
.claude/skills/processing-pdfs/
└── SKILL.md
Pour des conseils complets sur la création de Skills, y compris la structure SKILL.md, les Skills multi-fichiers et les exemples, consultez :
- Agent Skills dans Claude Code : Guide complet avec des exemples
- Agent Skills Best Practices : Directives de création et conventions de nommage
Restrictions d'outils
Pour contrôler l'accès aux outils pour les Skills dans les applications SDK, utilisez allowedTools pour pré-approuver des outils spécifiques. Sans un rappel canUseTool, tout ce qui ne figure pas dans la liste est refusé :
options = ClaudeAgentOptions(
setting_sources=["user", "project"], # Load Skills from filesystem
skills="all",
allowed_tools=["Read", "Grep", "Glob"],
)
async for message in query(prompt="Analyze the codebase structure", options=options):
print(message)
for await (const message of query({
prompt: "Analyze the codebase structure",
options: {
settingSources: ["user", "project"], // Load Skills from filesystem
skills: "all",
allowedTools: ["Read", "Grep", "Glob"],
permissionMode: "dontAsk" // Deny anything not in allowedTools
}
})) {
console.log(message);
}
Découverte des Skills disponibles
Pour voir quels Skills sont disponibles dans votre application SDK, demandez simplement à Claude :
options = ClaudeAgentOptions(
setting_sources=["user", "project"], # Load Skills from filesystem
skills="all",
)
async for message in query(prompt="What Skills are available?", options=options):
print(message)
for await (const message of query({
prompt: "What Skills are available?",
options: {
settingSources: ["user", "project"], // Load Skills from filesystem
skills: "all"
}
})) {
console.log(message);
}
Claude listera les Skills disponibles en fonction de votre répertoire de travail actuel et des plugins installés.
Test des Skills
Testez les Skills en posant des questions qui correspondent à leurs descriptions :
options = ClaudeAgentOptions(
cwd="/path/to/project",
setting_sources=["user", "project"], # Load Skills from filesystem
skills="all",
allowed_tools=["Read", "Bash"],
)
async for message in query(prompt="Extract text from invoice.pdf", options=options):
print(message)
for await (const message of query({
prompt: "Extract text from invoice.pdf",
options: {
cwd: "/path/to/project",
settingSources: ["user", "project"], // Load Skills from filesystem
skills: "all",
allowedTools: ["Read", "Bash"]
}
})) {
console.log(message);
}
Claude invoque automatiquement le Skill pertinent si la description correspond à votre demande.
Dépannage
Skills non trouvés
Vérifiez la configuration settingSources : Les Skills sont découverts via les sources de paramètres user et project. Si vous définissez settingSources/setting_sources explicitement et omettez ces sources, les skills ne sont pas chargés :
# Skills not loaded: setting_sources excludes user and project
options = ClaudeAgentOptions(setting_sources=[], skills="all")
# Skills loaded: user and project sources included
options = ClaudeAgentOptions(
setting_sources=["user", "project"],
skills="all",
)
// Skills not loaded: settingSources excludes user and project
const options = {
settingSources: [],
skills: "all"
};
// Skills loaded: user and project sources included
const options = {
settingSources: ["user", "project"],
skills: "all"
};
Pour plus de détails sur settingSources/setting_sources, consultez la référence du SDK TypeScript ou la référence du SDK Python.
Vérifiez le répertoire de travail : Le SDK charge les Skills par rapport à l'option cwd. Assurez-vous qu'elle pointe vers un répertoire contenant .claude/skills/ :
# Ensure your cwd points to the directory containing .claude/skills/
options = ClaudeAgentOptions(
cwd="/path/to/project", # Must contain .claude/skills/
setting_sources=["user", "project"], # Loads skills from these sources
skills="all",
)
// Ensure your cwd points to the directory containing .claude/skills/
const options = {
cwd: "/path/to/project", // Must contain .claude/skills/
settingSources: ["user", "project"], // Loads skills from these sources
skills: "all"
};
Consultez la section « Utilisation des Skills avec le SDK » ci-dessus pour le modèle complet.
Vérifiez l'emplacement du système de fichiers :
# Check project Skills
ls .claude/skills/*/SKILL.md
# Check personal Skills
ls ~/.claude/skills/*/SKILL.md
Skill non utilisé
Vérifiez l'option skills : Si vous avez passé une liste skills, confirmez que le nom du skill est inclus. Passer [] désactive tous les skills.
Vérifiez la description : Assurez-vous qu'elle est spécifique et inclut les mots-clés pertinents. Consultez Agent Skills Best Practices pour des conseils sur la rédaction de descriptions efficaces.
Dépannage supplémentaire
Pour le dépannage général des Skills (syntaxe YAML, débogage, etc.), consultez la section dépannage des Skills de Claude Code.
Documentation connexe
Guides des Skills
- Agent Skills dans Claude Code : Guide complet des Skills avec création, exemples et dépannage
- Agent Skills Overview : Aperçu conceptuel, avantages et architecture
- Agent Skills Best Practices : Directives de création pour des Skills efficaces
- Agent Skills Cookbook : Exemples de Skills et modèles
Ressources du SDK
- Subagents dans le SDK : Agents similaires basés sur le système de fichiers avec options programmatiques
- Slash Commands dans le SDK : Commandes invoquées par l'utilisateur
- Aperçu du SDK : Concepts généraux du SDK
- Référence du SDK TypeScript : Documentation complète de l'API
- Référence du SDK Python : Documentation complète de l'API