Pi Agent Skills Skill-System
Skills sind eigenständige Fähigkeitspakete, mit denen die KI bei Bedarf Workflow-Anweisungen und Tool-Skripte für spezialisierte Domänen laden kann.
Pi Agent implementiertden Agent Skills-Standard。
Was ist ein Skill
Ein Skill ist ein Verzeichnis, dasSKILL.md, eine SKILL.md-Datei, enthält.
SKILL.md enthält den Namen, die Beschreibung und detaillierte Nutzungsanweisungen des Skills. Die KI wird es bei Bedarf automatisch lesen und ausführen.
Man kann sich einen Skill als das "professionelle Trainingshandbuch" einer KI vorstellen — normalerweise belegt er keinen Kontextbereich und wird nur bei Bedarf geladen.
So funktionieren Skills
Der gesamte Ladevorgang besteht aus vier Schritten, wobei die Kernidee lautet: "Zuerst ins Verzeichnis schauen, dann den vollständigen Inhalt lesen."
- Wenn Pi Agent startet, scannt er alle Skill-Speicherorte und extrahiert Namen und Beschreibungen.
- Beschreibungen aller verfügbaren Skills sind im XML-Format im System-Prompt eingebettet.
- Wenn die Aufgabe eines Benutzers mit der Beschreibung eines Skills übereinstimmt, lädt die KI automatisch die vollständige SKILL.md mit dem read-Tool.
- Die KI arbeitet gemäß den Anweisungen in SKILL.md und verwendet relative Pfade, um auf Skripte und Ressourcen im Skill-Verzeichnis zu verweisen.
Beachten Sie, dass das Modell es möglicherweise nicht proaktiv liest. Falls nötig, fordern Sie es explizit im Prompt an oder verwenden Sie/skill:name, um das Laden zu erzwingen.
Dieses Design wird "Progressive Disclosure" genannt — nur Beschreibungen sind immer im Kontext, während vollständige Anweisungen bei Bedarf geladen werden.
Skill-Verzeichnisstruktur
Nur SKILL.md ist erforderlich; die übrigen Verzeichnisse werden nach Bedarf erstellt.
my-skill/
├── SKILL.md # 必需:Frontmatter + 指令
├── scripts/ # 辅助脚本
│ └── process.sh
├── references/ # 详细参考文档(按需加载)
│ └── api-reference.md
└── assets/
└── template.json
SKILL.md-Format
SKILL.md verwendet YAML-Frontmatter, um Metadaten zu definieren, gefolgt vom Anweisungstext im Markdown-Format:
Beispiel
name: my-skill
description: Was dieser Skill bewirkt und wann er verwendet werden sollte. Die Beschreibung sollte spezifisch und klar sein.
---
# Mein Skill
## Installation
Vor der ersten Verwendung ausführen:
```bash
cd ~/projects/brave-search-skill && npm install
```
## Verwendung
```bash
bash scripts/process.sh <input>
```
## Referenzen
Siehe [Referenzhandbuch](references/api-reference.md) für Details.
Wenn Sie auf Dateien im Skill-Verzeichnis verweisen, verwenden Sierelative Pfade。
Frontmatter-Felder
Nur name und description sind erforderlich; fügen Sie bei Bedarf weitere Felder hinzu.
| Feld | Erforderlich | Beschreibung |
|---|---|---|
| name | Ja | Bis zu 64 Zeichen, nur Kleinbuchstaben/Ziffern/Bindestriche. Pi Agent erfordert nicht, dass der Name mit dem übergeordneten Verzeichnis übereinstimmt. |
| description | Ja | Bis zu 1024 Zeichen. Beschreibt die Funktion des Skills und wann er verwendet werden sollte. Dies ist die Grundlage dafür, dass die KI entscheidet, ob der Skill geladen wird. |
| license | nein | Lizenzname |
| Kompatibilität | nein | Bis zu 500 Zeichen, Umgebungsanforderungen. |
| metadata | nein | Benutzerdefinierte Schlüssel-Wert-Paare |
| allowed-tools | nein | Vorab genehmigte Tool-Liste (experimentell) |
| disable-model-invocation | nein | Wenn auf true gesetzt, ist der Skill im System-Prompt ausgeblendet und kann nur manuell über /skill:name aufgerufen werden. |
description ist die wichtigste Grundlage dafür, dass die KI entscheidet, ob Ihr Skill geladen wird; achten Sie darauf, sie präzise und klar zu formulieren.
Eine vage Beschreibung kann dazu führen, dass der Skill in ungeeigneten Szenarien ausgelöst oder in benötigten Fällen ignoriert wird.
Skill-Ladeorte
Der Pi Agent scannt Skills sowohl auf globaler als auch auf Projektebene, wobei für verschiedene Orte leicht unterschiedliche Erkennungsregeln gelten.
| Ort | Geltungsbereich | Laderegeln |
|---|---|---|
| ~/.pi/agent/skills/ | Global | Auf Root-Ebene liegende .md-Dateien und Verzeichnisse, die SKILL.md enthalten, werden rekursiv erkannt. |
| ~/.agents/skills/ | Global | Nur Verzeichnisse, die SKILL.md enthalten, werden rekursiv erkannt; .md-Dateien auf Root-Ebene werden ignoriert. |
| .pi/skills/ | Projekt | Auf Root-Ebene liegende .md-Dateien und Verzeichnisse, die SKILL.md enthalten, werden rekursiv erkannt. |
| .agents/skills/ | Projekt | Nur Verzeichnisse, die SKILL.md enthalten, werden rekursiv erkannt. |
| Pi-Pakete | Global oder Projekt | Das Verzeichnis skills/ oder der Eintrag pi.skills in package.json. |
| CLI | Für diesen aktuellen Lauf | Der --skill-Pfad wird explizit geladen und kann mehrfach übergeben werden. |
Noch ein Punkt: In ~/.agents/skills/ und dem .agents/skills/ des Projekts werden auch verschachtelte .md-Dateien mit gültigem Frontmatter in gruppierten Unterverzeichnissen erkannt, während .md-Dateien auf oberster Ebene ohne Frontmatter ignoriert werden.
CLI-Argumente--no-skillsDie automatische Skill-Erkennung kann deaktiviert werden, aber explizit angegebene--skill-Pfadewerden trotzdem geladen.
Validierung und Namenskonflikte
Pi Agent validiert Skills gemäß dem Agent Skills-Standard. Die meisten Probleme erzeugen nur Warnungen, und der Skill wird trotzdem geladen.
SKILL.md-Dateien, denen eine Beschreibung fehlt, werden nicht geladen; fehlerhafte Dateien erzeugen ebenfalls nur eine Warnung und werden nicht geladen.
Wenn Skills mit demselben Namen von verschiedenen Orten stammen, wird eine Warnung ausgegeben und der zuerst entdeckte wird beibehalten.
Skill-Befehle
Jeder Skill wird automatisch als ein/skill:name-Befehl registriert:
/skill:brave-search /skill:pdf-tools extract
Argumente nach dem Befehl werden in der FormUser: argumentsan den Skill-Inhalt angehängt und an den Skill-Inhalt angehängt.
Am Beispiel von /skill:pdf-tools extract report.pdf sieht der erweiterte Inhalt ungefähr wie folgt aus:
/skill:pdf-tools extract report.pdf User: extract report.pdf
Nach Erhalt dieses Inhalts wird die KI den Anweisungen in SKILL.md folgen, um Skripte im Verzeichnis scripts/ zu finden und auszuführen.
Die Registrierung von Skill-Befehlen kann über Einstellungen deaktiviert werden:
Beispiel
{
"enableSkillCommands": false
}
Sie können auch die Einstellungdisable-model-invocationverwenden, um bestimmte Skills nur manuell aufrufbar zu machen und sie nicht im System-Prompt erscheinen zu lassen.
Importieren von Skills aus anderen Tools
Pi Agent kann Skills aus Claude Code oder OpenAI Codex laden:
Die folgenden beiden Konfigurationen werden jeweils in die globalen und globalen Einstellungen geschrieben; passen Sie die Pfade an Ihre tatsächlichen Verzeichnisse an.
Beispiel
{
"skills": [
"~/.claude/skills",
"~/.codex/skills"
]
}
Für Claude Code Skills auf Projektebene:
Beispiel
{
"skills": ["../.claude/skills"]
}
Anweisungen in Skills können verlangen, dass die KI beliebige Operationen ausführt, einschließlich der Ausführung ausführbarer Dateien.
Bevor Sie Skills von Drittanbietern verwenden, wird empfohlen, deren Inhalte zu prüfen.
Vollständiges Skill-Beispiel
Das Folgende ist ein vollständiges Beispiel für einen Web-Such-Skill:
Beispiel
name: brave-search
description: Führen Sie Web-Suchen und Inhaltsextraktion über die Brave Search API durch. Geeignet für die Suche nach Dokumenten, Faktenabfragen oder den Abruf beliebiger Webinhalte.
---
# Brave Search
## Installation
Abhängigkeiten vor der ersten Verwendung installieren:
```bash
cd ~/projects/brave-search-skill && npm install
```
## Suche
```bash
# Mit node ausführen, keine Ausführungsberechtigung erforderlich
node scripts/search.js "Suchanfrage" --content # enthält Seiteninhalt
node scripts/search.js "Abfrage-Schlüsselwort" --content # Seiteninhalt einbeziehen
# Wenn die Ausführungsberechtigung bereits erteilt wurde (chmod +x scripts/search.js), können Sie es auch direkt ausführen.
./scripts/search.js "Suchbegriff"
```
## Seiteninhalt extrahieren
```bash
node scripts/content.js https://example.com
```
Empfohlene Skill-Repositories
Diese beiden Repositories bieten eine große Anzahl sofort nutzbarer Skills, es wird jedoch weiterhin empfohlen, den Inhalt vor der Installation durchzulesen.
| Repository | Inhaltliche Ausrichtung | Anwendbare Szenarien |
|---|---|---|
| Anthropic Skills | Dokumentenverarbeitung (docx, pdf, pptx, xlsx), Webentwicklung | Stapelverarbeitung alltäglicher Office-Dokumente, Frontend-Seitenerstellung |
| Pi Skills | Websuche, Browser-Automatisierung, Google API, Audiotranskription | Aufgaben, die Online-Datenabruf, automatisierte Vorgänge und Multimedia-Transkription erfordern |