Système de compétences Pi Agent Skills
Les compétences sont des paquets de capacités autonomes qui permettent à l'IA de charger à la demande des instructions de flux de travail et des scripts d'outils pour des domaines spécialisés.
Pi Agent implémentela norme Agent Skills。
Qu'est-ce qu'une Skill
Une compétence est un répertoire qui contientSKILL.mdun fichier SKILL.md.
SKILL.md contient le nom de la compétence, sa description et des instructions d'utilisation détaillées. L'IA le lira et l'exécutera automatiquement en cas de besoin.
Vous pouvez considérer une compétence comme le « manuel de formation professionnelle » d'une IA — elle n'occupe normalement pas d'espace de contexte et n'est chargée qu'en cas de besoin.
Fonctionnement des compétences
L'ensemble du processus de chargement se compose de quatre étapes, l'idée centrale étant « de regarder d'abord le répertoire, puis de lire le contenu complet ».
- Lorsque Pi Agent démarre, il analyse tous les emplacements de compétences et en extrait les noms et descriptions.
- Les descriptions de toutes les compétences disponibles sont intégrées dans le prompt système au format XML.
- Lorsqu'une tâche utilisateur correspond à la description d'une compétence, l'IA charge automatiquement l'intégralité de SKILL.md à l'aide de l'outil read.
- L'IA travaille selon les instructions de SKILL.md, en utilisant des chemins relatifs pour référencer les scripts et ressources du répertoire de la compétence.
Notez que le modèle peut ne pas le lire de manière proactive. Si nécessaire, demandez-le explicitement dans le prompt, ou utilisez/skill:namepour forcer le chargement.
Cette conception est appelée « Progressive Disclosure » — seules les descriptions sont toujours dans le contexte, tandis que les instructions complètes sont chargées à la demande.
Structure du répertoire de compétences
Seul SKILL.md est requis ; les autres répertoires sont créés selon les besoins.
my-skill/
├── SKILL.md # 必需:Frontmatter + 指令
├── scripts/ # 辅助脚本
│ └── process.sh
├── references/ # 详细参考文档(按需加载)
│ └── api-reference.md
└── assets/
└── template.json
Format de SKILL.md
SKILL.md utilise YAML Frontmatter pour définir les métadonnées, suivi du corps d'instructions au format Markdown :
Exemple
name: my-skill
description: Ce que cette compétence fait et quand l'utiliser. La description doit être spécifique et claire.
---
# Ma compétence
## Installation
Exécuter avant la première utilisation :
```bash
cd ~/projects/brave-search-skill && npm install
```
## Utilisation
```bash
bash scripts/process.sh <input>
```
## Références
Voir [Guide de référence](references/api-reference.md) pour plus de détails.
Lorsque vous référencez des fichiers dans le répertoire du skill, utilisezdes chemins relatifs。
Champs de frontmatter
Seuls name et description sont obligatoires ; ajoutez d'autres champs selon les besoins.
| Champ | Requis | Description |
|---|---|---|
| name | Oui | Jusqu'à 64 caractères, uniquement des lettres minuscules/chiffres/tirets. Pi Agent n'exige pas que le name corresponde au répertoire parent. |
| description | Oui | Jusqu'à 1024 caractères. Décrit la fonction du skill et quand l'utiliser. C'est la base pour que l'IA décide si elle doit charger le skill. |
| license | non | Nom de la licence |
| compatibilité | non | Jusqu'à 500 caractères, exigences d'environnement. |
| metadata | non | Paires clé-valeur personnalisées |
| allowed-tools | non | Liste d'outils préapprouvés (expérimental) |
| disable-model-invocation | non | Lorsqu'il est défini sur true, le Skill est masqué du prompt système et ne peut être appelé manuellement que via /skill:name. |
description est la base essentielle pour que l'IA décide de charger ou non votre Skill, alors veillez à l'écrire de manière précise et claire.
Une description vague peut entraîner le déclenchement de la compétence dans des scénarios inappropriés ou son ignorance dans les situations où elle serait nécessaire.
Emplacements de chargement des compétences
Pi Agent analyse les compétences aux niveaux global et projet, avec des règles de découverte légèrement différentes selon les emplacements.
| Emplacement | Portée | Règles de chargement |
|---|---|---|
| ~/.pi/agent/skills/ | Global | Les fichiers .md à la racine et les répertoires contenant SKILL.md sont découverts récursivement. |
| ~/.agents/skills/ | Global | Seuls les répertoires contenant SKILL.md sont découverts récursivement ; les fichiers .md à la racine sont ignorés. |
| .pi/skills/ | Projet | Les fichiers .md à la racine et les répertoires contenant SKILL.md sont découverts récursivement. |
| .agents/skills/ | Projet | Seuls les répertoires contenant SKILL.md sont découverts récursivement. |
| Paquets Pi | Global ou Projet | Le répertoire skills/ ou l'entrée pi.skills dans package.json. |
| CLI | Pour cette exécution en cours | --skill path charge explicitement, peut être passé plusieurs fois. |
Un point supplémentaire : dans ~/.agents/skills/ et .agents/skills/ du projet, les fichiers .md imbriqués avec un Frontmatter valide dans des sous-répertoires groupés sont également reconnus, tandis que les fichiers .md de niveau supérieur sans Frontmatter sont ignorés.
Arguments CLI--no-skillsLa découverte automatique des Skills peut être désactivée, mais les--skill paths fournis explicitementseront quand même chargés.
Validation et conflits de nommage
Pi Agent valide les Skills conformément au standard Agent Skills. La plupart des problèmes ne produisent que des avertissements, et le Skill est quand même chargé.
Les fichiers SKILL.md sans description ne sont pas chargés ; les fichiers malformés ne produisent également qu'un avertissement et ne sont pas chargés.
Lorsque des Skills du même nom proviennent d'emplacements différents, un avertissement est émis et le premier découvert est conservé.
Commandes de Skill
Chaque Skill est automatiquement enregistré comme une/skill:namecommande :
/skill:brave-search /skill:pdf-tools extract
Les arguments après la commande seront ajoutés au contenu du Skill sous la forme deUtilisateur : argumentset ajoutés au contenu du Skill.
En utilisant /skill:pdf-tools extract report.pdf comme exemple, le contenu étendu est à peu près le suivant :
/skill:pdf-tools extract report.pdf User: extract report.pdf
Après avoir reçu ce contenu, l'IA suivra les instructions dans SKILL.md pour trouver et exécuter les scripts dans le répertoire scripts/.
L'enregistrement des commandes Skill peut être désactivé via les paramètres :
Exemple
{
"enableSkillCommands": false
}
Vous pouvez également utiliser le paramètredisable-model-invocationpour rendre certains Skills uniquement invocables manuellement, et ne pas apparaître automatiquement dans le prompt système.
Importation de Skills depuis d'autres outils
Pi Agent peut charger des Skills depuis Claude Code ou OpenAI Codex :
Les deux configurations suivantes sont écrites respectivement dans le settings.json global et celui du projet ; ajustez les chemins en fonction de vos répertoires réels.
Exemple
{
"skills": [
"~/.claude/skills",
"~/.codex/skills"
]
}
Pour les Skills Claude Code au niveau du projet :
Exemple
{
"skills": ["../.claude/skills"]
}
Les instructions dans les Skills peuvent exiger que l'IA effectue des opérations arbitraires, y compris l'exécution de fichiers exécutables.
Avant d'utiliser des Skills de tiers, il est recommandé d'examiner leur contenu.
Exemple complet de Skill
Ce qui suit est un exemple complet d'un Skill de recherche web :
Exemple
name: brave-search
description: Effectuer des recherches web et extraire du contenu via l'API Brave Search. Adapté pour rechercher des documents, des requêtes factuelles, ou toute récupération de contenu web.
---
# Brave Search
## Installation
Installez les dépendances avant la première utilisation :
```bash
cd ~/projects/brave-search-skill && npm install
```
## Recherche
```bash
# Exécuter avec node, aucune permission d'exécution nécessaire
node scripts/search.js "requête de recherche" --content # inclut le contenu de la page
node scripts/search.js "mot-clé de requête" --content # inclut le contenu de la page
# Si la permission d'exécution est déjà accordée (chmod +x scripts/search.js), vous pouvez aussi l'exécuter directement.
./scripts/search.js "mot-clé de recherche"
```
## Extraire le contenu de la page
```bash
node scripts/content.js https://example.com
```
Dépôts de compétences recommandés
Ces deux dépôts fournissent un grand nombre de compétences directement utilisables, mais il est toujours recommandé de lire le contenu avant l'installation.
| Dépôt | Direction du contenu | Scénarios applicables |
|---|---|---|
| Compétences Anthropic | Traitement de documents (docx, pdf, pptx, xlsx), développement web | Traitement par lots des documents bureautiques quotidiens, création de pages front-end |
| Compétences Pi | Recherche web, automatisation du navigateur, API Google, transcription audio | Tâches nécessitant une récupération de données en ligne, des opérations automatisées et une transcription multimédia |