Structure de base de Skills
L'essence même des Skills est de fournir à l'IA des directives opérationnelles qui définissent des processus d'exécution standardisés. Une fois écrites, ces règles peuvent être invoquées de manière répétée et directement réutilisées, tout comme des fonctions de programme.
Les Skills sont stockés sous forme de texte Markdown et n'exécutent pas eux-mêmes directement de fonctions.
Les Skills offrent un chargement à la demande et une invocation progressive, accumulant efficacement l'expérience de travail et permettant une réutilisation rapide et un transfert précis des capacités.
La structure de base d'un Skill
Le cœur des Skills est :Un dossier + un fichier SKILL.md。
Le fichier SKILL.md contient :
- Métadonnées (au moins un nom et une description)
- Des instructions indiquant à l'IA comment accomplir une tâche spécifique
Une compétence est essentiellement un fichier Markdown (avec le nom de fichier fixé à SKILL.md)
my-skill/ └── SKILL.md （唯一必需）
Modèle de base de SKILL.md :
--- name: your-skill-name description: 一句话描述该 Skill 的功能和使用场景 --- # Skill 名称 ## 使用指引 [给 AI 的分步骤行为指引] ## 示例 [该 Skill 的具体使用示例]
L'intégralité du fichier SKILL.md est divisée en deux parties : la partie entourée par------ est le frontmatter YAML (configuration d'en-tête), et la partie en dessous est le corps Markdown (instructions d'exécution).
| Champ | Requis | Description | Exemple |
|---|---|---|---|
name | Oui | L'identifiant unique de la compétence, nommé en kebab-case. Il est référencé par les commandes / et est le champ clé permettant au système d'identifier la compétence. | web-design-guidelines |
description | Oui | Une description en une phrase de la fonctionnalité et des scénarios de déclenchement. Plus le contenu est spécifique, plus le déclenchement est précis. | UI/UX design review for web pages |
Ensuite, décomposons chaque partie :
Frontmatter : deux champs obligatoires
Le frontmatter est le bloc de configuration YAML entouré par --- en haut de SKILL.md, servant d'informations d'identité pour l'ensemble de la compétence.
La spécification officielle ne requiert que deux champs :
Champ 1 : name (nom de la compétence)
Le champ name peut contenir jusqu'à 64 caractères et ne peut comporter que des lettres minuscules, des chiffres et des traits d'union.
name: processing-pdfs # 好：动名词形式，清晰描述功能 name: analyzing-spreadsheets # 好：一眼知道用途 name: my-brand-guidelines # 好：组织专属知识 name: helper # 差：太模糊 name: MySkill # 差：包含大写字母（不合规） name: data files # 差：包含空格（不合规）
Il est recommandé d'utiliser la forme gérondive (verbe + -ing) pour nommer, comme processing-pdfs, analyzing-spreadsheets, afin de décrire clairement l'activité ou la capacité fournie par la compétence.
| Recommandé | Non recommandé | Raison |
|---|---|---|
code-reviewer | CodeReviewer | Utilisez des minuscules et des traits d'union cohérents pour éviter les problèmes de compatibilité multiplateforme |
sql-optimizer | sql_optimizer | kebab-case est le format conventionnel, en le gardant cohérent avec le nom du répertoire |
deploy-check | deploy-check-tool-v2 | Le nom doit être court ; les informations de version vont dans la description interne du fichier |
Champ 2 : description (description de la condition de déclenchement)
C'est le champ le plus important. Au démarrage, le système ne précharge que le nom et la description de tous les Skills dans le prompt système.
Ce n'est que lorsque l'IA détermine que la description est pertinente pour la tâche en cours qu'elle lit le contenu complet de SKILL.md.
La description doit contenir deux parties :Ce que ce Skill fait, et quand Claude doit l'utiliser.
description: | Use when the user needs to create, read, edit, or generate Word documents (.docx). Triggers include: 'Word doc', 'word document', '.docx', 'report', 'letter', 'memo', or any request to produce a formatted document for sharing or printing.
Corps Markdown : structure interne des instructions d'exécution
| Recommandé | Non recommandé | Raison |
|---|---|---|
| "Analyser le code Python pour détecter les risques d'injection SQL et fournir des suggestions de correction" | "Un outil de sécurité" | La description est trop vague pour se déclencher avec précision |
| "Convertir du Markdown en e-mails HTML conformes aux directives de la marque" | "Convertir des formats de fichiers" | Manque de scénarios spécifiques et peut être déclenché par erreur dans d'autres tâches |
Après le Frontmatter vient le corps Markdown, qui indique à l'IA exactement comment faire les choses.
Il contient au moins deux sections :
Exemples de SKILL.md
Modèle de base de SKILL.md :
--- name: pdf-processing description: 从 PDF 中提取文本和表格，填写表单，并合并文档 --- # PDF 处理 ## 使用场景 当需要对 PDF 文件进行操作时使用，例如： - 提取 PDF 文本或表格数据 - 填写 PDF 表单 - 合并多个 PDF 文件 ## 提取文本 - 使用 `pdfplumber` 提取文本型 PDF 内容 - 扫描版 PDF 需配合 OCR 工具 ## 填写表单 - 读取 PDF 表单字段 - 按输入数据填充并生成新文件
Exemple minimal requis :
--- name: skill-name description: 说明该 Skill 的功能以及适用场景 ---
Exemple avec champs optionnels :
--- name: pdf-processing description: 从 PDF 中提取文本和表格，填写表单，并合并文档 license: Apache-2.0 metadata: author: example-org version: "1.0" ---
Descriptions des champs :
| Champ | Requis | Description |
|---|---|---|
| name | Oui | Nom de la compétence, jusqu'à 64 caractères ; ne peut contenir que des lettres minuscules, des chiffres et des traits d'union-, et ne doit pas-commencer ou se terminer par un trait d'union |
| description | Oui | Description des fonctionnalités et des scénarios d'utilisation, jusqu'à 1024 caractères, ne peut pas être vide |
| license | non | Nom de la licence ou pointeur vers le fichier de licence fourni avec la compétence |
| compatibilité | non | Description de l'environnement et des dépendances (produits, paquets système, autorisations réseau, etc.), jusqu'à 500 caractères |
| metadata | non | Paires clé-valeur personnalisées pour étendre les métadonnées (comme auteur, version) |
| allowed-tools | non | Liste des outils autorisés (séparés par des espaces, fonctionnalité expérimentale) |
Structure du répertoire des fichiers de compétence
Une compétence est un dossier qui contient au moins un fichier SKILL.md, et peut également contenir d'autres répertoires et fichiers selon les besoins.
Pour éviter l’encombrement du contexte :
- Règles principales →
SKILL.md - Documents détaillés → fichiers séparés
- Logique pratique → exécution de script (non chargée)
Structure recommandée :
my-skill/
├── SKILL.md # 必需：元数据 + 指令
├── scripts/ # 可选：可执行代码
└── helper.py
├── references/ # 可选：参考文档
├── assets/ # 可选：模板、资源
└── ... # 其他文件或目录
La fonction de chaque répertoire est la suivante :
- SKILL.md: Fichier requis, contenant les métadonnées de la compétence et les instructions d'exécution
- scripts/: Répertoire facultatif, contenant le code exécutable que l'agent peut exécuter
- references/: Répertoire facultatif, contenant des documents de référence détaillés
- assets/: Répertoire facultatif, contenant des ressources statiques telles que des modèles, des images, etc.
Autres extensions