Fichier SKILL.md
SKILL.md est le fichier principal des Agent Skills.
Cette section examinera en profondeur la structure complète de SKILL.md et tous les champs disponibles.
Structure de base
Un fichier SKILL.md contient deux parties principales :
- Frontmatter YAML (zone de métadonnées)
- Contenu Markdown (zone d'instructions)
Exemple complet
name: my-skill
description: Description de la compétence, indiquant quand utiliser cette compétence
license: Apache-2.0
compatibility: Nécessite Python3.10+
metadata:
author: votre-nom
version: "1.0"
---
# Nom de la compétence
Voici les instructions détaillées pour la compétence...
## Étape 1
Étapes d'opération spécifiques...
## Étape 2
Étapes d'opération supplémentaires...
Champs de métadonnées expliqués
Les champs suivants sont tous les champs de métadonnées pris en charge par SKILL.md :
| Champ | Requis | Contraintes |
|---|---|---|
| name | Oui | Jusqu'à 64 caractères, seuls sont autorisés les lettres minuscules, les chiffres et les traits d'union ; ne peut pas commencer ou se terminer par un trait d'union |
| description | Oui | Jusqu'à 1024 caractères, décrivant la fonction et les scénarios d'utilisation de la compétence |
| license | non | Nom de la licence ou référence à un fichier de licence inclus |
| compatibilité | non | Jusqu'à 500 caractères, spécifiant les exigences d'environnement (produit cible, paquets système, accès réseau, etc.) |
| metadata | non | Paires clé-valeur arbitraires pour stocker des métadonnées supplémentaires |
| allowed-tools | non | Liste d'outils pré-approuvés séparés par des espaces (fonctionnalité expérimentale) |
Explication du champ name
Le champ name est l'identifiant de la compétence et doit respecter ces règles :
- Longueur : 1-64 caractères
- Restriction de caractères : seules les lettres minuscules Unicode (a-z) et les traits d'union (-) peuvent être utilisés
- Début/fin : ne peut commencer ni se terminer par un trait d'union
- Caractères consécutifs : ne peut pas contenir de traits d'union consécutifs (--)
- Exigence de correspondance : doit correspondre au nom du répertoire parent
Exemples valides :
name: pdf-processing name: data-analysis name: code-review
Exemples non valides :
name: PDF-Processing # 错误:不能使用大写字母 name: -pdf # 错误:不能以连字符开头 name: pdf--processing # 错误:不能包含连续连字符
Explication du champ description
Le champ description est l'un des champs les plus importants ; il indique à l'agent quand il doit activer cette compétence.
Une bonne description doit :
- Décrire ce que fait la compétence (ce qu'elle fait)
- Expliquer les scénarios d'utilisation (quand l'utiliser)
- Inclure des mots-clés pour aider l'agent à identifier les tâches pertinentes
Exemple d'une bonne description :
description: 从 PDF 文件中提取文本和表格,填写 PDF 表单,合并多个 PDF。处理 PDF 文档或用户提及 PDF、表单或文档提取时使用。
Exemple d'une mauvaise description :
description: 帮助处理 PDF 文件。 # 太笼统,代理无法判断何时使用
Astuce : Le champ description est chargé au début de la conversation. Assurez-vous qu'il contient suffisamment de mots-clés pour que l'agent puisse correctement identifier quand activer la compétence.
Le champ license expliqué
Le champ license sert à spécifier la licence de la compétence. C'est un champ facultatif.
license: Apache-2.0 # 或者引用 bundled 的许可证文件 license: Proprietary. LICENSE.txt has complete terms
Le champ compatibility expliqué
Le champ compatibility sert à spécifier les exigences d'environnement de la compétence. Il ne doit être ajouté que lorsque la compétence a des exigences d'environnement particulières.
# 指定目标产品 compatibility: Designed for Claude Code # 指定系统依赖 compatibility: Requires git, docker, jq, and access to the internet # 指定编程语言版本 compatibility: Requires Python 3.14+ and uv
Remarque : La plupart des compétences n'ont pas besoin du champ compatibility. Ne l'ajoutez que lorsque la compétence a réellement des exigences d'environnement spécifiques.
Le champ metadata expliqué
Le champ metadata peut stocker des informations arbitraires sous forme de paires clé-valeur. Les clients peuvent l'utiliser pour stocker des propriétés supplémentaires non définies dans la spécification.
metadata:
author: example-org
version: "1.0"
tags:
- pdf
- document
- extraction
Astuce : Il est recommandé d'utiliser des noms de clés relativement uniques pour éviter les conflits avec d'autres compétences.
Le champ allowed-tools expliqué
allowed-tools est un champ expérimental utilisé pour spécifier les outils pré-approuvés qu'une compétence peut utiliser.
allowed-tools: Bash(git:*) Bash(jq:*) Read
Remarque : Il s'agit d'une fonctionnalité expérimentale ; différentes implémentations d'agent peuvent avoir des niveaux de prise en charge variables.
Explication de la section Instructions
Le contenu Markdown après la zone de métadonnées constitue la partie instructions de la compétence. Il n'y a ici aucune restriction de format ; vous pouvez écrire tout ce qui est nécessaire.
Il est recommandé d'inclure les éléments suivants :
- Instructions étape par étape
- Exemples d'entrée/sortie
- Gestion des cas limites courants
# 技能名称 ## 功能说明 简要描述这个技能做什么。 ## 操作步骤 1. 第一步:执行某个操作 2. 第二步:执行另一个操作 3. 第三步:完成最终操作 ## 示例 ### 输入示例 描述输入是什么... ### 输出示例 描述输出是什么... ## 注意事项 - 注意点 1 - 注意点 2
Autres extensionsRemarque : Une fois qu'une compétence est activée, le fichier SKILL.md entier est chargé dans le contexte. Il est recommandé de conserver les instructions principales dans la limite de 500 lignes et de 5000 tokens. Déplacez les documents de référence détaillés dans des fichiers séparés.