Structure du répertoire des compétences
Comprendre la structure des répertoires et le mécanisme de fonctionnement d'un Skill est la base pour construire des capacités d'Agent IA maintenables et réutilisables.
Cet article décompose la structure des répertoires, le rôle de chaque fichier et le flux de travail complet d'un Skill standard à partir de zéro.
Qu'est-ce qu'une Skill
Un Skill est une unité de capacité indépendante utilisée pour accomplir un type spécifique de tâche.
Si l'Agent est comparé à un système d'exploitation, un Skill est comme une application ; si l'Agent est comparé à un chef de projet, un Skill est une capacité professionnelle qui peut être invoquée.
Types courants de Skills
Voici quelques scénarios d'application typiques de Skill :
| Type | Description | Scénarios applicables |
|---|---|---|
| Analyse de documents PDF | Extraire le contenu PDF et générer des résumés | Traitement de documents, extraction d'informations |
| Extraction web | Obtenir automatiquement des données web | Collecte de données, surveillance des informations |
| Optimisation SQL | Analyser et optimiser les requêtes SQL | Optimisation des performances de base de données |
| Statistiques de données | Calcul de données et traitement statistique | Analyse de données, génération de rapports |
| Reconnaissance d’images | Reconnaître le contenu dans les images | OCR, classification d'images |
Relation entre Compétence et Agent
Une Compétence elle-même n'est pas responsable de décider quand elle doit être utilisée ; c'est l'Agent qui prend réellement la décision.
Le flux de travail complet est le suivant :
Point clé : L'Agent ne charge pas le contenu complet de toutes les Compétences en une seule fois. Il lit d'abord les informations de description de chaque Compétence, et ce n'est qu'après avoir fait correspondre la Compétence cible qu'il charge le contenu complet. La raison en est : s'il y a des centaines de Compétences, les charger toutes à chaque fois serait extrêmement coûteux en Tokens.
Structure de répertoire standard d'une Compétence
Un Skill complet n'est pas un seul fichier, mais un répertoire contenant plusieurs fichiers.
Voici la structure complète de répertoire d'un Skill standard :
my-skill/ │ ├── SKILL.md ← 核心执行文件 ├── metadata.json ← 元信息 ├── examples/ ← 示例目录 │ ├── example1.md │ └── example2.md │ ├── scripts/ ← 可执行脚本 │ ├── main.py │ └── utils.py │ ├── resources/ ← 资源目录 │ ├── prompt.md │ └── config.yaml │ ├── tests/ ← 测试目录 │ ├── test_cases.md │ └── eval.yaml │ ├── README.md ← 使用说明 │ └── CHANGELOG.md ← 变更日志
Ensuite, nous allons décomposer l'objectif de chaque fichier et répertoire un par un.

SKILL.md : fichier d'exécution principal
C'est le fichier le plus important d'un Skill, définissant toute la logique d'exécution du Skill.
Il contient les informations clés suivantes :
| Section | Description | Objectif |
|---|---|---|
| Description | Description fonctionnelle du Skill | Utilisé pour la correspondance d'Agent |
| Quand l'utiliser | Définir clairement les scénarios applicables | Éviter les faux déclenchements |
| Quand NE PAS l'utiliser | Définir clairement les scénarios inapplicables | Éviter les conflits avec d'autres compétences |
| Entrée | Définir le format d'entrée | Standardiser la méthode d'invocation |
| Instructions | Étapes d'exécution | Guider l'exécution des tâches |
| Sortie | Description du format de sortie | Garantir la cohérence des résultats |
Voici un exemple standardisé de SKILL.md :
Exemple
## Description
Sert à analyser le contenu PDF et à générer des résumés.
## Quand l'utiliser
Adapté à :
- Lecture de PDF
- Extraction de résumé
- Analyse de contenu
## Quand NE PAS l'utiliser
Ne convient pas pour :
- Édition d'image
- Traitement vidéo
## Entrée
Fichier PDF
## Instructions
1. Extraire le texte
2. Identifier la structure du chapitre
3. Résumer le contenu principal
4. Afficher les points clés
## Sortie
Résumé au format Markdown
Styles d'écriture incorrects courants
De nombreux débutants écrivent un SKILL.md trop simplifié, par exemple :
Exemple d'écriture déconseillée
Lire le PDF
Résumer le contenu
Renvoyer le résultat
Le problème avec ce style d’écriture est : il ne sait pas quand l’utiliser, ne sait pas quand ne pas l’utiliser, le format de sortie n’est pas clair et il est facile d’entrer en conflit avec d’autres compétences.
Un SKILL.md qualifié devrait permettre à l’Agent de juger au premier coup d’œil si cette compétence convient à la tâche actuelle.
metadata.json : métadonnées de compétence
Ce fichier fournit des données structurées lisibles par machine pour aider l’Agent à filtrer rapidement les compétences.
Exemple
"name": "pdf-analyzer",
"version": "1.0.0",
"description": "Analyser un PDF et générer un résumé",
"tags": ["pdf", "summary"],
"category": "document"
}
Descriptions des champs courants
| Champ | Objectif | Importance |
|---|---|---|
| name | Nom de la compétence | Requis |
| description | Description fonctionnelle ; l’Agent s’appuie sur elle pour la correspondance | Le plus important |
| version | Numéro de version | Recommandé |
| tags | Tags, pour une récupération facile | Recommandé |
| category | Catégorie | Optional |
| author | Auteur | Optional |
| permissions | Autorisations requises | Optional |
Parmi eux,descriptionLe champ est le plus important car l'Agent s'appuie généralement dessus pour la correspondance.
Le processus de correspondance est approximativement le suivant : après que l'utilisateur a fait une requête, l'Agent analyse les descriptions de toutes les Skills, et après avoir trouvé une description correspondante, charge le contenu complet de la Skill et l'exécute.
examples : Répertoire d'exemples
De nombreux développeurs ignorent cette partie, mais elle est en fait très importante.
Structure du répertoire
examples/ ├── example1.md ├── example2.md
Contenu du fichier d'exemple
Exemple
Veuillez m'aider à analyser ce PDF
Sortie :
# Résumé du document
## Contenu principal
1. ...
2. ...
3. ...
Objectif des exemples
| Objectif | Description |
|---|---|
| Fournir des exemples few-shot | Aider le modèle à comprendre le comportement attendu grâce à des exemples |
| Standardiser le format de sortie | Clarifier la structure et le style de sortie à l'aide d'exemples |
| Améliorer la stabilité de la sortie | Réduire le comportement aléatoire et rendre les résultats plus prévisibles |
Empiriquement, de bons exemples sont souvent plus efficaces que d'ajouter davantage de prompts.
scripts : Scripts exécutables
Une Skill n'est pas seulement un prompt ; il est parfois nécessaire d'exécuter réellement du code pour accomplir un vrai travail.
Les scénarios courants nécessitant des scripts incluent : la lecture de PDF, l'exécution d'OCR, l'appel à des bases de données, le traitement de données, la génération de graphiques, etc.
Structure du répertoire
scripts/ ├── main.py └── utils.py
Exemple de script Python
Exemple
# Fonction : Extraire le contenu textuel d'un fichier PDF
from pypdf import PdfReader
# Ouvrir le fichier PDF
reader = PdfReader("demo.pdf")
# Stocker le texte extrait
text = ""
# Parcourir chaque page et extraire le texte
for page in reader.pages:
text += page.extract_text()
# Afficher tout le contenu textuel
print(text)
Le workflow du Skill est : lire le fichier → exécuter le script → obtenir le résultat, puis transmettre le résultat au grand modèle pour traitement.
resources: Répertoire de ressources
Utilisé pour stocker du contenu auxiliaire, en séparant la configuration du code.
Structure du répertoire
resources/ ├── prompt.md ├── config.yaml
Types de ressources possibles
| Type de ressource | Description | Exemple |
|---|---|---|
| Modèle de prompt | Modèles de prompts réutilisables | prompt.md |
| Fichier de configuration | Paramètres et réglages | config.yaml |
| Modèles de texte | Modèles d'e-mails et de rapports | template.txt |
| Ressources d'images | Icônes, diagrammes | logo.png |
| Modèles SQL | Modèles de requêtes prédéfinis | query.sql |
Exemple de fichier de configuration
Exemple
# Configuration liée au résumé
max_length: 1000 # Longueur maximale du résumé (caractères)
language: zh # Langue de sortie : zh=chinois, en=anglais
Placer la configuration dans un fichier séparé signifie que vous n'avez pas besoin de modifier le code lorsque vous modifiez les paramètres par la suite.
tests : Répertoire de tests
Les projets matures incluent généralement des tests pour vérifier l'efficacité et la stabilité du Skill.
Structure du répertoire
tests/ ├── test_cases.md └── eval.yaml
Exemple de cas de test
Exemple
Entrée :
Aidez-moi à analyser le PDF
Attendu :
Produire un résumé
Inclure les points clés
Objectif des tests
| Objectif | Description |
|---|---|
| Vérifier l'efficacité | S'assurer que la sortie du Skill répond aux attentes |
| Tests de régression | Après modifications, vérifier que l'ancienne fonctionnalité n'est pas affectée |
| Évaluation automatisée | Tests par lots avec des flux de travail automatisés |
| Tests A/B | Comparer la qualité de sortie de différentes versions |
Les Skills sans tests sont sujets au problème suivant : « modifier une phrase casse soudainement une ancienne fonctionnalité ».
README : Instructions d'utilisation
README est destiné aux développeurs, expliquant comment installer et utiliser ce Skill.
Exemple
Copier dans le répertoire skills
# Utilisation
Téléverser un PDF
# Format de sortie
Markdown
Le problème central qu'il résout est le suivant : à l'avenir, même l'auteur pourrait ne plus savoir comment utiliser le Skill qu'il a écrit.
Exemple complet : Skill d'analyse de PDF
Voici un exemple complet qui rassemble tous les concepts ci-dessus.
Aperçu de la structure des répertoires
pdf-analyzer/ ├── SKILL.md ├── metadata.json ├── examples/ │ └── summary.md ├── scripts/ │ └── extract.py ├── tests/ │ └── eval.md └── README.md
Flux d'invocation complet
用户:
上传 PDF 并总结
↓
Agent:
扫描所有 Skills
↓
发现:
description: 分析 PDF 并生成摘要
↓
命中 pdf-analyzer
↓
读取 SKILL.md
↓
调用 extract.py
↓
提取 PDF 内容
↓
生成摘要
↓
返回结果
Pourquoi concevoir les Skills comme une structure de répertoires ?
Beaucoup de personnes demandent : pourquoi ne pas simplement utiliser un seul prompt.txt pour tout gérer ?
La raison est que les choses deviennent incontrôlables à mesure que l'échelle augmente.
Problèmes de l'approche à fichier unique
| Problème | Manifestation spécifique |
|---|---|
| Non maintenable | Tout le contenu entassé dans un seul fichier, ce qui rend les modifications difficiles |
| Non testable | Pas de cas de test, donc on ne sait pas si cela fonctionne après des modifications |
| Non réutilisable | Chaque Skill doit être écrit à partir de zéro |
| Pas de gestion de versions | Difficile de suivre l'historique des modifications |
| Aucune collaboration à plusieurs | Plusieurs personnes modifiant un même fichier provoquent facilement des conflits |
Avantages de l'approche basée sur les répertoires
| Avantage | Méthode d'implémentation |
|---|---|
| Maintenable | Chaque fichier a des responsabilités claires, permettant de localiser rapidement les modifications |
| Réutilisable | Les scripts et configurations peuvent être partagés entre les Skills |
| Testable | Répertoire de tests indépendant, prend en charge la vérification automatisée |
| Extensible | L'ajout de nouvelles fonctionnalités ne nécessite que l'ajout de fichiers |
| Publiable | Le répertoire peut être empaqueté et distribué |
Résumé
Un Skill n'est essentiellement pas un prompt, mais un package complet de capacités logicielles.
Relations entre les fichiers principaux
SKILL.md
↓
定义行为
metadata.json
↓
定义信息
examples/
↓
定义示例
scripts/
↓
定义能力
tests/
↓
定义质量
README
↓
定义使用方式
Autres extensionsUn prompt ne résout un problème qu'une seule fois, tandis qu'un Skill transforme une capacité en actif.