Claude Code Skills und Plugins: ein Set für jedes Repo

Claude Code Skills sind SKILL.md-Dateien mit Anweisungen, die der Agent lädt, wenn eine Aufgabe sie braucht. Ein Plugin bündelt Skills, Agenten und Hooks zu einer Einheit, die Sie in vielen Repositories installieren. Wir liefern unsere als ein Plugin, wizrd (unser internes Claude-Code-Plugin und CLI, nicht öffentlich), aktiviert in den committeten Einstellungen eines Repositorys, und ein Validator in der CI lässt das Repository scheitern, wenn ein Skill kaputt ist.

Dahin hat uns ein Durcheinander gebracht: Kopien derselben Skills in mehreren Repositories, jede ein bisschen anders. Unten steht, wie Skills und Plugins funktionieren, wie wir ein Plugin überall laden und was dabei kaputtging.

Was sind Claude Code Skills und Plugins?

Ein Skill ist ein Ordner mit einer Datei, SKILL.md. Oben steht Frontmatter mit name und description, darunter die Anweisungen. Die Claude Code Dokumentation sagt es klar: Skill-Beschreibungen sind im Kontext, damit Claude weiß, was verfügbar ist, und der volle Inhalt eines Skills lädt erst, wenn er verwendet wird. Sie können einen Skill auch selbst als /name starten.

Ein Plugin ist ein Ordner mit Skills, Agenten, Hooks oder MCP-Servern, den Claude Code als eine Einheit installiert und lädt. Sein Manifest liegt in .claude-plugin/plugin.json. Plugin-Skills bekommen einen Namensraum, unser Review-Skill läuft also als /wizrd:review und kollidiert nie mit einem eigenen /review des Projekts.

Wohin welches Teil gehört:

Die letzte Spalte zählt am meisten. Ein Skill sagt dem Agenten, wie er eine Aufgabe gut erledigt. Er erzwingt nichts. Was gelten muss, gehört in einen Hook, eine Lint-Regel oder die CI.

Warum haben wir alle Skills in ein Plugin gepackt?

Unser Firmen-Repository enthält jedes Kunden- und Service-Repository als Submodul. Eine Session, die in einem Kunden-Repository startete, sah die Skills der Firma nicht, weil Claude Code Projekt-Skills nur bis zur Wurzel des Repositorys sucht, in dem es läuft.

Also wurden die Skills kopiert. Mehrere Kunden-Repositories hatten eigene Versionen von plan, execute und review. Als wir sie verglichen, war jede Kopie von den anderen abgewichen. Niemand hat das entschieden. Es passierte einfach, eine kleine Korrektur nach der anderen, in einem Repo ja, im nächsten nicht.

Die Lösung war nicht mehr Disziplin. Es war ein Plugin, das überall lädt. Seitdem bekommt eine Session im Firmen-Repo, in einem Kunden-Repo oder in einem Service-Repo dieselben Skills, Agenten und Hooks. Eine Änderung landet mit einem PR, die alten Kopien haben wir in begleitenden PRs gelöscht.

Wie lädt ein Plugin in jedem Repository?

Ein Plugin braucht ein Zuhause, den Marketplace. Das ist nur eine Datei .claude-plugin/marketplace.json, die Plugins auflistet und sagt, woher jedes kommt. Unsere listet ein Plugin, das Repository selbst:

{
  "name": "digitaliko",
  "plugins": [{ "name": "wizrd", "source": "./" }]
}

Das Repository, das es nutzt, aktiviert das Plugin in seiner committeten .claude/settings.json. Das ist der echte Block aus unserem Firmen-Repo, in dem das Plugin-Repo ein Submodul unter services/wizrd ist:

{
  "enabledPlugins": { "wizrd@digitaliko": true },
  "extraKnownMarketplaces": {
    "digitaliko": { "source": { "source": "directory", "path": "services/wizrd" } }
  }
}

Die Reihenfolge, die wir wieder wählen würden:

Hooks reisen genauso. Unser Plugin liefert eine Begrüßung bei SessionStart und zwei PreToolUse-Hooks auf Bash: einer blockiert KI-Attribution in Commits und PRs, der andere Pushes, die der Operator nicht machen darf. Ihre Pfade beginnen mit ${CLAUDE_PLUGIN_ROOT}, also funktionieren sie in jedem Repository. Warum das wichtig ist, steht in Claude Code Hooks, die still nichts tun.

Was braucht ein Skill, damit er für ein Team funktioniert?

Weniger, als wir zuerst dachten. Ein echtes Frontmatter aus unserem Plugin, mit gekürzter Beschreibung:

---
name: issue
description: Create GitHub issues at the right level following the canonical labels and issue-body spec. Triggers on /wizrd:issue, gh issue, file issue, create issue, log a task.
allowed-tools: Bash, Read
audience: both
---

Drei Felder tragen das Gewicht:

• description mit echten Auslösern. An dieser Zeile entscheidet das Modell, ob es den Skill lädt. „Hilft bei Issues“ lädt zufällig. Die Wörter, die Leute wirklich tippen, laden ihn, wenn er gebraucht wird.
• audience: human, agent oder both. Das ist unser eigenes Feld, kein Claude-Code-Feld. Ein Skill, den ein Agent allein ausführt, darf nie auf einen Menschen warten. Unser Validator warnt, wenn ein Skill mit agent oder both eine Popup-Frage stellt oder auf Freigabe wartet. Ein Agent fragt stattdessen auf GitHub.
• Klare Namen. Zwei unserer Skills unterschieden sich einmal um einen Buchstaben und taten das Gegenteil. Wir haben sie umbenannt.

Eine Zeit lang verlangten wir in jedem Skill auch feste Abschnitte: ein Playbook, ein Quality Gate, Entscheidungsbefugnisse. Meist wiederholten sie nur den Inhalt. Wir haben die Pflicht gestrichen und die Skills auf die Anweisungen gekürzt, die Verhalten ändern. Heute verlangt der Validator nur noch name, description und audience.

Was ist unterwegs kaputtgegangen?

Meist leise. Dinge liefen durch, obwohl sie nichts mehr prüften.

• Eine Umbenennung, die für immer durch die CI gegangen wäre. Als das Plugin uns einen Namensraum gab, war das alte Präfix vor jedem Skill-Namen überflüssig, also haben wir es entfernt. Unser Check auf Verweise zu gelöschten Skills hatte dieses Präfix fest in seinem Regex. Unverändert hätte er nach der Umbenennung nichts mehr gefunden und wäre für immer grün geblieben.
• Der Validator nannte lebende Skills veraltet. Er baute seine Skill-Liste aus einem lokalen Ordner. Nach dem Umzug ins Plugin hatte ein Kunden-Repository, das plan oder review erwähnte, lokal nichts zum Abgleichen, und seine CI wurde rot. Die Lösung: auch die Skills des Plugins selbst lesen.
• Skills, die niemand nutzte. Manche Skills liefen seit Monaten nicht. Jeder saß trotzdem in jedem Zug im Kontext, weil Namen und Beschreibungen von Plugin-Skills immer geladen sind. Wir haben sie gelöscht. Drei Varianten eines Skills wurden ein Skill mit Modi, und unser eigener Skill zum Schreiben von Skills wich dem eingebauten skill-creator.

Die meisten dieser Korrekturen waren Löschungen. Das Muster sehen wir immer wieder: Ein gemeinsames Plugin macht Ballast sichtbar, weil ihn plötzlich jeder in jeder Session mitträgt.

Persönlich oder geteilt: welche Skills gehören ins Plugin?

Nicht jeder Skill muss geteilt werden. Wie jemand gern arbeitet, kann in seinem eigenen ~/.claude/skills/ bleiben. Was das ganze Team braucht, gehört ins Plugin: Planung, Review, Issues anlegen, die Schritte eines Releases für einen Kunden.

Unser Plugin ist intern, Sie können es nicht installieren. Unser öffentlicher Claude Code Production Starter hat keine Skills. Er enthält die Ebene darunter: Agentenregeln, Hooks und ein CI-Gate. Dort würden wir anfangen.

Was davon hat Ihr Team schon?

Was neben den Skills in die Regeln gehört, behandelt CLAUDE.md und AGENTS.md: Regeln für KI-Code im Team.

Möchten Sie ein gemeinsames Setup für die Agenten Ihres Teams?

Wir richten Skills, Hooks, Regeln und CI direkt in den Repositories eines Teams ein, als Teil von AI-native SDLC für Entwicklerteams. Fehlen Ihrem Team eher Hände als Regeln? Sehen Sie sich einen Senior-Entwickler für Ihr Team an. KI schreibt heute unseren gesamten Code, und ein Senior steht für das Ergebnis ein. Seit 2023 haben wir 15+ Produktionsprojekte geliefert.

Wir melden uns innerhalb von zwei Arbeitstagen und wählen gemeinsam, was wir zuerst lösen.

Wenn Sie lieber zuerst sprechen möchten, buchen Sie ein 15-Minuten-Meeting mit Filip.

Wie viele Kopien desselben Skills leben heute in Ihren Repositories?

Häufige Fragen

Was sind Claude Code Skills?

Ein Skill ist ein Ordner mit einer SKILL.md: oben Frontmatter mit Name und Beschreibung, darunter Anweisungen. Claude Code hält die Beschreibung im Kontext und lädt die vollständigen Anweisungen erst, wenn eine Aufgabe sie braucht oder wenn Sie den Skill als /name starten.

Was ist der Unterschied zwischen Skill und Plugin?

Ein Skill ist ein Satz Anweisungen. Ein Plugin ist ein Ordner, der Skills, Agenten, Hooks und MCP-Server als eine Einheit bündelt, mit einem Manifest in .claude-plugin/plugin.json. Plugin-Skills haben einen Namensraum, unsere laufen als /wizrd:review.

Wie teile ich Claude Code Skills mit meinem Team?

Legen Sie sie in ein Plugin, tragen Sie das Plugin in einen Marketplace ein und aktivieren Sie es in der committeten .claude/settings.json jedes Repositorys. Alle haben dieselbe Version, und eine Änderung landet mit einem PR überall statt in Kopien, die auseinanderlaufen.

Machen viele Skills Claude Code langsamer?

Jeder Skill, den das Modell selbst aufrufen kann, hält Name und Beschreibung in jedem Zug im Kontext. Das kostet Tokens, auch wenn nichts läuft. Skills, die niemand nutzt, löschen wir, und Beschreibungen halten wir kurz und konkret.

Ersetzt ein Skill Hooks oder CI-Checks?

Nein. Ein Skill ist eine Anweisung, die der Agent befolgen kann. Was gelten muss, gehört in einen Hook, eine Lint-Regel, einen Test oder die CI, wo der Agent es nicht überspringen kann.