zhangliang0115/ai-plugin

Erstellung einer agentenübergreifenden SKILL.md-Fähigkeit

Eine Fähigkeit (Skill) ist ein Ordner mit einer SKILL.md-Datei darin. Die Datei beginnt mit einem YAML-Frontmatter-Block (Name + Beschreibung), gefolgt von Markdown-Anweisungen, die der Agent bei Bedarf lädt. Da Claude Code, DeepSeek Harness (dsh), Codex CLI, Gemini CLI, Copilot und Cursor alle dieses gleiche Format lesen, bedient eine gut verfasste Fähigkeit jeden Agenten.

Aufbau

my-skill/
├── SKILL.md            # erforderlich: Frontmatter + Anweisungen
├── references/         # optional: ausführliche Dokumente, die das Modell bei Bedarf liest
└── scripts/            # optional: Hilfsskripte, die die Fähigkeit ausführen kann

---
name: my-skill
description: >-
  Ein oder zwei Sätze: WAS es tut UND wann man es verwendet. Dies ist der Auslöser,
  den der Agent mit der Anfrage des Benutzers abgleicht – schreiben Sie es wie eine Routing-Regel.
---

# My Skill

Schritt-für-Schritt-Anleitung. Gehen Sie von einem kompetenten Ingenieur aus; seien Sie konkret, nicht vage.

Regeln, die über die Funktionsfähigkeit einer Fähigkeit entscheiden

1. name muss im Kebab-Case sein – Kleinbuchstaben, Ziffern, Bindestriche; maximal 64 Zeichen. Agenten lehnen andere Namen ab oder verstümmeln sie. aipx normalisiert für Sie, aber liefern Sie es korrekt aus.
2. description ist der Auslöser, keine Dokumentation. Schlecht: „Hilfsprogramme für die Arbeit mit Dingen.“ Gut: „Fasse YouTube-/Bilibili-Videos und Podcasts von einer URL zusammen. Verwende, wenn der Benutzer einen Video- oder Audiolink einfügt.“
3. Halten Sie SKILL.md unter ~500 Zeilen. Platzieren Sie Tiefe in references/*.md und verlinken Sie dorthin („siehe references/schema.md“). Agenten laden den Hauptteil nur, wenn die Fähigkeit ausgelöst wird; große Hauptteile verschwenden Kontext und verwässern das Verhalten.
4. Keine verschachtelten Fähigkeiten. Die Erkennung scannt nur die direkten Kinder eines Fähigkeitsverzeichnisses – skills/a/SKILL.md wird gefunden, skills/a/b/SKILL.md nicht.
5. Relative Links müssen relativ bleiben. Wenn SKILL.md auf scripts/x.py verweist, muss der gesamte Ordner zusammenbleiben – verlinken Sie niemals außerhalb des Fähigkeitsverzeichnisses.

Wo Fähigkeiten leben (Benutzerverzeichnisse)

Verzeichnis	Gelesen von
~/.agents/skills/<name>/SKILL.md	DeepSeek Harness (dsh), Codex CLI
~/.claude/skills/<name>/SKILL.md	Claude Code
~/.gemini/skills/<name>/SKILL.md	Gemini CLI
~/.copilot/skills/<name>/SKILL.md	GitHub Copilot CLI

Es gibt auch projektbezogene Entsprechungen (z. B. .claude/skills/, .agents/skills/ im Repository). Kopieren Sie nicht von Hand – verwenden Sie aipx sync, um eine Kopie in jedes Agentenverzeichnis zu verlinken.

Vor der Veröffentlichung testen

# Wird es geparst und erkannt?
aipx install ./my-skill --dry-run
aipx install ./my-skill
aipx list

Öffnen Sie dann Ihren Agenten und bestätigen Sie, dass die Fähigkeit erscheint (Claude Code: sie wird in der Fähigkeitsliste angezeigt; dsh: Befehlspalette / → Gruppe „Fähigkeiten“).

Checkliste für die Veröffentlichung

• Repository enthält den Fähigkeitsordner unter einem stabilen Pfad, z. B. skills/my-skill/
• description gibt Auslösebedingungen an, nicht nur Funktionen
• Funktioniert aus einer sauberen Installation (aipx install owner/repo#path:/skills/my-skill)
• GitHub-Themen hinzufügen, damit die Erkennung funktioniert: agent-skills, claude-code, dsh-plugin (falls es auch ein dsh-Bundle enthält), deepseek (falls DS-bezogen)
• Optional: Dual-Target-Paketierung – siehe die Fähigkeiten dsh-plugin-dev und claude-plugin-dev