Claude Academy
Wird geladen

Skills als institutionelles Wissen

Lektion 65 Min.

Skills sind die Art und Weise, wie eine Organisation ihr institutionelles Wissen operationalisiert. Die Anweisungen sind explizit, versionskontrolliert, breit angewendet und werden zentral aktualisiert, wenn sich die Richtlinie ändert. Die Faustregel: Schreibe einen Skill für institutionelles Wissen, das konsistent angewendet werden muss; schreibe keinen Skill für Komponenten, die in CLAUDE.md oder einen Prompt gehören.

Erste Schritte

  • Voraussetzungen: Keine erforderlich. Eine CLAUDE.md hilft, weil sie das Arbeitswissen des Agenten im Repository hält, aber ein Skill hängt nicht davon ab.
  • Infrastruktur: Eine Richtlinie mit einem benannten Verantwortlichen und einer schriftlichen Quelle der Wahrheit.

Wie man es umsetzt

  1. Wähle ein Wissenselement aus, das heute inkonsistent durchgesetzt wird. Das könnte ein Sicherheitsstandard, eine API-Designkonvention oder eine Markenregel sein.
  2. Schreibe es als Skill, einen Ordner, der eine SKILL.md enthält, deren Frontmatter angibt, wann sie ausgelöst wird, und deren Inhalt angibt, was zu tun ist. Ein Ingenieur schreibt sie anhand der Quelle der Wahrheit des Richtlinienverantwortlichen, mit Unterstützung durch Claude.
  3. Lege den Skill im Repository unter .claude/skills/<name>/ ab, damit er mit dem Code ausgeliefert wird, oder verteile ihn organisationsweit über ein Plugin.
  4. Teste, dass der Skill ausgelöst wird. Bitte Claude, die relevante Aufgabe auf unterschiedliche Weise auszuführen, und bestätige, dass der Skill jedes Mal geladen wird.
  5. Wenn sich die Richtlinie ändert, ändere den Skill und lasse den Richtlinienverantwortlichen die Änderung absegnen.
  6. Ingenieure übernehmen die neue Version automatisch in ihrer nächsten Sitzung.

So sieht es aus

.claude/skills/secure-api-review/SKILL.md:

markdown
---
name: secure-api-review
description: Apply the API security standard. Use whenever creating or
  modifying an external-facing endpoint, reviewing API code, or
  generating an OpenAPI spec.
---
# Secure API review
When you create or change an API endpoint:
1. Authentication: every endpoint requires the gateway JWT;
   no anonymous routes outside /health.
2. Input validation: validate request bodies against the OpenAPI
   schema and reject unknown fields.
3. Audit: every state-changing endpoint emits an audit event with
   actor, action, entity and timestamp.
4. Data classification: fields tagged pii in the schema must never
   appear in logs or error messages.
Run scripts/check-endpoints.sh and include its output in your summary.

Governance-Überlegungen

Ein Skill ist eine Kontrolle, wenn auch eine beratende. Er macht es wahrscheinlich, dass Claude die Richtlinie anwendet, während der Code geschrieben wird, aber nichts zwingt eine Sitzung dazu, sich daran zu halten. Eine Richtlinie, die immer gelten muss, braucht etwas Deterministisches hinter dem Skill, etwa einen Hook, der die Aktion blockiert, oder einen Review-Durchgang, der die Richtlinie beim PR erneut prüft. Der Skill macht Verstöße selten, und der Hook macht sie nahezu unmöglich. Der Hook erfasst einen Verstoß bei der Bearbeitung, und dieselbe Prüfung beim Pull Request erfasst alles, was auf anderem Weg in den Branch gelangt ist. Skill-Aufrufe werden in Sitzungsprotokollen erfasst, und der Richtlinienverantwortliche überprüft Skill-Änderungen wie Code.

Wie man es misst

  • Frühindikator: Zeit von der Genehmigung einer Richtlinienänderung durch den Richtlinienverantwortlichen bis zum Merge des aktualisierten Skills, entnommen aus dem PR für den Skill-Ordner.
  • Spätindikator: PR-Review-Befunde, die sich auf die Richtlinie beziehen, die gegen null tendieren sollten, sobald der Skill die Richtlinie anwendet, während der Code geschrieben wird. Wo die Befunde nicht gegen null tendieren, löst entweder der Skill nicht aus, oder sein Text hat sich von der offiziellen Richtlinie entfernt.

Hooks als Build-Time-Schutzmechanismen

Ein Skill ist eine beratende Kontrolle, während ein Hook die deterministische Schicht dahinter ist. Die meisten Aktionen von Claude sind Dateibearbeitungen und Shell-Befehle während der Implementierung, sodass die Build-Phase der Ort ist, an dem Hooks am häufigsten auslösen können.

Build-Phase-Hooks können:

  • Bearbeitungen an geschützten Pfaden wie generierten Klassen oder einem eingefrorenen Paket blockieren
  • Den Formatter und Linter nach Dateibearbeitungen ausführen, damit sich keine Abweichungen ansammeln
  • Zugangsdaten aus dem Diff heraushalten
  • Jeden Skill absichern, dessen Richtlinie ausnahmslos gelten muss

Ein Hook läuft bei jeder Aktion, die zu ihm passt, daher sollten Build-Phase-Hooks schnell und auf die geänderte Datei begrenzt sein. Schwerere Prüfungen wie die vollständige Testsuite gehören zum Commit oder zum PR.

Dies ist der Hook hinter Regel 4 des zuvor auf dieser Seite gezeigten secure-api-review-Skills. Das Repository gehört einem Versicherer, und dessen Endpunkt-Dateien liegen in claims-api/routes/. Nach jeder Bearbeitung einer dieser Dateien führt der Hook scripts/check-endpoints.sh aus, das Skript im Repository-Stammverzeichnis, das der Skill bereits benennt. Dieses Skript schlägt fehl, wenn ein im OpenAPI-Schema mit pii markiertes Feld einen Log-Aufruf oder einen ausgelösten Fehler erreicht.

Der Hook ist in .claude/settings.json registriert. Die leere args-Liste lässt Claude Code das Skript direkt ausführen, statt über eine Shell:

json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/api-policy.sh",
            "args": [] }
        ]
      }
    ]
  }
}

Das Hook-Skript, .claude/hooks/api-policy.sh:

bash
#!/bin/bash
# Untermauert Regel 4 des secure-api-review-Skills mit demselben Skript, das der Skill ausführt.
file=$(jq -r '.tool_input.file_path')
case "$file" in
  "$CLAUDE_PROJECT_DIR"/claims-api/routes/*.py) ;;
  *) exit 0 ;;                                   # not an endpoint
esac
cd "$CLAUDE_PROJECT_DIR" || exit 2
if ! found=$(scripts/check-endpoints.sh "${file#"$CLAUDE_PROJECT_DIR"/}"); then
  echo "secure-api-review rule 4: a pii field reaches a log or an error message." >&2
  echo "$found" >&2
  exit 2
fi

Ein Hook, der nach einer Bearbeitung läuft, kann diese nicht rückgängig machen, daher stellt der Exit-Code 2 die Nachricht des Skripts vor Claude, das die Zeile dann korrigieren kann. Nach einer Bearbeitung, die den Namen eines Kunden protokolliert, ist dies die Nachricht, die Claude vom Skript sieht:

text
secure-api-review rule 4: a pii field reaches a log or an error message.
claims-api/routes/status.py:10: policy_holder_name

Ein Edit|Write-Hook löst nicht aus, wenn ein Shell-Befehl die Datei umschreibt. Aus diesem Grund läuft dasselbe Skript auch als erforderliche Prüfung bei jedem Pull Request:

yaml
name: API policy
on: pull_request
jobs:
  check-endpoints:          # a required check in branch protection
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: scripts/check-endpoints.sh claims-api/routes/*.py

Ein Hook, der einen Menschen um Genehmigung bittet, gehört zu den Gates in Stufe 5: Bereitstellung, denn eine Genehmigungsaufforderung während des Builds bringt eine Person zurück auf den kritischen Pfad aller parallel laufenden Sitzungen.