claude-code/05-mcp-skills-hooks.md

Kapitel 5

MCP, Skills und Hooks – Erweiterbarkeit mit Leitplanken

Kern in einem Satz: MCP gibt Claude neue Werkzeuge, Skills geben abrufbare Workflows, Hooks erzwingen maschinen-sichere Schritte – drei Ebenen, die man nicht vermischen sollte.

---

5.1 Entscheidungsmatrix

„Nur schnell GitHub anbinden“: Ein MCP-Server aus einem Blogpost, Token in die Env, fertig. Zwei Wochen später: fünfzehn Tools im Kontext, niemand hat den Server-Code gelesen, und der Agent postet „hilfreiche“ PR-Kommentare, die niemand wollte. Erweiterbarkeit ohne Leitplanken endet genau so – nicht in Magie, sondern in Tool-Chaos.

Die Matrix ordnet Bedarf → Mittel, bevor du den nächsten Server installierst. Sie ergänzt die drei Ebenen aus Kapitel 2 (User / Projekt / Task) – und dieselbe Trennlinie weich/hart, diesmal von der Hook- und MCP-Seite:

• wo / wie dauerhaft etwas liegt (User vs. Projekt vs. Task)
• wie hart es greift (Markdown → Skill → MCP → Hook/deny)

Du wählst Ort und Härte – nicht einen riesigen Prompt, der beides vermischt.

Bedarf	Mittel	Warum
Zugriff auf GitHub/Jira/DB/Browser	MCP-Server	Tools + Resources zur Laufzeit
Wiederholbarer Mehrschritt-Prozess	Skill (/name)	On-demand, spart Kontext
„Nach jedem Edit formatieren“	Hook	Claude kann es nicht überspringen
Immer gültige Coding-Norm	CLAUDE.md / rules	weiche Steuerung
Nie .env lesen	Permission deny (+ optional Hook)	harte Steuerung

Was du vor dem Install prüfst: Welches Bedürfnis habe ich – und reicht die weichere Ebene links?

Welche Ebene ist die falsche?

Dieselben Wünsche, teure Fehlgriffe:

Fehler	Was passiert	Besser
Skill statt Hook für Format	Agent „vergisst“ Format	PostToolUse-Hook
CLAUDE.md-Roman statt Skill	Kontext immer voll	Skill on-demand
MCP „just in case“	Token-Overhead + Angriffsfläche	1–2 Server mit klarem Nutzen
Nur CLAUDE.md gegen Secrets	weich, umgehbar	deny Read

Faustregel: Bitten (Markdown) → Abrufen (Skill) → Anbinden (MCP) → Erzwingen (Hook/deny). Je härter die Anforderung, desto weiter rechts.

{width=90%}

Kosten der falschen Ebene: Eine Prozedur in CLAUDE.md zahlt jede Session Tokens – auch wenn du nur eine Typo fixst. Ein Hook für etwas, das nur „nice to have“ ist, erzeugt Reibung und fragiles Scripting. MCP ohne Nutzen multipliziert Tool-Schemas und Auth-Probleme. Die Matrix ist deshalb keine Theorie: sie spart Geld, Nerven und Incident-Zeit.

Transfer: MCP ist ein offenes Protokoll – Client und Server gibt es jenseits von Claude Code. Skills und Hooks heißen anderswo oft „Commands“, „Workflows“ oder „Automation“; die Härtegrade (Faustregel oben) bleiben. Wer die Ebene wählt, wählt Angriffsfläche und Kontextkosten – nicht nur ein Produktfeature.

---

5.2 MCP – Model Context Protocol

MCP ist die Schicht „Claude bekommt neue Hände“: Issues, Browser, interne APIs. Genau deshalb ist der erste Reflex „installieren und ausprobieren“ riskant – jede Hand ist Code plus oft Credentials.

Claude Code ist MCP-Client (und kann in speziellen Modi auch Server sein). Server liefern Tools wie create_issue, query_db, browse_page.

Wie MCP wirkt: Beim Start (oder Connect) listet der Client die Tools des Servers. Die Tool-Schemas landen im Kontext. Das Modell kann sie wie eingebaute Tools aufrufen – der Harness prüft weiterhin Permissions und fragt dich bei Bedarf. MCP ist also keine Magie außerhalb des Permission-Systems; es ist zusätzliche Tool-Oberfläche.

{width=90%}

Konfiguration

Häufige Orte:

• Projekt: .mcp.json (team-geteilt)
• User: Einträge über /mcp bzw. User-Config
• Managed: managed-mcp.json / Allowlists

Lehrbeispiel mit einem Server (weniger Angriffsfläche). Die Vorlage vorlagen/.mcp.json.beispiel.json (nur online – Begleit-Service → Material / Repo; nicht Teil der stabilen Kerne in Anhang A) kann zusätzliche Server-Einträge (z. B. GitHub) enthalten – im Repo nur freigeben, was ihr wirklich braucht:

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    }
  }
}

HTTP-/Remote-Server und Auth-Flows sind server-spezifisch. Nach dem Hinzufügen:

/mcp

Status, Auth und Tools prüfen.

Ein Server kann „configured“ sein und trotzdem nicht authentifiziert oder abgestürzt. Ohne Status-Check rät das Modell und erfindet Docs.

{width=90%}

Beispiel-Session: Docs über MCP

Nutze die Context7-Tools (falls verbunden), um die aktuelle pytest-Fixture-Dokumentation
zu holen, und schreibe einen Test analog zu unserem store-Test.
Nicht raten, wenn das Tool fehlt – dann sag Bescheid.

Ohne Tool fällt das Modell auf Trainingswissen zurück – oft veraltet. Lieber abbrechen als raten.

Beispiel: GitHub

Mit angebundenem GitHub-MCP oder gh + Allow:

Liste offene PRs mit Label "needs-review".
Fasse Diff-Risiken in 5 Bullets zusammen. Keine Reviews posten.

Lesen ist billig und reversibel; Schreiben auf PRs ist Team-Kommunikation mit Side-Effects.

Sicherheit bei MCP

• Jeder Server ist Code + Credentials, dem du Tools gibst
• Managed-Allowlists (allowedMcpServers) in Unternehmen ernst nehmen
• deny / Hooks auf mcp__…-Toolnamen möglich
• Keine MCP-Server aus unbekannten Repos ohne Review

Toolnamen-Muster:

mcp__<server>__<tool>
mcp__plugin_<plugin>_<server>__<tool>

Du installierst ausgeführte Software mit Netzwerk- und Token-Zugriff. Supply-Chain und Least Privilege gelten wie bei npm – oft mit mehr Schadenradius, weil der Agent Tools selbst vorschlägt.

Achtung: MCP-Server aus unbekannten Repos oder Blogposts ohne Code-Review sind Code plus oft Credentials im Agent-Pfad. Nur vertrauenswürdige Quellen; in Teams Allowlists (allowedMcpServers) ernst nehmen.

---

5.3 Skills und Slash-Commands

Skills sind paketierte Anweisungen (und optional Tool-Hinweise), typisch:

.claude/skills/verify/SKILL.md

Kopiervorlage (nur online – Begleit-Service → Material / Repo; nicht Anhang A): vorlagen/skills/verify/SKILL.md.

---
name: verify
description: Run lint, typecheck, and unit tests for this repo
---

# Verify

1. Run `npm run lint`
2. Run `npm run typecheck` if present
3. Run `npm test`
4. Summarize failures with file:line if possible
5. Do not commit or push

Aufruf:

/verify

Wie Skills Kontext sparen: Der volle Workflow liegt nicht in jeder Session in CLAUDE.md. Er wird geladen, wenn du (oder das Modell, je nach Config) den Skill aufruft. Die description steuert, wann der Skill angeboten wird – vage Descriptions = falsche oder keine Aufrufe.

Skill mit Argumenten und Seiteneffekten

---
name: fix-issue
description: Implement a GitHub issue end-to-end with tests
disable-model-invocation: true
---

# Fix issue $ARGUMENTS

1. Fetch issue $ARGUMENTS (gh or MCP)
2. Explore relevant code read-only
3. Plan, then implement
4. Tests green
5. Propose commit message – do not push unless asked

disable-model-invocation: true: nur du startest den Skill – wichtig bei Deploy/Prod-Aktionen.

Sonst kann das Modell einen „hilfreichen“ Prod-Workflow mitten in einer Explore-Session anstoßen. Menschlicher Start = bewusste Side-Effects.

Bundled vs. Project vs. User

Drei Orte, eine Frage: Soll das Team denselben Workflow erben?

Quelle	Pfad (typisch)
Project	.claude/skills/<name>/SKILL.md
User	~/.claude/skills/…
Plugins	über /plugin

/skills listet und managed.

Project-Skills: dieselben Verify-Schritte für alle. User-Skills eignen sich für persönliche Rituale, die das Team nicht teilen soll.

Custom Slash-Commands (ältere/parallele Form)

Manche Setups nutzen Command-Markdown unter .claude/commands/. Skills sind der modernere, reichere Mechanismus – beide Konzepte heißen im Alltag oft „Slash-Command“. Im Zweifel Projekt scannen und Doku zu Skills lesen.

Grenze zu Hooks: Skills sind Prozeduren on-demand – der Agent kann sie vergessen oder du musst sie aufrufen. Was unverhandelbar ist (Format, Guards, Logging), gehört in Hooks oder Permission-deny, nicht in einen Skill.

{width=90%}

---

5.4 Hooks – wenn „bitte“ nicht reicht

Hooks sind shell/HTTP/MCP/prompt/agent-Handler an Lifecycle-Events.

Wie Hooks sich von CLAUDE.md unterscheiden: Markdown bittet. Hooks laufen im Harness – bei PreToolUse können sie eine Aktion blocken, bevor sie passiert. Deshalb eignen sie sich für Format, Policy-Logging und harte Guards – und deshalb müssen Scripts deterministic und getestet sein.

Welche Hook-Events brauchst du wirklich?

Die Lifecycle-Liste ist lang. Im Alltag starten die meisten Teams mit zwei: PreToolUse (blocken) und PostToolUse (formatieren). Der Rest kommt mit konkreten Compliance- oder Compact-Anforderungen.

Event	Wann	Typischer Einsatz
PreToolUse	vor Tool – kann blocken	gefährliche Commands stoppen
PostToolUse	nach erfolgreichem Tool	format after edit
PermissionRequest	wenn Freigabe-UI kommt	Policy/Logging
Stop	Ende einer Antwort-Runde	Abschluss-Checks
SessionStart / SessionEnd	Session-Grenzen	Setup/Cleanup
PreCompact / PostCompact	vor/nach Compact	wichtige Fakten sichern

Transfer: Unverhandelbar und maschinell prüfbar → Hook. Nur „bitte denk daran“ → CLAUDE.md oder Skill.

Beispiel: Format nach Edit

Settings (siehe vorlagen/settings.hooks-format.json – nur online, Index 8.7):

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/format-changed.sh",
            "args": [],
            "timeout": 60
          }
        ]
      }
    ]
  }
}

Script: vorlagen/hooks/format-changed.sh – nach .claude/hooks/ kopieren und chmod +x.

Format ist binär und häufig – Menschen und Modelle „vergessen“. Der Hook macht den Diff review-fähig, ohne Style-Diskussionen.

Beispiel: gefährliche Bash blocken

Settings-Vorlage: vorlagen/settings.hooks-guard.json. Script: vorlagen/hooks/block-rm.sh – nach .claude/hooks/ kopieren und chmod +x.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh",
            "args": [],
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Das Script liest den Bash-Befehl aus dem Hook-JSON und denied bei rm -r / rm -f-Mustern (Details in der Vorlage). Optionaler Matcher-if-Filter in Settings ist best-effort; Permission deny bleibt die härtere Linie für Policy.

{width=90%}

Deny ist deklarativ und schnell zu reviewen. Hooks fangen komplexere Fälle ab (Regex, Logging). Deny plus Hook – Hooks allein sind umgehbar bei Lücken im Matcher.

Wo Hooks definiert werden

Ort	Scope
~/.claude/settings.json	User
.claude/settings.json	Project (geteilt)
.claude/settings.local.json	Local
Managed settings	Org
Plugin hooks/hooks.json	wenn Plugin an
Skill/Agent-Frontmatter	nur solange aktiv

/hooks zeigt geladene Hooks read-only.

Enterprise: allowManagedHooksOnly kann User/Project-Hooks abschalten.

Ein Tippfehler im Matcher → Hook feuert nie. Ein zu breiter Matcher → Hook blockt alles. /hooks nach dem Setup: Sichtbarkeit schlägt Raten.

---

5.5 Plugins

/plugin

Offizielle Marketplaces liefern Skills, Hooks, MCP-Bündel. Team: gemeinsames enable in Project-Settings (enabledPlugins), statt dass jeder manuell rät.

Wie Plugins zu den drei Ebenen passen: Ein Plugin ist ein Paket aus den Bausteinen, die du schon kennst – nicht eine vierte Magie-Schicht. Review denselben Maßstäben: Welche Tools? Welche Hooks? Welche Credentials?

Wenn der Hook nicht feuert: Matcher zu eng, Script nicht ausführbar, oder Event falsch – /hooks und manuell testen, bevor du mehr MCP installierst.

Mini-Check vor dem Enable (Team):

1. /plugin → Marketplace wählen → Plugin installieren
2. Was kommt mit? Skills-Liste, Hooks (/hooks), MCP (/mcp)
3. Credentials oder Netz-Tools? Wenn ja: Deny/Allowlist und Team-OK
4. In Project-Settings pinnen (Konzept), z. B.:

{
  "enabledPlugins": {
    "code-review@claude-code-plugins": true
  }
}

Pin statt „jeder installiert lokal“: sonst hat jeder Laptop andere Skills und Side-Effects – das Team-Problem aus Kapitel 6 in Klein.

---

5.6 Zusammenspiel – ein Tag im Leben

Schritt	Was passiert	Warum dieses Mittel
1	Session startet → CLAUDE.md + Rules laden	Weiche Dauerregeln, immer relevant
2	Du: /plan Feature	Phasengrenze vor Edits
3	Claude editiert → PostToolUse formatiert	Hook erzwingt Style
4	Claude will pytest → Allow-Regel, kein Prompt	gezieltes Allow gegen Prompt-Müdigkeit
5	Claude will curl → Deny	harte Netz-Grenze
6	Du: /verify Skill → Lint+Tests gebündelt	Prozedur on-demand
7	MCP GitHub → PR-Beschreibung entwerfen	externes System, du freigibst Side-Effects

Typischer Fehlgriff: Format per Bitte statt Hook, PR-Schreiben ohne Scope – MCP ist Außenwelt, nicht die Lösung für alles. Die Ebenen greifen, wenn jede Entscheidung die richtige Härte trifft.

{width=90%}

---

Jetzt selbst machen: Skill + Hook (ca. 15 Min)

In einem Demo-Repo oder in beispiele/todo-cli (dort ohne echten MCP-Server):

1. Kopiere vorlagen/skills/verify/SKILL.md (ZIP/Repo) nach .claude/skills/verify/SKILL.md und passe die Commands an (pytest -q für todo-cli).
2. Kopiere Format-Hook aus vorlagen/settings.hooks-format.json und vorlagen/hooks/format-changed.sh nach .claude/ (Script: chmod +x).
3. Optional: PreToolUse-Guard aus vorlagen/hooks/block-rm.sh + vorlagen/settings.hooks-guard.json.
4. Session starten → /skills und /hooks prüfen → kleine Edit-Aufgabe auslösen → Formatter-Spur im Diff sehen.
5. /verify (bzw. den Skill-Namen) aufrufen und prüfen, dass die echten Repo-Commands laufen.

Erfolgskriterien:

• /skills listet verify
• /hooks zeigt den PostToolUse-Format-Hook
• Ein Edit erzeugt formatierte Datei ohne „bitte formatier“ im Prompt
• Du kannst in einem Satz sagen, warum Format ein Hook und Verify ein Skill ist

---

Checkliste

• MCP nur aus vertrauenswürdigen Quellen
• Mindestens ein Project-Skill für Verify
• Format- oder Lint-Hook, wenn Formatter im Repo existiert
• Destruktive Shell zusätzlich per deny/hook abgesichert
• /mcp und /hooks nach Setup geprüft

Häufige Fehler

Die vier Varianten der GitHub-Montag-Geschichte – als Lookup:

Fehler	Folge	Fix
15 MCP-Server „just in case“	Tool-Chaos, Tokens, Angriffsfläche	2–4 Servers, klarer Zweck
Alles in CLAUDE.md statt Skill	Kontext voll, schlechte Compliance	Skills für Prozeduren
Hook ohne jq/Deps	stiller Fail	doctor, manuell testen
Hook als einzige Security	umgehbar bei Lücken	deny + managed policy

Wenn du nur eines änderst: MCP-Anzahl und Deny für Secrets – der Rest skaliert mit dem Team.

So baust du das in deinem Projekt nach

1. .mcp.json mit einem Server, den ihr wirklich braucht (oder erst Skill+Hook ohne MCP)
2. .claude/skills/verify/SKILL.md aus vorlagen/skills/verify/ (Begleit-Service → Material) mit echten Commands
3. Format-Hook aus dem ZIP/vorlagen/
4. Session: Edit auslösen → Formatter-Spur sehen
5. Team-Doku: „So installierst du MCP-Auth“

Skills, Hooks und MCP-Configs sind keine stabilen Kerne – Index und Online-Pfade: 8.7; Baseline Memory/Policy: Anhang A.

Erfolgskriterien (Projekt): Verify-Skill ist committed; Hook läuft auf einem Test-Edit; /mcp zeigt nur freigegebene Server; ein Kollege kann ohne Slack-Thread onboarden.

Ein Server zuerst: Auth, Toolnamen und Permission-Patterns an einem echten Nutzen lernen, bevor die Matrix unübersichtlich wird.

---

Was du jetzt kannst

• MCP, Skills und Hooks gezielt zuordnen und Fehlentscheidungen benennen
• Einen Verify-Skill und einen Format-Hook bauen und erklären, warum sie unterschiedlich hart sind
• MCP-Risiken benennen und mit Allowlists/deny einschränken

Nächste Schritte

→ Kapitel 06 – Teams, Enterprise und CI: Policies, GitHub Actions, Kosten und Multi-Agent.