Mein Claude-Skills-Workflow

Irgendwann habe ich zum gefühlt hundertsten Mal in dieselbe Session getippt: Nein, keine Emojis in den Logs. Ja, clippy muss clean sein. Nein, bitte kein println!. Und Claude hat jedes Mal brav genickt — und in der nächsten Session wieder bei null angefangen.

Das ist der Punkt, an dem man entweder Geduld entwickelt oder ein Tool baut. Ich habe ein Tool gebaut. Beziehungsweise acht.

Kurz vorweg: Was ist ein Skill?

Ein Skill ist erst mal nichts Magisches — eine Textdatei mit Anweisungen und ein Etikett davor, das sagt, wofür sie gilt. Claude liest das Etikett, und nur wenn die Aufgabe dazu passt, holt er sich die Datei dazu.

Wie ein Ordner im Regal: Der Ordner „Coding-Konventionen" bleibt stehen, solange ich über mein Buchprojekt rede. Sobald ich anfange zu programmieren, wird er rausgezogen. Das ist der ganze Trick — ich muss meine Regeln nicht in jede Unterhaltung reinschreiben, sie liegen einfach griffbereit.

Wie das angefangen hat

Auf der Arbeit wurde schon mit Skills und Harnesses gearbeitet, das war also kein Neuland. Privat hatte ich parallel etwas anderes: eigene Coding Conventions, die ich seit Jahren mit mir rumschleppe und immer wieder von Hand erklärt habe.

Irgendwann lag es auf der Hand, beides zusammenzubringen. Der erste Skill war coding — meine Konventionen, einmal ordentlich aufgeschrieben, ab jetzt für jede Code-Arbeit. Alles Weitere ist daraus gewachsen.

Und genau so entstehen die Skills bis heute: nicht am Reißbrett, sondern weil mir in echten Sessions auffällt, dass ich zum dritten Mal dasselbe erkläre. Das dritte Mal ist der Auslöser.

Aus einem Skill wurde ein Plugin

Inzwischen sind es acht Skills, gebündelt in einem Plugin namens orbitstack. Alles liegt in einem Repo — hier ein Auszug:

claude-skills/
├── README.md
├── justfile
├── scripts/
│   ├── build.sh
│   └── validate.sh
└── skills/
    ├── blog-writing/SKILL.md
    ├── calendar/SKILL.md
    ├── coding/SKILL.md + ref/   (11 Referenzdateien)
    ├── tracky/SKILL.md + ref/SYNTAX.md
    └── ...

Das justfile — selbst eine Neuerung aus diesem Umbau — packt die Skills in eine .plugin-Datei. Die lade ich in Claude Desktop oder Claude Code hoch, einmal neu starten, fertig. build.sh und validate.sh sind die Bau- und Prüfkette dahinter.

Auffällig ist das Ungleichgewicht: coding ist mit Abstand der dickste Brocken, mit eigenen Dateien für Stack, Style, Git, Deploy, Testing, Ports und so weiter. Andere wie calendar oder blog-writing kommen mit einer einzigen Datei aus. Das ist kein Versehen, sondern das Ergebnis meines größten Lernmoments.

Die Landkarte und das Kleingedruckte

Der Fehler am Anfang: Ich habe dieselbe Konvention an mehreren Stellen gepflegt. Und was an zwei Stellen gepflegt wird, driftet auseinander — das ist keine Prognose, das ist ein Naturgesetz.

Die Lösung ist eine Arbeitsteilung. Die SKILL.md ist die knappe Landkarte: jede harte Regel bündig im Fließtext, mit Verweis auf die Detaildatei.

- **Frontends → Svelte (SvelteKit / Vite). Backends, CLIs, MCP servers &
  libraries → Rust** — ...
- **`cargo fmt` und `cargo clippy --all-targets -- -D warnings` müssen
  beide clean sein** ... (siehe `ref/STACK.md`)

Und ganz am Ende ein reines Inhaltsverzeichnis auf die ref/-Dateien:

## References
- Stack, tooling, linting/formatting, crate defaults per language → ref/STACK.md
- Code style (KISS, YAGNI, Rule of Three, comments) → ref/CODE_STYLE.md
- Git, Forgejo/`fj`, commit/push permission, semantic versioning → ref/GIT.md
- ... (insgesamt 11 ref-Dateien)

Das Detail wird nur nachgeladen, wenn es gebraucht wird. Eine Konvention, ein Ort.

Der zweite Teil desselben Lernmoments war die Formulierung. Zu verwaschen, und die Regel wird höflich ignoriert. Zu hart, und sie wird auch da angewendet, wo sie nichts zu suchen hat. Beides musste ich mehrfach nachschärfen.

Skills dürfen sich widersprechen

Das fand ich unerwartet befreiend: Zwei Skills dürfen gegensätzliche Regeln tragen, solange klar ist, wo welche gilt.

Beim khan-buch-Skill — mein Fantasy-Buchprojekt — will ich ausdrücklich keine Empfehlung. Ich will Optionen mit Pro und Contra, und ich entscheide. Beim Coden will ich das exakte Gegenteil: eine klare Ansage, mit Begründung.

Dieselbe Trennung gilt für die Arbeitsweise. Im Buchprojekt steht der Shotgun-Ansatz drin:

Erst viele NPCs, Orte, Konzepte, Systeme und Ereignisse als generische Stubs mit maximal einem Hook. Ausarbeitung und Zusammenführen kommt später. TBD stehen zu lassen ist Absicht, kein Versäumnis — nicht ungefragt auffüllen.

Ein TBD im Worldbuilding ist ein Platzhalter für später. Ein TBD im Code ist ein Bug. Beides steht so in den Skills, und beides ist richtig.

Wie sicher ist die Antwort?

Mein liebstes Detail steckt im repo-sanity-Skill, der ein Repo gegen meine Konventionen prüft. Jeder Punkt der Checkliste ist markiert, wie sicher die Antwort ist:

- **[m]** mechanisch — eine Datei, ein grep oder ein git-Befehl entscheidet.
  Als Fakt berichten.
- **[g]** ein grep findet Kandidaten, du bewertest jeden einzeln. Als
  Einschätzung berichten, mit den Kandidatenzeilen.
- **[j]** Urteil — Code lesen. Stichprobe nehmen, und sagen was gelesen wurde.

Übersetzt:

• [m] ist eine Ja/Nein-Frage, die ein simpler Befehl eindeutig beantwortet — „gibt es die Datei SPEC.md?". Kein Interpretationsspielraum.
• [g] liefert eine Vorauswahl, die noch von Hand geprüft werden muss.
• [j] lässt sich nicht abkürzen — da muss der Code tatsächlich gelesen werden, wie ein Lektorat.

Kurz: von „der Computer weiß es sicher" über „der Computer schlägt vor, jemand entscheidet" bis „nur genaues Hinsehen hilft". Ein Check sieht dann so aus:

- [g] Kein Secret oder Live-Runtime-Config ist getrackt. Getrackte `*.toml`
  jenseits der Tool-Dateien ansehen, `.env`, alles mit `*secret*` oder
  `*token*`; eine Runtime-Config braucht ihr `.example` stattdessen.

Der Unterschied im Alltag ist groß. Ich weiß bei jedem Befund sofort, ob ich ihn glauben oder nachsehen muss.

Zwei Stolperfallen

Erstens: Claude Code im Terminal kann zusätzlich projekteigene Skills haben, und die können mit den Plugin-Skills kollidieren. Das hätte ich gerne vorher gewusst. Stattdessen habe ich zwei Stunden lang gerätselt, warum Claude hartnäckig den coding-Skill in Version 0.12 ausführt, während im Plugin längst 0.16 liegt.

Zweitens: Wenn man jahrelang mit einem Skill arbeitet, die Konventionen dann endgültig festzurrt, sauber umschreibt — und anschließend einen repo-sanity-Skill baut, der jedes Repo gegen genau diese Konventionen prüft …

… dann erwarte bitte nicht, dass dein eigener Code danach noch „okay" ist. hust sagte er nach diversen Stack-Migrationen hust.

Ich, nachdem der repo-sanity-Check eingeführt wurde

Kann natürlich auch einfach der eigene Blödkopf sein, der ruft: „Alles muss der Konvention entsprechen, nyeh nyeh NYEH!"

Was dabei nebenbei entstanden ist

Zwei Tools sind aus diesem Umbau herausgefallen, beide aus demselben Grund: ein bestehender Workflow war mir zu manuell.

bumper hat die Versionierung übernommen. Bumpt nach SemVer — Major, Minor, Patch — und zwar nicht nur für Skill-Revisionen, sondern auch für Rust-Crates und npm-Packages. Ein Tool für alle drei Welten.

tracky hat Notion abgelöst: Tasks, Linkliste, Spiele-Wishlist. Der Kern ist eine Inline-Syntax, in der alles im Text selbst steht — Tags, Priorität, Fälligkeit, Referenzen:

#einkauf                 tag / tasklist / group
!1                       priority, 1 highest … 5 lowest
~20260915T2000           due — a moment
@rezepte/lasagne         → pad with that slug
°42                      → task 42

Leitsatz: Der Text ist die Quelle. Alles andere ist ein Cache darüber. Dazu gibt es einen eigenen Post, der kommt noch.

Und dieser Post hier?

Der läuft auch über einen Skill. blog-writing kennt genau eine Pipeline:

status: Idee → Sammeln → Schreiben → Veröffentlicht   (oder: Verworfen)

Gesammelt wird in tracky — ein Task, ein Scratchpad, lose Stichpunkte. Geschrieben und veröffentlicht wird in satz. Bewusst zwei Tools statt einem, das alles können soll. Dieser Absatz hier stand vor zwei Tagen als Stichpunkt im Pad.

Und jetzt?

Besser als vorher, definitiv. Ein Reibungspunkt bleibt: Ab und zu meckert Claude trotz expliziter Freigabe im Skill wegen eigener Guardrails — git push, Merges, manchmal ein Deploy nach Prod. Per Skill ausdrücklich als safe markiert, trotzdem erst mal Rückfrage.

Das treibe ich ihm noch aus. 😛