Passer au contenu principal

​
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 :
  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 à partir du système de fichiers : Les Skills sont chargés à partir des emplacements du système de fichiers régis par settingSources (TypeScript) ou setting_sources (Python)
  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. 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.
Les Skills sont découverts via les sources de paramètres du système de fichiers. Avec les options query() par défaut, le SDK charge les sources utilisateur et projet, donc les skills dans ~/.claude/skills/, <cwd>/.claude/skills/, et .claude/skills/ dans n’importe quel répertoire parent de <cwd> jusqu’à la racine du référentiel sont disponibles. Si vous définissez settingSources explicitement, incluez 'user' ou 'project' pour maintenir la découverte des skills, ou utilisez l’option plugins pour charger les skills à partir d’un chemin spécifique.

​
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 ajoute automatiquement l’outil Skill à allowedTools. Si vous transmettez également une liste tools explicite, incluez "Skill" dans cette liste afin que Claude puisse invoquer les skills. 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())
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"])
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 lorsque setting_sources inclut "project"
  • User Skills (~/.claude/skills/) : Skills personnels dans 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 :

​
Restrictions d’outils

Le champ frontmatter allowed-tools dans SKILL.md n’est pris en charge que lors de l’utilisation directe de la CLI Claude Code. Il ne s’applique pas lors de l’utilisation de Skills via le SDK.Lors de l’utilisation du SDK, contrôlez l’accès aux outils via l’option principale allowedTools dans votre configuration de requête.
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é :
Les déclarations d’importation du premier exemple sont supposées dans les extraits de code suivants.
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)

​
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)
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)
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",
)
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 à partir de .claude/skills/ dans l’option cwd et dans chaque répertoire parent jusqu’à la racine du référentiel. Assurez-vous que cwd pointe vers ou en dessous du répertoire contenant .claude/skills/, dans le même référentiel : 
# Ensure your cwd points to the directory containing .claude/skills/
options = ClaudeAgentOptions(
    cwd="/path/to/project",  # .claude/skills/ here or in a parent directory
    setting_sources=["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

​
Ressources du SDK