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 :

TypeDescriptionScénarios applicables
Analyse de documents PDFExtraire le contenu PDF et générer des résumésTraitement de documents, extraction d'informations
Extraction webObtenir automatiquement des données webCollecte de données, surveillance des informations
Optimisation SQLAnalyser et optimiser les requêtes SQLOptimisation des performances de base de données
Statistiques de donnéesCalcul de données et traitement statistiqueAnalyse de données, génération de rapports
Reconnaissance d’imagesReconnaître le contenu dans les imagesOCR, 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 :

Skill 工作流程

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 :

SectionDescriptionObjectif
DescriptionDescription fonctionnelle du SkillUtilisé pour la correspondance d'Agent
Quand l'utiliserDéfinir clairement les scénarios applicablesÉviter les faux déclenchements
Quand NE PAS l'utiliserDéfinir clairement les scénarios inapplicablesÉviter les conflits avec d'autres compétences
EntréeDéfinir le format d'entréeStandardiser la méthode d'invocation
InstructionsÉtapes d'exécutionGuider l'exécution des tâches
SortieDescription du format de sortieGarantir la cohérence des résultats

Voici un exemple standardisé de SKILL.md :

Exemple

# Compétence d'analyse PDF

## 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

# Compétence PDF

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

ChampObjectifImportance
nameNom de la compétenceRequis
descriptionDescription fonctionnelle ; l’Agent s’appuie sur elle pour la correspondanceLe plus important
versionNuméro de versionRecommandé
tagsTags, pour une récupération facileRecommandé
categoryCatégorieOptional
authorAuteurOptional
permissionsAutorisations requisesOptional

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

Entrée :

Veuillez m'aider à analyser ce PDF

Sortie :

# Résumé du document

## Contenu principal

1. ...
2. ...
3. ...

Objectif des exemples

ObjectifDescription
Fournir des exemples few-shotAider le modèle à comprendre le comportement attendu grâce à des exemples
Standardiser le format de sortieClarifier la structure et le style de sortie à l'aide d'exemples
Améliorer la stabilité de la sortieRé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

# Chemin du fichier : scripts/extract.py
# 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 ressourceDescriptionExemple
Modèle de promptModèles de prompts réutilisablesprompt.md
Fichier de configurationParamètres et réglagesconfig.yaml
Modèles de texteModèles d'e-mails et de rapportstemplate.txt
Ressources d'imagesIcônes, diagrammeslogo.png
Modèles SQLModèles de requêtes prédéfinisquery.sql

Exemple de fichier de configuration

Exemple

# Chemin du fichier : resources/config.yaml
# 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

Test :

Entrée :

Aidez-moi à analyser le PDF

Attendu :

Produire un résumé
Inclure les points clés

Objectif des tests

ObjectifDescription
Vérifier l'efficacitéS'assurer que la sortie du Skill répond aux attentes
Tests de régressionAprès modifications, vérifier que l'ancienne fonctionnalité n'est pas affectée
Évaluation automatiséeTests par lots avec des flux de travail automatisés
Tests A/BComparer 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

# Installation

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èmeManifestation spécifique
Non maintenableTout le contenu entassé dans un seul fichier, ce qui rend les modifications difficiles
Non testablePas de cas de test, donc on ne sait pas si cela fonctionne après des modifications
Non réutilisableChaque Skill doit être écrit à partir de zéro
Pas de gestion de versionsDifficile de suivre l'historique des modifications
Aucune collaboration à plusieursPlusieurs personnes modifiant un même fichier provoquent facilement des conflits

Avantages de l'approche basée sur les répertoires

AvantageMéthode d'implémentation
MaintenableChaque fichier a des responsabilités claires, permettant de localiser rapidement les modifications
RéutilisableLes scripts et configurations peuvent être partagés entre les Skills
TestableRépertoire de tests indépendant, prend en charge la vérification automatisée
ExtensibleL'ajout de nouvelles fonctionnalités ne nécessite que l'ajout de fichiers
PubliableLe 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
    ↓
定义使用方式

Un prompt ne résout un problème qu'une seule fois, tandis qu'un Skill transforme une capacité en actif.

Autres extensions