Das Skill-feuert-Kit: so lädt sich ein Claude-Code-Skill von selbst

TL;DR und Fazit

Ein Claude-Code-Skill kann einwandfrei laufen, wenn du seinen Namen tippst, und sich trotzdem nie laden, wenn du in normalen Worten fragst. Bevor Claude entscheidet, einen Skill zu laden, liest es pro Skill eine Zeile: den Namen und die Beschreibung. Es gleicht diese Zeile mit deinen Worten ab. Benutzt die Zeile deine Worte nicht, bleibt der Skill stumm.

In unserem Lauf wurde ein Release-Notes-Skill mit der Beschreibung "Generates changelog documents from repository history." bei der Anfrage "what did we ship this week?" in 0 von 5 frischen Sitzungen geladen. Wir haben diese eine Zeile umgeschrieben: was er tut, wann man ihn nutzt und die Worte, die wir tippen. Dieselbe Anfrage lud ihn dann in 5 von 5.

Das Fazit:

• Ein Skill lohnt sich für eine Aufgabe, die du mit festem Ergebnis wiederholst: wöchentliche Notes, eine Pull-Request-Beschreibung, eine Release-Checkliste.
• Für eine einmalige Frage lohnt er sich nicht, und er ist nicht das Werkzeug für eine Regel, die immer gelten muss. Das ist die Aufgabe eines Hooks.
• Ein Haufen Skills, die niemand nutzt, kostet dich, denn jenseits des Budgets für die Liste kürzt Claude Code Beschreibungen, die am wenigsten genutzten zuerst.
• Die eine Regel: Schreib die Beschreibung in den Worten, die du tatsächlich tippst, wenn du um die Aufgabe bittest.

Das Kit unten enthält unsere Skill-Datei davor und danach, eine Beschreibungsvorlage, die Checkliste für frische Sitzungen und den Test mit zwanzig Anfragen, den wir benutzt haben.

Was die Docs und die Praxis sagen

Wo ein Skill liegt. Ein Skill ist ein Ordner mit einer SKILL.md darin, entweder in ~/.claude/skills/<skill-name>/ für jedes Projekt oder in .claude/skills/<skill-name>/, damit dein Team ihn auch bekommt. Eine lose name.md-Datei lädt nicht. s1 s2

Claude liest die Beschreibung, nicht den Rumpf. Die Liste mit Namen und Beschreibungen steht in jedem Zug im Kontext, und der Rumpf lädt nur, wenn der Skill aufgerufen wird. Laut Docs nutzt Claude die Beschreibung, um zu entscheiden, wann der Skill angewendet wird. s1

Die Liste hat eine Obergrenze und ein Budget. Der Text von Beschreibung und when_to_use wird gemeinsam bei 1.536 Zeichen gekürzt. Die gesamte Liste ist auf 1 % des Kontextfensters begrenzt, und wenn sie überläuft, streicht Claude Code Beschreibungen, beginnend bei den Skills, die du am seltensten aufrufst. Die Docs sagen, dass dadurch die Schlüsselwörter fehlen, die Claude braucht, um deine Anfrage zuzuordnen. Mit --debug siehst du eine Warnung im Debug-Log. s1

Ein kaputter Header ist die Falle, die wie Erfolg aussieht. Ist das YAML fehlerhaft, lädt der Rumpf mit leeren Metadaten, sodass /skill-name weiter funktioniert, Claude aber deine Beschreibung nicht zuordnen kann. Starte mit --debug, um den Parse-Fehler zu sehen, oder führe claude plugin validate .claude/skills aus. s1 s2

Prüf das Badge. Erscheint ein Skill in /skills, aber Claude ruft ihn nie auf, ist entweder disable-model-invocation: true gesetzt oder die Beschreibung passt nicht dazu, wie du die Anfrage formulierst. Ein Label user-only bedeutet, dass Claude ihn nicht von selbst auslöst. s2

Was eine gute Beschreibung enthält. Anthropics Guide sagt, die Beschreibung soll enthalten, was der Skill tut und wann man ihn nutzt, in der dritten Person, mit den Schlüsselbegriffen, die Nutzer tippen. Er merkt an, dass Claude sie nutzt, um aus potenziell mehr als 100 Skills den richtigen zu wählen. s3

Claude neigt zum Untertriggern. Anthropics skill-creator sagt "currently Claude has a tendency to 'undertrigger' skills" und empfiehlt eine leicht "pushy" Beschreibung. s18 Sein Trigger-Test nutzt 20 Anfragen, eine Mischung aus solchen, die auslösen sollen, und solchen, die nicht auslösen sollen, wobei Beinahe-Treffer am wertvollsten sind. Die Schleife teilt sie in 60 % Training und 40 % zurückgehaltenen Test, führt jede Anfrage 3-mal aus und behält die Beschreibung mit dem besten Testwert. s4 Das Eval-Skript lässt jede Anfrage über claude -p laufen und prüft, ob der Skill benutzt wurde. s19

Aktivierung verhält sich wie Keyword-Matching. Auf dem echten Binary maß ein Drittanbieter-Test (22 Prompts, Sonnet 4.5) in zwei Läufen eine Baseline von 55 % und 50 % und einen Forced-Evaluation-Hook bei 100 %. Ein Prompt mit einem expliziten Token wurde zu nahezu 100 % aktiviert, während indirekte Formulierungen nahe 0 % lagen. Die Lesart des Autors: näher an Keyword-Matching als an semantischem Matching. Das ist ein Blog, ein älteres Modell und ein anderes Repo, also nimm es als stützende Evidenz, nicht als Regel. s5

Die Beschreibung ist ein Auslöser, keine Zusammenfassung. Ein Audit von neun echten Skills kam zum selben Schluss: Eine Beschreibung, die konkrete Situationen aufzählt, schlägt eine, die sagt, was der Skill ist. s8

Auch der umgekehrte Fehler existiert. Ein Entwickler sah einen Skill bei den falschen Aufgaben auslösen, schrieb Trigger-Evals, formulierte die Beschreibung als "Load when..." um und hielt fest, dass ein Skill, den man behalten will, meist aus einem Fehler entsteht, den man nicht zweimal sehen will. s11

Andere traf das auch. Das Issue "Claude Code not aware of skills in .claude/skills" hat 75 Reaktionen und war am 2026-10-17 noch offen. Workarounds im Thread sind ein CLAUDE.md-Verweis und ein Hook. s7

Wo ein Hook einen Skill schlägt. Eine Top-Antwort in einem Thread mit 778 Upvotes sagt, ein Skill sei "basically just a prompt you save for later", den Claude nutzen kann oder den du per Slash-Befehl aufrufst, und ein Hook sei für den Fall, dass Skills zu locker sind und du Determinismus willst. s9 Ein anderer Thread warnt, dass Erinnerungs-Anstupser in einer langen Sitzung verblassen können. s10

Das Kit

Der Skill davor und danach. Nur die Beschreibungszeile unterscheidet sich, der Rumpf ist identisch.

release-notes.before.SKILL.md

---
name: release-notes
description: Generates changelog documents from repository history.
---

# Release notes

1. Find the range: commits since last Monday (`git log --since="last monday" --no-merges --pretty="%h %s"`).
2. Drop `chore` and `docs` commits.
3. Group what is left by the conventional-commit scope (router, css, jsx, serve-static...), fixes and features apart.
4. Write one line per change, in plain English, present tense, no commit hashes, with the PR number at the end.
5. Output a markdown block titled "Release notes, week of <date>", with a two-line summary on top.

release-notes.before.SKILL.md on GitHub

release-notes.after.SKILL.md

---
name: release-notes
description: Writes this week's release notes from git log, grouped by scope (router, css, jsx). Use when the user asks what we shipped, what changed this week, for release notes, a changelog, or a summary of recent commits.
---

# Release notes

1. Find the range: commits since last Monday (`git log --since="last monday" --no-merges --pretty="%h %s"`).
2. Drop `chore` and `docs` commits.
3. Group what is left by the conventional-commit scope (router, css, jsx, serve-static...), fixes and features apart.
4. Write one line per change, in plain English, present tense, no commit hashes, with the PR number at the end.
5. Output a markdown block titled "Release notes, week of <date>", with a two-line summary on top.

release-notes.after.SKILL.md on GitHub

Die Beschreibungsvorlage, mit unserer echten Beschreibung als durchgespieltes Beispiel.

description-template.md

# Skill description template

The description is the one line Claude reads before it decides to load your skill. Write it for the moment you ask, not for the file.

## Template

```
<Verb in third person> <what the skill produces>, <how it is shaped>. Use when the user asks <phrase 1>, <phrase 2>, <phrase 3>, or <phrase 4>.
```

Three parts, in this order:

1. What it does. Third person ("Writes", never "I can" or "You can use this"). Name the output.
2. When to use it. Start with "Use when the user asks".
3. Your words. The exact phrases you or your team type, copied from your own history, not synonyms you invented.

Put the key use case first. The description and `when_to_use` are cut together at 1,536 characters in the skill listing.

## Worked example (the real one from our run)

Before, a summary of the skill:

```
Generates changelog documents from repository history.
```

After, what + when + the words we type:

```
Writes this week's release notes from git log, grouped by scope (router, css, jsx). Use when the user asks what we shipped, what changed this week, for release notes, a changelog, or a summary of recent commits.
```

What changed:

- What: "Writes this week's release notes from git log, grouped by scope".
- When: "Use when the user asks ...".
- Your words: "what we shipped", "what changed this week", "release notes", "a changelog", "a summary of recent commits".

## Fill-in sheet

- Skill name:
- The prompt I keep retyping (copy it from your history):
- The output I want from it:
- Verb + output (what it does):
- Four phrases I really type (when):
- Phrases that sound close but are a different job (for your near misses):

## Check before you save

- Third person, no "I" and no "you".
- At least three phrases you really type.
- Under 1,536 characters in total.
- Not so wide that it matches a neighbour job. Add the near misses to your trigger test.

description-template.md on GitHub

Die Checkliste für frische Sitzungen.

trigger-checklist.md

# Fresh-session trigger checklist

A skill that runs by name can still be invisible to a plain request. Test it the way a teammate will use it.

## Test in a fresh session

1. Open a new session. A skill already used stays in the conversation, so a test in the same session proves nothing.
2. Ask for the task in your own words, without the skill's name. Example: "what did we ship this week?"
3. Watch for the Skill tool call before Claude touches anything else. If Claude runs the commands itself and writes its own summary, the skill was skipped.
4. Repeat in several fresh sessions. A handful of runs is a demo, not a statistic.

## If it was skipped, read why before you edit

1. `/skills`: is it listed, is it switched on, is there a `user-only` badge? A `user-only` badge means Claude will not trigger it on its own.
2. Ask "What skills are available?" and check your skill is in the answer.
3. `claude --debug`, then search the log for the skills line (how many loaded) and for a "Skill listing over budget" warning. Over budget means some descriptions are cut, the least invoked first.
4. `claude plugin validate .claude/skills`: a malformed header still lets `/name` work but leaves Claude with empty metadata to match against.
5. Check the file is `.claude/skills/<name>/SKILL.md`, not a loose `<name>.md`, and that the header starts on the first line.

## Fix, then prove it

1. Rewrite the description with `description-template.md`.
2. Fresh session, same plain request, several runs: does the Skill call come first now?
3. Baseline: set the skill to `"off"` in `skillOverrides` (saved to `.claude/settings.local.json` from `/skills`), ask again, then switch it back on.

## Hold it

1. Write twenty requests: ten that should load the skill, ten near misses (`evals.json` is our set).
2. Run each in its own fresh session and note whether the skill loaded (`trigger_test.py`, `tally.py`).
3. Re-run the list every time you change the description.
4. For a skill that must never miss: call it by name, or add a UserPromptSubmit hook (`hook.json`).

trigger-checklist.md on GitHub

Das Testset mit zwanzig Anfragen: zehn Anfragen, die den Skill laden sollen, zehn Beinahe-Treffer, die es nicht sollen. Passe die Anfragen an dein eigenes Repo an.

evals.json

[
  {"query": "what did we ship this week?", "should_trigger": true},
  {"query": "can you put together the release notes for this week", "should_trigger": true},
  {"query": "what changed in the repo since monday", "should_trigger": true},
  {"query": "write the changelog for the commits we merged this week", "should_trigger": true},
  {"query": "I need a summary of this week's commits for the team update on friday", "should_trigger": true},
  {"query": "draft the weekly notes of what got fixed, grouped by area", "should_trigger": true},
  {"query": "list what landed this week, router and css changes apart", "should_trigger": true},
  {"query": "give me something to post in the team channel about this week's fixes", "should_trigger": true},
  {"query": "recap the work merged since last monday", "should_trigger": true},
  {"query": "what's new in hono this week? short version for the release post", "should_trigger": true},
  {"query": "explain what commit 08807ce1 changes in the trie router", "should_trigger": false},
  {"query": "the jsx tests are failing on cloneElement, can you fix them", "should_trigger": false},
  {"query": "write a commit message for my staged changes", "should_trigger": false},
  {"query": "who wrote most of the serve-static code?", "should_trigger": false},
  {"query": "add a CHANGELOG entry format section to CONTRIBUTING.md", "should_trigger": false},
  {"query": "show me the diff between main and my branch", "should_trigger": false},
  {"query": "bump the version in package.json to the next patch", "should_trigger": false},
  {"query": "why does the css helper minify url() like that?", "should_trigger": false},
  {"query": "squash my last three commits into one", "should_trigger": false},
  {"query": "review this PR for breaking changes before I merge it", "should_trigger": false}
]

evals.json on GitHub

Das Skript, das jede Anfrage in einer eigenen frischen claude -p-Sitzung ausführt und zählt, ob das Skill-Tool aufgerufen wurde.

trigger_test.py

"""Twenty-prompt trigger test for one skill, the method skill-creator describes, run on the real skill folder.
For each query: a fresh `claude -p` in the repo; the run counts as loaded if the Skill tool is called with the skill's name
before the run ends (stopped early as soon as it is). Usage:
  python3 trigger_test.py <repo> <skill-name> <SKILL.md to install> <evals.json> <out.json> [workers]"""
import json, os, shutil, subprocess, sys
from concurrent.futures import ThreadPoolExecutor

repo, name, skill_md, evals_path, out = sys.argv[1:6]
workers = int(sys.argv[6]) if len(sys.argv) > 6 else 4
dest = os.path.join(repo, '.claude', 'skills', name)
os.makedirs(dest, exist_ok=True)
shutil.copy(skill_md, os.path.join(dest, 'SKILL.md'))
evals = json.load(open(evals_path))
allowed = ['Bash(rtk git log *)', 'Bash(git log *)', 'Bash(git show *)', 'Bash(date *)', 'Skill', 'Read']

def run(item):
    cmd = ['claude', '-p', item['query'], '--output-format', 'stream-json', '--verbose', '--allowedTools', *allowed]
    p = subprocess.Popen(cmd, cwd=repo, stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, text=True)
    loaded = False
    try:
        for line in p.stdout:
            try:
                d = json.loads(line)
            except ValueError:
                continue
            if d.get('type') == 'assistant':
                for c in d['message'].get('content', []):
                    if c.get('type') == 'tool_use' and c['name'] == 'Skill' and name in json.dumps(c.get('input', {})):
                        loaded = True
            if loaded or d.get('type') == 'result':
                break
    finally:
        if p.poll() is None:
            p.kill()
    return {**item, 'loaded': loaded, 'pass': loaded == item['should_trigger']}

with ThreadPoolExecutor(workers) as ex:
    results = list(ex.map(run, evals))
should = [r for r in results if r['should_trigger']]
shouldnt = [r for r in results if not r['should_trigger']]
summary = {'loaded_when_it_should': sum(r['loaded'] for r in should), 'of_should': len(should),
           'loaded_when_it_should_not': sum(r['loaded'] for r in shouldnt), 'of_should_not': len(shouldnt),
           'passed': sum(r['pass'] for r in results), 'total': len(results)}
json.dump({'skill': name, 'skill_md': skill_md, 'summary': summary, 'results': results}, open(out, 'w'), indent=2)
for r in results:
    print(f"[{'PASS' if r['pass'] else 'FAIL'}] {'loaded ' if r['loaded'] else 'skipped'} expected={'load' if r['should_trigger'] else 'skip'}: {r['query']}")
print(json.dumps(summary))

trigger_test.py on GitHub

Eine kleine Auswertung für einen Ordner mit claude -p --output-format stream-json-Läufen.

tally.py

"""Count whether a `claude -p --output-format stream-json` run loaded a given skill. Usage: python3 tally.py <skill> run1.jsonl [run2.jsonl ...]"""
import json, sys
skill, files = sys.argv[1], sys.argv[2:]
fired = 0
for f in files:
    hit = False
    for line in open(f):
        try:
            d = json.loads(line)
        except ValueError:
            continue
        if d.get('type') == 'assistant':
            for c in d['message'].get('content', []):
                if c.get('type') == 'tool_use' and c['name'] == 'Skill' and skill in json.dumps(c.get('input', {})):
                    hit = True
    fired += hit
    print(f"{f}: {'loaded' if hit else 'skipped'}")
print(f"{skill}: loaded in {fired} of {len(files)} runs")

tally.py on GitHub

Die Must-fire-Absicherung: ein UserPromptSubmit-Hook, der den Skill nennt.

hook.json

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo 'If the user asks about release notes, a changelog or what shipped this week, use the release-notes skill.'"
          }
        ]
      }
    ]
  }
}

hook.json on GitHub

Mach das am Montag

• Schreib den Prompt auf, den du letzte Woche am häufigsten neu getippt hast, und die genaue Ausgabe, die du dafür willst.
• Lege .claude/skills/<name>/SKILL.md an, mit Namen, Beschreibung und einem kurzen nummerierten Rumpf.
• Teste ihn per Namen, öffne dann eine frische Sitzung und bitte in normalen Worten um die Aufgabe, ohne den Namen.
• Wird er übergangen, lies /skills, claude --debug und claude plugin validate .claude/skills, bevor du etwas änderst.
• Schreib die Beschreibung mit description-template.md um: was er tut, wann man ihn nutzt, die Worte, die du tippst.
• Teste in mehreren frischen Sitzungen erneut, dann einmal mit dem Skill auf "off" in skillOverrides und einmal wieder an.
• Schreib deine zwanzig Anfragen, lass sie mit trigger_test.py laufen und wiederhole sie, wann immer du die Beschreibung änderst.
• Entscheide bei einem Skill, der nie fehlen darf: per Namen aufrufen oder den Hook hinzufügen.

Was wir gemessen haben

Das sind kleine Demoläufe auf einem Scratch-Klon des Open-Source-Repos Hono (s20), mit Claude Code 2.1.294 und der Anfrage "what did we ship this week?" bei 8 Nicht-Merge-Conventional-Commits seit Montag, 2026-10-12. Sie sind kein Benchmark. Dein Modell, deine Skills und dein Repo werden die Zahlen verschieben.

Vor dem Umschreiben waren die 4 Anfragen, die luden, die mit "release notes", "changelog", "notes" oder "release": das ist der Keyword-Effekt, offen sichtbar. Nach dem Umschreiben zog die breitere Beschreibung keinen einzigen Beinahe-Treffer an.

Die Warnung, die wir gefunden haben, und die ehrliche Lesart. Mit --debug gab unser Setup aus: "Skill listing over budget: 296 skills, 144833 chars > 30000 budget". Unser Setup trägt zu viele Skills, deshalb werden Beschreibungen gekürzt. Unser Projekt-Skill lud trotzdem ("Loaded 43 unique skills", einer davon der Projekt-Skill), und die alte Beschreibung überstand die Kürzung: Im Test mit zwanzig Anfragen lud die Anfrage mit "changelog", einem Wort, das nur in der Beschreibung steht, den Skill. Wir haben nicht bewiesen, wie das Budget einen neuen Skill allgemein behandelt. Wenn du viele Skills hast, führ die Prüfung selbst durch. /skills listete in unserem Setup 277 Skills, und release-notes erschien als Projekt-Skill, eingeschaltet, ohne Badge user-only.

Ein Vorbehalt zum Werkzeug selbst: Anthropics Eval-Skript sah den Skill auf unserer Version überhaupt nicht, also ließen wir dieselben Anfragen mit dem kurzen Skript aus dem Kit laufen. Die Methode ist dieselbe, eine frische claude -p-Sitzung pro Anfrage.

Weiter gehen

Behebe auch das umgekehrte Problem. Eine Beschreibung, die auf zu viel passt, lässt den Skill dort feuern, wo er es nicht soll. Deshalb besteht die Hälfte des Testsets aus Beinahe-Treffern. Füge die Worte hinzu, die du wirklich benutzt, nicht jedes Wort, das dir einfällt. s11

Lass den Optimizer den Umschrieb vorschlagen. Die Schleife des skill-creator schlägt neue Beschreibungen vor und behält die beste nach dem Wert auf zurückgehaltenen Tests, um Überanpassung an die Anfragen zu vermeiden, auf die du abgestimmt hast. Nutze deine eigenen zwanzig Anfragen als Eval-Set. s4

Nimm einen gehaltvollen Test-Prompt. Der skill-creator merkt an, dass Claude Skills nur für Aufgaben heranzieht, die es allein nicht leicht lösen kann; eine triviale Ein-Schritt-Anfrage löst also selbst bei perfektem Treffer womöglich keinen Skill aus. s4

Geh über den einfachen Hook hinaus. Der obige Drittanbieter-Test fand, dass ein Forced-Evaluation-Hook, der Claude jeden Skill mit Ja oder Nein bewerten und dann aktivieren lässt, 100 % erreichte, wo eine passive Erinnerung es nicht tat, und dass sich ein nativer Hook mit type: "prompt" wie gar kein Hook verhielt. Unser Hook ist die einfache Version, und es ist ein Demolauf. s5 Berichten zufolge können Hook-Anstupser in einer langen Sitzung verblassen. s10

Halte den Rumpf kurz. Im obigen Audit war der eine kaputte Skill 1.002 Zeilen lang mit MANDATORY überall, während die gesunden kurz waren. s8

Was wir weggelassen haben. Wir haben Plugin-Skills und die Plugin-Eval-Grader nicht behandelt, die nur für Plugin-Autoren zählen, und auch nicht, wie man einen Skill über Monate mit dem nackten Modell vergleicht. Manche berichten außerdem, dass Skills, die für schwächere Modelle geschrieben wurden, zum toten Gewicht werden können, also teste sie ab und zu neu. Das haben wir nicht gemessen.

FAQ

Warum funktioniert /release-notes, aber normale Worte nicht? Der Name umgeht das Matching. In normalen Worten hat Claude nur den Namen und eine Beschreibungszeile zum Abgleichen, und eine Zusammenfassung, die kein Wort mit deiner Anfrage teilt, wird übergangen. s1

Muss ich Claude Code nach dem Bearbeiten eines Skills neu starten? Nein. Claude Code übernimmt einen hinzugefügten oder bearbeiteten Skill unter ~/.claude/skills/ oder .claude/skills/ in der laufenden Sitzung. Legst du ein Skills-Verzeichnis auf oberster Ebene an, das beim Start der Sitzung nicht existierte, führe /reload-skills aus. s1

Wie lang darf die Beschreibung sein? Die Beschreibung und when_to_use werden in der Liste gemeinsam bei 1.536 Zeichen gekürzt, also setz den wichtigsten Anwendungsfall nach vorn. Anthropics Plattform-Guide begrenzt eine Beschreibung separat auf 1.024 Zeichen für Skills, die außerhalb von Claude Code hochgeladen werden. s1 s3

Reichen fünf frische Sitzungen, um einem Fix zu trauen? Nein. Sie zeigen die Richtung. Unser Ergebnis ist eine Demo auf einem Repo, deshalb endet das Kit mit einem Test mit zwanzig Anfragen, den du bei jeder Änderung der Beschreibung wiederholen kannst.

Wann sollte ich einen Hook statt eines Skills nehmen? Wenn eine Regel jedes Mal gelten muss, nicht nur dann, wenn Claude einen Treffer bemerkt. Ein Hook fügt jeder Nachricht eine Zeile hinzu, also heb ihn für die wenigen Skills auf, die feuern müssen. s9