Claude Code Skills: Schreiben und Testen deiner ersten SKILL.md

Nach der offiziellen Claude Code Skills-Dokumentation ist eine Skill ein Ordner, der eine SKILL.md-Datei mit YAML-Frontmatter und Markdown-Anweisungen enthält. Claude lädt Name und Beschreibung beim Start, zieht den vollständigen Text aber erst, wenn die Skill benötigt wird. Dieses progressive-disclosure-Design hält den Kontext schlank. Was du hier bekommst: eine originale Skill zum Auditing interner Links, von Grund auf neu geschrieben, mit Trigger-Testfällen, einer Ergebnis-Rubrik und den Verpackungsschritten, um sie wiederholbar zu machen.

Ein funktionierendes SKILL.md-Beispiel

Lass uns mit dem fertigen Artefakt starten, damit du siehst, wohin wir gehen. Unten ist eine Skill, die interne Links auf einer Website auditet. Kopiere sie, installiere sie und lies dann den Rest des Beitrags, um jede Entscheidung zu verstehen.

description: >

Audits internal links in a project's HTML or Markdown output.

Use when the user asks to check broken links, find dead anchors,

audit site links, or review internal navigation before a deploy.

``

## Internal Link Audit

``

Run a link audit against the built output or source files.

``

### Steps

``

1. Collect all internal links (href or markdown link targets starting

with / or a relative path).

2. Resolve each link against the project root.

3. Check whether the resolved target file or anchor exists on disk.

4. Report broken links grouped by source file. For each broken link,

show: source file, link text, href, and the reason it fails

(missing file, missing anchor, or redirect loop if detectable).

5. List passing links only in a summary count, not individually.

6. If zero broken links are found, say so explicitly.

``

### Output format

``

- Broken links: grouped table per source file.

- Summary line: "X of Y internal links are broken."

- If scripts/ contains check-links.sh, run it first and append

Claude's analysis below the script output.

Das ist eine echte, funktionierende Skill. Speichere sie unter ~/.claude/skills/internal-link-audit/SKILL.md und sie ist sofort in jedem Projekt verfügbar.

Ein wichtiger Punkt: Die offizielle Dokumentation bestätigt, dass benutzerdefinierte Befehle in Skills zusammengefasst wurden. Beide können mit /name aufgerufen werden. So funktioniert /internal-link-audit als direkter Befehl, und Claude matched ihn auch automatisch aus einer natürlichsprachigen Anfrage. Das sind nicht zwei separate Mechanismen.

Wähle eine enge Aufgabe und schreibe die Beschreibung

Das description-Feld ist keine Dokumentation. Es ist der Trigger. Jedes Wort darin hilft Claude entweder, die Skill zum richtigen Moment zu matched, oder fügt Lärm hinzu, der das Matching verschlechtert.

Hidekazu Konishis Leitfaden bringt es auf den Punkt: Eine vage Beschreibung ist der einzige häufigste Grund, warum eine Skill nie ausgelöst wird. Schreibe sie in der dritten Person. Beginne mit dem primären Anwendungsfall. Dann liste die tatsächlichen Phrasen auf, die Benutzer eingeben, denn das Matching geschieht gegen diese Phrasen, nicht gegen deine interne Idee der Skill.

Schlechte Beschreibung: Hilft mit Links und verwandten Dingen in Web-Projekten.

Besser: Auditet interne Links in HTML- oder Markdown-Ausgaben eines Projekts.

Use when the user asks to check broken links, find dead anchors,

audit site links, or review internal navigation before a deploy.

Beachte, dass die zweite Version die Aktion („Auditet interne Links") an den Anfang stellt, die Dateitypen benennt und dann vier konkrete Trigger-Phrasen in der Use when-Klausel angibt. Jede Phrase ist etwas, das ein Entwickler tatsächlich eingeben würde.

Eng ist besser

Widerstehe dem Drang, einen „generellen Link-Checker" zu bauen. Eine Skill, die eine Sache gut macht, wird zuverlässig ausgelöst. Eine Skill, die verspricht Links zu checken, Weiterleitungen zu validieren und Page-Speed zu berichten, wird unzuverlässig ausgelöst und gibt Ausgaben inkonsistent. Wähle den kleinsten nützlichen Teil. Du kannst jederzeit eine zweite Skill für den Rest schreiben.

Für das internal-link-audit waren die Verengungsentscheidungen:

• Nur interne Links, nicht externe (verschiedene Werkzeuge, verschiedene Fehlermodi)
• Prüft Dateiexistenz und Anker-Existenz, nicht HTTP-Status
• Fehlerhafte Links nach Quelldatei gruppiert, nicht als flache Liste

Jede Eingrenzungsentscheidung macht die Trigger-Phrasen spezifischer und das Ausgabeformat leichter zu validieren.

Kontrolle von Aufruf und unterstützenden Dateien

Skills werden automatisch geladen, wenn Claude die Beschreibung erkennt, und reagieren auch auf explizite /skill-name Befehle. Laut der offiziellen Dokumentation scannt Claude beim Start vier Orte: persönlich (~/.claude/skills/), Projekt (.claude/skills/), Plugin und Enterprise. Enterprise überschreibt Personal, Personal überschreibt Projekt. Die Hierarchie ist wichtig, wenn du einen Skill für ein Team bereitstellst, wo lokale Anpassungen in Konflikt geraten könnten.

Für den Aufruf hast du zwei Pfade:

1. Automatisch: Claude liest deine Anfrage, gleicht sie mit geladenen Beschreibungen ab, aktiviert den Skill. Kein Schrägstrich-Befehl nötig.
2. Explizit: Du gibst /internal-link-audit ein. Claude lädt den vollständigen SKILL.md-Body und führt ihn aus. Nützlich zum Testen und für Momente, in denen die automatische Erkennung nicht greift.

Beide Pfade führen dieselben Anweisungen aus. Der Unterschied ist nicht „manuell versus automatisch", sondern welches Signal Claude nutzt, um zu entscheiden, dass der Skill zutrifft.

Unterstützende Dateien

Ein Skill-Ordner kann mehr als nur SKILL.md enthalten:

• scripts/: Ausführbarer Code (Bash, Python), auf den der Skill-Body verweist. Der internal-link-audit Skill verweist auf scripts/check-links.sh, falls vorhanden, sodass du später ein echtes Link-Check-Skript einbinden kannst, ohne die Anweisungen zu ändern.
• references/: Detaillierte Dokumentation, die Claude bei Bedarf lädt, nicht bei jedem Aufruf. Ideal für Edge-Case-Regeln, die du nicht in den Hauptanweisungen haben möchtest.
• assets/: Vorlagen und Ausgabeformate.

Für einen ersten Skill reicht SKILL.md allein. Füge scripts/ hinzu, wenn du einen Befehl hast, den du wirklich ausführen möchtest. Füge references/ hinzu, wenn deine Anweisungen länger werden, weil du ein Dutzend Edge Cases inline behandelst.

Falls du bereits eine CLAUDE.md für projektweite Anweisungen verwaltez, stehen Skills daneben – sie ersetzen sie nicht. Der Claude.md für Agenturen-Beitrag behandelt die Strukturierung dieser Datei separat; Skills handhaben enge, wiederverwendbare Aufgaben, die nicht in eine globale Anweisungsdatei gehören.

Positive und negative Trigger-Tests durchführen

Schreiben ist der einfache Teil. Testen ist dort, wo die meisten Menschen zu früh aufhören. Gemäß dem Towards Data Science-Leitfaden zu produktionsreifen Claude Code Skills bedeutet „Testen" hier, echte Prompts gegen den Skill zu werfen und zu prüfen, ob er sich korrekt verhält, nicht Unit Tests im softwaretechnischen Sinne.

Du brauchst zwei Arten von Testfällen: positive (sollten triggern) und negative (sollten nicht triggern).

Positive Trigger-Fälle für internal-link-audit

Diese Prompts sollten den Skill alle automatisch aufrufen:

• "Überprüfe auf fehlerhafte interne Links, bevor ich bereitstelle."
• "Finde tote Anker in meiner Markdown-Ausgabe."
• "Überprüfen Sie die Site-Links im Build-Ordner."
• "Gibt es fehlerhafte Links auf der Website?"
• "Überprüfen Sie die interne Navigation im gesamten Projekt."

Negative Trigger-Fälle

Diese Prompts sollten die Fähigkeit NICHT auslösen. Falls doch, haben Sie ein Über-Triggering-Problem.

• "Überprüfen Sie, ob die externen Links in meiner README noch funktionieren." (externe Links, anderes Aufgabengebiet)
• "Validieren Sie meine sitemap.xml." (völlig andere Aufgabe)
• "Finden Sie fehlerhafte Bilder auf der Seite." (Bilder, nicht Links)
• "Überprüfen Sie den HTTP-Status meiner API-Endpunkte." (HTTP, nicht Dateisystem)

Ergebnisrubrik

Gute Ausgaben von /internal-link-audit müssen alle folgenden Kriterien erfüllen:

Führen Sie zunächst die positiven Fälle aus. Wenn die Skill bei allen fünf funktioniert, fahren Sie mit den negativen Fällen fort. Wenn sie bei einem negativen Fall funktioniert, haben Sie ein Beschreibungsproblem.

Beheben Sie Überauslösungen, verpasste Auslösungen und schwache Ausgaben

Drei Fehlermodi, drei Lösungen. Das sind separate Probleme und jedes hat eine andere Lösung.

Überauslösung bedeutet, dass die Skill funktioniert, wenn sie nicht sollte. Normalerweise verursacht durch eine zu breite Beschreibung. Die Lösung ist, Ausschlusssprachliche zur Use when Klausel hinzuzufügen:

Do NOT use for external link checks, HTTP status checks,

sitemap validation, or image audits.

Das Hinzufügen expliziter Ausschlüsse begrenzt die Übereinstimmungsfläche, ohne die positiven Auslösungen zu entfernen.

Verpasste Auslösungen bedeuten, dass die Skill existiert, aber nie automatisch funktioniert. Die Beschreibung entspricht nicht der echten Benutzersprache. Die Lösung ist, mehr Trigger-Phrasen hinzuzufügen, die widerspiegeln, wie Menschen tatsächlich fragen, nicht wie Sie die Aufgabe formal beschreiben würden. „Gibt es tote Links?" ist anders als „interne Navigation prüfen", beide sollten die gleiche Skill auslösen.

Der Towards Data Science Guide beschreibt eine Optimierungsschleife: Testfälle aufteilen, Auslösungsrate messen, verbesserte Beschreibungen generieren, den besten Score auswählen. Sie können dies manuell mit einer Handvoll Prompts tun, oder Anthropics Skill-Creator-Skill verwenden, um es teilweise zu automatisieren.

Schwache Ausgabe bedeutet, dass die Skill funktioniert, aber die Ausgabe ist inkonsistent oder unvollständig. Das ist ein Body-Problem, kein Beschreibungsproblem. Schauen Sie sich die Rubrik an, die Sie definiert haben. Welche Kriterien schlagen fehl? Fügen Sie spezifischere Formatierungsanweisungen hinzu. Wenn die Ausgabe die Spalte „Fehlergrund" fehlt, sagen Sie dies explizit in den Anweisungen. Wenn sie alle bestandenen Links aufzählt (was Sie nicht möchten), fügen Sie „Führen Sie bestandene Links nicht einzeln auf" hinzu.

Wenn Sie einen Stapel von Claude Code Automatisierungen verwalten und das größere Bild dessen möchten, wie Skills hineinpassen, deckt der Claude Code Superpowers Post den umgebenden Workflow ab.

Für wachsende Teams oder Agenturen, die mehrere Kundenprojekte bearbeiten, lohnt sich ein Blick auf die dedizierte Claude Code Agency Setup Seite, da sie erklärt, wie Skills in einer Multi-Projekt-Umgebung organisiert werden.

Packen Sie die Skill und pflegen Sie sie

Sobald die Skill alle positiven Tests besteht und keinen der negativen, packen Sie sie ordnungsgemäß.

Endgültige Ordnerstruktur

~/.claude/skills/internal-link-audit/

├── SKILL.md

├── scripts/

│ └── check-links.sh (optional, referenced in instructions)

└── references/

└── anchor-edge-cases.md (optional, for edge-case rules)

Teilen über Projekte und Personen hinweg

Persönliche Skills in ~/.claude/skills/ sind auf jedem Projekt auf Ihrer Maschine verfügbar. Für die Teamverteilung verschieben Sie die Skill in ein gemeinsames Repository und lassen Sie Teammitglieder sie in ihren persönlichen Skills-Ordner symlink oder kopieren, oder committen Sie sie in .claude/skills/ in einem gemeinsamen Projekt-Repo für projektbezogenen Zugriff.

Das Skill-Format ist ein offener Standard. Nach dem Build Guide von freeCodeCamp funktioniert die gleiche SKILL.md Struktur in Claude Code, GitHub Copilot, Cursor und Gemini CLI, Installationspfade unterscheiden sich, aber das Dateiformat nicht. Für Claude Code ist der Pfad ~/.claude/skills/. Für Copilot ist es ~/.copilot/skills/. Gleiche Datei, anderes Zuhause.

Wartung

Skills driften ab. Die Projektstruktur ändert sich, das Ausgabeformat muss aktualisiert werden, oder die Trigger-Phrasen passen nicht mehr dazu, wie das Team über die Aufgabe spricht. Behandeln Sie SKILL.md wie jedes andere Dokument in Ihrem Repo: versionieren Sie es, überprüfen Sie es, wenn sich der zugrunde liegende Workflow ändert, und führen Sie die Trigger-Tests nach jeder Bearbeitung der Beschreibung erneut aus.

Eine nummerierte Wartungs-Checkliste:

1. Führen Sie alle positiven und negativen Trigger-Tests nach jeder Beschreibungsänderung erneut aus.
2. Aktualisieren Sie die Ergebnis-Rubrik, wenn sich die Ausgabeformatanforderungen ändern.
3. Wenn Sie ein Skript zu scripts/ hinzufügen, referenzieren Sie es explizit in SKILL.md Body, damit Claude weiß, dass es verwendet werden soll.
4. Wenn Sie eine persönliche Fähigkeit in eine Team-Fähigkeit umwandeln, überprüfen Sie die Trigger-Phrasen – Teamkollegen verwenden möglicherweise eine andere Sprache als Sie.
5. Löschen Sie Fähigkeiten, die nicht mehr verwendet werden. Veraltete Fähigkeiten, die unerwartet ausgelöst werden, sind schlimmer als gar keine Fähigkeit.

FAQ

Wo genau muss die Datei SKILL.md gespeichert sein?

Für persönliche Fähigkeiten, die projektübergreifend verfügbar sind, liegt der Pfad bei ~/.claude/skills/your-skill-name/SKILL.md . Der Verzeichnisname wird zum Schrägstrich-Befehl. Für projektgebundene Fähigkeiten (nur in einem Repository verfügbar) verwenden Sie .claude/skills/your-skill-name/SKILL.md im Projektstammverzeichnis. Enterprise-Fähigkeiten folgen einem separaten Pfad, der von Ihrer Organisation verwaltet wird Claude Code Admin verwaltet wird.

Wird der volle Inhalt der Fähigkeit jedes Mal geladen, wenn Claude startet?

Nein. Nach der offiziellen Dokumentation scannt Claude die Fähigkeitsverzeichnisse beim Start, lädt aber nur den Namen und die Beschreibung in den Kontext. Der vollständige SKILL.md-Inhalt wird nur geladen, wenn die Fähigkeit einer Anfrage zugeordnet wird. Das ist das Progressive-Disclosure-Design: Beschreibungen bleiben im Kontext, vollständige Anweisungen werden bei Bedarf geladen.

Können mehrere Fähigkeiten für dieselbe Anfrage ausgelöst werden?

Fähigkeiten werden einzeln abgeglichen. Wenn zwei Fähigkeiten Beschreibungen haben, die beide dieselbe Anfrage erfüllen, gilt die Prioritätshierarchie: Enterprise setzt persönlich außer Kraft, persönlich setzt Projekt außer Kraft. Innerhalb desselben Tiers sollten Sie die Beschreibungen sorgfältiger unterscheiden, damit nur die beabsichtigte Fähigkeit ausgelöst wird. Doppelte Trigger sind normalerweise ein Zeichen dafür, dass zwei Fähigkeiten sich überschneidende Funktionen haben und zusammengefasst oder eingegrenzt werden sollten.

Was passiert, wenn die Beschreibung „Use when" sagt, der Benutzer aber den Schrägstrich-Befehl direkt eingibt?

Die Fähigkeit wird trotzdem ausgeführt. Explizite Aufrufe über /skill-name umgehen das automatische Matching vollständig und laden den vollständigen Inhalt sofort. Die „Use when"-Klausel des description-Felds gilt nur für das automatische Matching. Ein direkter Schrägstrich-Befehl funktioniert also immer, auch wenn die Formulierung des Benutzers nicht automatisch erkannt worden wäre.

Wie weiß ich, wann ich eine Fähigkeit verwenden sollte und wann ich Anweisungen zu CLAUDE.md hinzufügen sollte?

CLAUDE.md ist für immer aktive Kontexte gedacht: Projektstruktur, Coding-Konventionen, Dinge, die Claude in jeder Sitzung wissen sollte. Fähigkeiten sind für zeitweilige Aufgaben gedacht: Dinge, die Sie manchmal tun, nicht immer, und für die Sie konsistente Ergebnisse möchten. Wenn Sie feststellen, dass Sie einen mehrstufigen Workflow zu CLAUDE.md hinzufügen, gehört dieser wahrscheinlich stattdessen in eine Fähigkeit.

Das description-Feld leistet die Arbeit, die die meisten Leute denken, dass der Inhalt leistet. Schreiben Sie Trigger-Phrasen aus dem tatsächlichen Vokabular Ihres Teams, halten Sie die Aufgabe eng, und der Rest ergibt sich von selbst.