Agent Skills dans le SDK

Aperçu

Agent Skills étend Claude avec des capacités spécialisées que Claude invoque de manière autonome lorsqu'elles sont pertinentes. 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 :

1. Définis comme des artefacts du système de fichiers : Créés sous forme de fichiers SKILL.md dans des répertoires spécifiques (.claude/skills/)
2. Chargés depuis le système de fichiers : Les Skills sont chargés à partir des emplacements du système de fichiers configurés. Vous devez spécifier settingSources (TypeScript) ou setting_sources (Python) pour charger les Skills depuis le système de fichiers
3. 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é
4. Invoqués par le modèle : Claude choisit de manière autonome quand les utiliser en fonction du contexte
5. Activés via allowed_tools : Ajoutez "Skill" à votre allowed_tools pour activer les Skills

Contrairement aux subagents (qui peuvent être définis de manière programmatique), 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

Pour utiliser les Skills avec le SDK, vous devez :

1. Inclure "Skill" dans votre configuration allowed_tools
2. Configurer settingSources/setting_sources pour charger les Skills depuis le système de fichiers

Une fois configuré, Claude découvre automatiquement les Skills à partir des répertoires spécifiés et les invoque lorsqu'ils sont pertinents 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
        allowed_tools=["Skill", "Read", "Write", "Bash"]  # Enable Skill tool
    )

    async for message in query(
        prompt="Help me process this PDF document",
        options=options
    ):
        print(message)

asyncio.run(main())

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 lorsque setting_sources inclut "project"
• User Skills (~/.claude/skills/) : Skills personnels sur tous les projets - chargés lorsque setting_sources inclut "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 exemples
• Agent Skills Best Practices : Directives de création et conventions de nommage
• Agent Skills Cookbook : Exemples de Skills et modèles

Restrictions d'outils

Pour restreindre les outils pour les Skills dans les applications SDK, utilisez l'option allowedTools :

options = ClaudeAgentOptions(
    setting_sources=["user", "project"],  # Load Skills from filesystem
    allowed_tools=["Skill", "Read", "Grep", "Glob"]  # Restricted toolset
)

async for message in query(
    prompt="Analyze the codebase structure",
    options=options
):
    print(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
    allowed_tools=["Skill"]
)

async for message in query(
    prompt="What Skills are available?",
    options=options
):
    print(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
    allowed_tools=["Skill", "Read", "Bash"]
)

async for message in query(
    prompt="Extract text from invoice.pdf",
    options=options
):
    print(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 ne sont chargés que lorsque vous configurez explicitement settingSources/setting_sources. C'est le problème le plus courant :

# Wrong - Skills won't be loaded
options = ClaudeAgentOptions(
    allowed_tools=["Skill"]
)

# Correct - Skills will be loaded
options = ClaudeAgentOptions(
    setting_sources=["user", "project"],  # Required to load Skills
    allowed_tools=["Skill"]
)

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"],  # Required to load Skills
    allowed_tools=["Skill"]
)

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 que l'outil Skill est activé : Confirmez que "Skill" est dans votre allowedTools.

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 in the SDK : Agents basés sur le système de fichiers similaires avec options programmatiques
• Slash Commands in the SDK : Commandes invoquées par l'utilisateur
• SDK Overview : Concepts généraux du SDK
• TypeScript SDK Reference : Documentation complète de l'API
• Python SDK Reference : Documentation complète de l'API