ssheleg/make-skill

make-skill — Erstelle, retrofitte und veröffentliche Skills auf bewährte Weise

Kopiere aus einem funktionierenden Repository (normalerweise ~/DATA/<name>): ssheleg/super-ux (Multi-Skill-Suite, Cursor-Regeln) oder ssheleg/task-pipeline (Single-Skill- Orchestrator, Release-Automatisierung). make-skill selbst ist nach diesem Kanon gebaut.

Referenzen — bei Bedarf laden

Lesen	Wann
references/agent-skills-spec.md	beim Erstellen oder Prüfen einer JEDEN SKILL.md — harte Grenzen beider Autoritäten, optionale Felder, Budgets, wer was ablehnt
references/authoring.md	beim Schreiben oder Optimieren eines Texts/einer Beschreibung — Namensgebung, dritte Person, Freiheitsgrade, Skriptregeln, Evaluierungsschleifen
references/surfaces.md	beim Veröffentlichen außerhalb von Claude Code — Skills-API-Upload/Versionen/8-pro-Anfrage, claude.ai-Zip, die Netzwerkeinschränkungen
references/enterprise.md	beim Installieren eines fremden Skills oder Verwalten einer Flotte — Risikostufen, Überprüfungscheckliste, Genehmigungstore, Lebenszyklus
references/retrofit.md	beim Prüfen eines bestehenden Skills/Repositories — die 14-Punkte-Checkliste, die Beweisregeln, das Kurzformular für persönliche Skills
references/host-capabilities.md	beim Ausliefern eines Hooks, Subagenten, Befehls, Skripts oder einer MCP-Abhängigkeit — was jeder bietet und kostet, Hook-Ereignisse und Exit-Codes, die Klauseln zur Verschlechterung
references/claude-code-plugin.md	bei allem, das als Claude Code Plugin/Marktplatz ausgeliefert wird — Manifest-Schemata, Komponentenlayout, Pfadvariablen, Fehler bei validate
references/distribution.md	das Repository-Layout, Releases und alle fünf Kanäle — Plugin, Skills CLI, npx, Cursor, Dach-Familien-Repository
references/mcp.md, references/mcp-ship.md	Skill vs. MCP-Server, einen umschließen — dann ausliefern: Einbinden, sein 404, server.json, die Registrierung
references/a2a.md	der Skill erstreckt sich über zwei autonome Agenten (A2A): Agent Cards, Aufgabenlebenszyklus, Delegation

Fehlt in dieser Kopie? Reiner Fallback: raw.githubusercontent.com/ssheleg/make-skill/main/plugins/make-skill/skills/make-skill/references/<file>

Auswahl eines Workflows

Erkenne aus der Anfrage und einem Pfad in $ARGUMENTS; kündige die Wahl an.

Situation	Workflow
Neuer Skill, nur für die Agenten dieses Benutzers	Erstellen (persönlich)
Neuer Skill, von anderen/anderen Agenten installierbar	Erstellen (verteilbar)
Vorhandener Skill oder Repository unter diesem Standard, „entspricht dies der Spezifikation?“	Retrofit
Persönlicher Skill soll verteilbar werden	Promote

Ohne Argument erkenne statt zu fragen: eine SKILL.md, .claude-plugin/ oder plugins/*/skills/*/ im aktuellen Verzeichnis → führe das Retrofit-Audit aus und berichte die Lückentabelle plus EINE nächste Aktion. Nichts zu erkennen → frage in einer Zeile, was erstellt werden soll.

Verteilbare Arbeit ist ein richtiges Projekt: Spezifikation (docs/superpowers/specs/) vor Code, und die Spezifikation legt ZIELPROJEKT-Dateiverträge ZUERST fest — Skills werden gegen diesen Vertrag geschrieben, niemals ad hoc.

Autorenregeln (jeder Workflow)

Spezifikationsboden zuerst — der offene Standard und Anthropics Plattformregeln sind beide nicht verhandelbar; dieser Kanon fügt nur hinzu. Feldtabellen, ihre Unterschiede und die Checkliste: references/agent-skills-spec.md.

• name: Zeichenregeln in references/agent-skills-spec.md; gleich dem Verzeichnisnamen. Die Falle: enthält niemals anthropic oder claude — reservierte Teilzeichenfolgen, die Claude Code fröhlich lädt und die Skills-API beim Hochladen ablehnt, sodass der Fehler auf dem Rechner eines anderen auftritt.
• description: ≤1024 Zeichen (die Grenze gilt für dieses Feld allein, nicht den gesamten Front-Matter-Block), keine spitzen Klammern, dritte Person — sie wird in den System-Prompt eingefügt, wo „Ich kann Ihnen helfen…“ die Auswahl verschlechtert. Gib an, WAS es tut und WANN es verwendet werden soll.
• Das portable optionale Set ist license, compatibility, metadata und allowed-tools — Grenzen und Typen in references/agent-skills-spec.md.
• license ist optional — deklariere es trotzdem, sowohl im Front Matter als auch im marketplace.json-Plugin-Eintrag: Eine root LICENSE-Datei erreicht weder die Plugin-Listung noch einen installierten Skill, und nichts gibt einen Fehler aus, sodass die Lücke offen bleibt (alle sechs Repos hier, 2026-07-30).
• Host-Erweiterungen sind legal, niemals tragend. Claude Code liest einen weiteren host-exklusiven Satz (references/claude-code-plugin.md); andere Agenten ignorieren ihn, sodass ein Skill, der VON einem abhängt, überall sonst defekt ist. Außerhalb von Spezifikation ∪ Host = Tippfehler.
• Text < 500 Zeilen und < 5000 Token und halte 5% Spielraum — ein Text bei 99% des Budgets macht die nächste Korrektur zu einem Kampf mit dem Validator. Schwereres Material geht in references/, scripts/, assets/ INNERHALB des Skill- Verzeichnisses, eine Ebene tief, jede vom Text mit einem angegebenen Ladeauslöser verlinkt („lese X, wenn Y“) — niemals ein bloßes „siehe references/“. Referenzdateien >100 Zeilen beginnen mit einer ## Inhalt-Liste: Ein partielles head-Lesen ist, was Agenten bekommen.
• Fallstricke bleiben in SKILL.md: Der Agent kann nicht wissen, eine Datei über eine Falle zu öffnen, von deren Existenz er nichts weiß.
• Schreibe für die schwächste Oberfläche, die du beanspruchst (references/surfaces.md): Der Claude-API-Container hat KEIN Netzwerk und KEINE Paketinstallation, claude.ai variiert, nur Claude Code hat beides. Ein Skript, das pip install oder curl ausführt, ist ein Claude Code Skill — sage dies in compatibility oder lasse es weg. Nichts synchronisiert sich zwischen Oberflächen; git ist die Quelle der Wahrheit.

Hauszusätze zum Standard:

• Prosa ist Englisch; ein Literal bleibt in der Sprache, in der es getippt wurde. Kyrillisch überlebt nur an vier Stellen, wo die Zeichenkette selbst der Punkt ist: einem Auslösesatz, einem Ablehnungssatz (der Bediener tippt beide — übersetzt stimmen sie nicht mehr mit dem Gesagten überein), einem Eigennamen, einem Sprachbeispiel («вы»/«ты»). Eine Budgetregel vor einer Stilregel: Russisch kodiert mit 1,9–2,3 Zeichen/Token gegenüber Englisch mit 5,0 (cl100k), und das Umschreiben der acht ssheleg- Router ins Englische reduzierte sie 3408 → 1885 Token ohne Bedeutungsverlust.
• description beginnt mit „Verwende, wenn …“ und listet konkrete Auslösesätze auf — auf Englisch UND Russisch (der Benutzer arbeitet in beiden Sprachen). Ein Skill, den niemand auslöst, ist tote Last. Halte auch hier 5% Spielraum (≤970 von 1024): Ein naher Nachbar erzwingt eine „NICHT für …“-Klausel, und eine Beschreibung bei 98% des Limits hat keinen Platz dafür.
• Ein Namensmuster, vorzugsweise Gerundium (processing-pdfs); niemals helper, utils, tools, data — vage Namen verlieren jede Auswahl.
• Ein Skill = eine Aufgabe. Mehrere Belange → mehrere Skills + eine gemeinsame Vertrags- datei. Lege Verträge INNERHALB des Skill-Verzeichnisses ab (references/…): Das Skills CLI versendet nur das EIGENE Verzeichnis des Skills, sodass ein GESCHWISTER-skills/references/ als Claude Code Plugin funktioniert und auf jedem anderen Agenten defekt ankommt. Für mehrere Skills gemeinsam → pro Skill-Verzeichnis duplizieren, Validator-geprüft identisch.
• Text: Imperativ, prozedural, Checklisten statt Prosa; Nicht-Verhandelbares als solches dargestellt. Passe die Vorschriftsmäßigkeit an die Verletzlichkeit an — genaue Befehle für destruktive oder reihenfolgeabhängige Arbeiten, nur Richtung, wo der Kontext entscheidet (references/authoring.md).
• Evaluierung vor Prosa: Führe die Zielaufgabe OHNE Skill aus, notiere die Fehler, schreibe mindestens 3 Evaluierungen dagegen, dann schreibe das Minimum, das besteht; ein Skill, der ohne Baseline gebaut wurde, dokumentiert eingebildete Probleme. Hinzufügen zu einer bestehenden Familie → messe Koexistenz gegen das INSTALLIERTE Set, rate nicht: Der Nachbar, den du nennen würdest, ist normalerweise nicht der nächste.
• Liefere einen Ein-Befehl-Einstiegspunkt: idempotent — Zustand prüfen → fehlende Teile reparieren → Statusbericht → GENAU EINE vorgeschlagene nächste Aktion. Erkenne den Modus, frage niemals. Der Skill IST dieser Befehl; der Aufruf unterscheidet sich je nach Kanal (/<skill> aus einem Skills-Verzeichnis, /<plugin>:<skill> als Plugin) — schreibe beide in die README, anstatt einen zu versprechen.
• Überschreibe niemals Benutzerdaten: seede nur, wenn nicht vorhanden; überschreibe nur hinter --force.

Verschlechterungsvertrag (jeder Skill, der eine Host-Funktion berührt)

Hooks, Subagenten, /commands, Plugin-Pfadvariablen und MCP-Server existieren nur innerhalb von Claude Code — eine Minderheit der Umgebungen, in denen Skills laufen. Jeder ist ein Beschleuniger mit einem schriftlichen Fallback; der Skill erledigt seine Aufgabe trotzdem ohne ihn, nur langsamer. Schreibe die drei Fälle in den Text, in den Worten des Agenten, an dem Punkt, an dem er sie brauchen wird (Formen: references/host-capabilities.md):

• Nicht Claude Code (Cursor, Codex, Skills CLI, API): keine Hooks, keine Subagenten, kein /command. Nenne die Inline-Prozedur; gebündelte scripts/ reisen trotzdem, also gib den Pfad pro Kanal.
• Empfohlenes Plugin/Skill nicht vorhanden: sage einmal, was verschlechtert ist, fahre auf dem manuellen Pfad fort. Eine Stufe, die sich weigert zu starten, weil ein optionaler Begleiter fehlt, ist defekt, nicht streng.
• Werkzeug, Interpreter oder MCP-Server nicht vorhanden: gib es einmal an, falle auf die manuelle Prozedur zurück, wiederhole niemals in einer Schleife. Interaktive Authentifizierung ist ein menschlicher Schritt.

Ein Fallback, den du kennst, aber nicht geschrieben hast, ist kein Fallback.

Arbeitsbeispiele, die dieser Skill mitliefert — kopiere diese, nicht dein Gedächtnis

scripts/audit_skill.py prüft JEDES Skill-Verzeichnis (stdlib; die mechanische Hälfte eines Retrofits), verpackt als bin/make-skill-audit für Claude Code. Daneben: hooks/ (PostToolUse, still, es sei denn, eine SKILL.md wurde geschrieben), commands/skill-audit.md (bewusst NICHT der Name des Skills), agents/skill-auditor.md und sechs Gerüste: assets/SKILL.template.md, assets/plugin.template.json, assets/marketplace.template.json, assets/hooks.template.json, assets/agent.template.md, assets/command.template.md.

Erstellen (persönlich)

~/.claude/skills/<name>/SKILL.md gemäß den Autorenregeln — erledigt. Kein Repo, keine Versionierung; lädt in der nächsten Sitzung. Erwähne Promote als Upgrade-Pfad.

Benötigt Hooks, einen Agenten oder einen MCP-Server, immer noch ohne Repo? Füge .claude-plugin/plugin.json zu diesem selben Ordner hinzu — Claude Code lädt es als <name>@skills-dir in der nächsten Sitzung.

Erstellen (verteilbar)

Der Repo-Baum, das Public-Repo-Minimum, beide claude plugin validate … --strict- Läufe und die Haus-Validator-Spezifikation sind in references/distribution.md → Das verteilbare Repo-Layout. Öffne es vor der ersten Datei. Was unabhängig gilt:

• .claude-plugin/marketplace.json im Repo-Root; das Plugin unter plugins/<name>/ mit seinem eigenen .claude-plugin/plugin.json; der Skill unter plugins/<name>/skills/<skill>/ mit references/, scripts/, assets/ DARIN. Nur Manifeste leben in .claude-plugin/ — Komponenten, die dort vergraben sind, laden als Nichts, während das Plugin weiterhin zu funktionieren scheint.
• Versionssynchronisation (harte Regel): marketplace.json, plugin.json, package.json und der oberste CHANGELOG-Eintrag tragen die GLEICHE SemVer, zusammen erhöht (+ einem 5. Punkt, wenn SKILL.md metadata.version trägt).
• Beide --strict-Läufe sind grün, in CI, als eigener Job — sie lesen nur MANIFESTE, also leben Front-Matter-Regeln in deinem eigenen test/validate.py, das einen negativen Selbsttest benötigt: Ein Validator, der nicht fehlschlagen kann, ist Dekoration. Liefere $schema und displayName in plugin.json UND im Marktplatz-EINTRAG (der Marktplatz-Root akzeptiert keines von beidem).
• Ein öffentliches Repo schuldet einem Leser eine Englisch-zuerst README, CONTRIBUTING.md mit den Offline-Befehlen, die eine Änderung verifizieren, und SECURITY.md, das einen privaten Kanal benennt und was die Installateure berühren.

Erste Veröffentlichung — Ende-zu-Ende, gleiche Sitzung

Mache es GANZ durch, keine halbfertigen Übergaben. Nur die erste Veröffentlichung braucht einen Menschen (npm 2FA); CI-Veröffentlichung zu bewaffnen ist Teil des Auslieferns, also tut die zweite es nicht. Die 11-Schritt-Sequenz ist in references/distribution.md → Erste Veröffentlichung. Erledigt = fünf VERIFIZIERTE Fakten: Repo + CI grün, npm über npx auflösbar, Plugin installiert, Skills-CLI-Erkennung funktioniert, nächste Tag-Veröffentlichung ohne Menschen.

Retrofit (einen bestehenden Skill/ein bestehendes Repo auf Standard bringen)

Prüfe zuerst, repariere als Zweites, in der gleichen Sitzung. Urteil pro Punkt: BESTANDEN / LÜCKE / NICHT-AUSGEFÜHRT mit Nachweis — eine datei:zeile oder die Ausgabe des Befehls, den du wirklich ausgeführt hast. „Sieht gut aus“ ist kein Urteil, und auch kein BESTANDEN bei einer Prüfung, die statt ausgeführt nur durchdacht wurde; eine Prüfung, deren Werkzeug fehlt, ist NICHT-AUSGEFÜHRT mit dem Grund, niemals ein BESTANDEN.

Führe zuerst den gebündelten Prüfer aus — er erledigt die mechanische Hälfte deterministisch und hängt niemals von einer nicht gesetzten Variable ab:

make-skill-audit <skill-verz> --house    # Claude Code: das bin/ des Plugins ist im PATH

Woanders führe scripts/audit_skill.py aus dem make-skill-Verzeichnis aus, aus dem du dies gerade gelesen hast. Dann arbeite die 14-Punkte-Checkliste in references/retrofit.md ab — Spezifikationsboden, Plugin-Boden, Oberflächen, Eine-Aufgabe, Einstiegs- punkt, Layout und Versionssynchronisation, Validator und CI, Evaluierungen, README, Distribution, Repo-Metadaten, Fallstricke, Protokolle, Host-Funktionen. Für einen PERSÖNLICHEN Skill gelten nur drei Punkte; diese Datei sagt welche.

Dann: Berichte die Lückentabelle, repariere alles jetzt Reparierbare, erhöhe eine Minor/Patch- Version, führe die Release-Checkliste aus.

Promote (persönlich → verteilbar)

Erstelle das Repo gemäß Layout, verschiebe den Skill in plugins/<name>/skills/<skill>/, extrahiere Verträge nach references/, dann führe die erste Veröffentlichung Ende-zu-Ende durch. Lösche die alte ~/.claude/skills/<skill>-Kopie erst, NACHDEM die Plugin-Installation verifiziert ist.

Installieren eines fremden Skills

Ein Skill sind Anweisungen, die ein Agent ausführt, plus Code, den er ohne Lesen ausführt — jemanden zu installieren bedeutet, Software zu installieren. Alles, was du nicht geschrieben hast, bekommt die Überprüfungs- checkliste in references/enterprise.md ZUERST. Das risikoreichste Muster: ein Skill, der seine Anweisungen von einer URL abruft — dieser Inhalt ändert sich nach der Überprüfung, die ihn genehmigt hat.

Protokollverbundene Skills (MCP / A2A)

Ein Skill sind Anweisungen; er kann keine Fähigkeit verleihen. Dem Agenten das WIE beizubringen ist ein Skill. Neue Fähigkeit gegen ein Live-System ist ein MCP-Server (mcp.md, dann mcp-ship.md, um ihn einzubinden und zu veröffentlichen). Das Delegieren eines Ergebnisses an einen anderen autonomen Agenten ist A2A (a2a.md). Beide Referenzen tragen die Regeln auf Drahtebene — Werkzeugnamen-Erkennung pro Host, Agent Cards und interaktive Authentifizierung als menschlicher Schritt.