shipit-skill – Ein-Pass-Launch-Pipeline für Entwicklerwerkzeuge

Was macht shipit-skill – Ein-Pass-Launch-Pipeline für Entwicklerwerkzeuge?

Ein vorhandenes Repository von „es funktioniert" zu veröffentlicht + gelistet + vermarktbar bringen. Vier Phasen, jede mit einem harten Abbruchkriterium. Das Überspringen einer Phase ist nur erlaubt, wenn ihr Abbruchkriterium bereits erfüllt ist.

Philosophie: Erst prüfen, dann bauen. Überprüfe, was bereits existiert und was das Ökosystem zuerst verlangt – genauso, wie du jedem Benutzer raten würdest, das Rad nicht neu zu erfinden.

---

Phase 0 – Erkundung (30s, immer)

Führe diese Prüfungen durch, bevor du etwas anfasst:

1. Aktueller Repository-Zustand – git status, git remote -v, aktuelles git log.
2. Paketregistrierung – Ist der Name vergeben? (pip index versions <name>, npm view <name>, Registry-CDN). Namen kollidieren oft; Scoped-Namen für npm (@org/pkg) umgehen Typosquatting-Regeln.
3. Ähnliche Projekte – Durchsuche GitHub nach direkten Mitbewerbern. Falls einer existiert, dokumentiere die Abgrenzung explizit; baue keine identische Kopie.
4. Die „Abbruchkriterien“-Lücken – CI? Dockerfile? GitHub Release? gelistet auf Glama / awesome-Verzeichnissen? Werbematerial aktuell? Erstelle eine Checkliste, was fehlt. Diese Checkliste treibt den Rest.

Ausgabe: ein kurzer Lückenbericht + Plan. Hole vor Phase 1 die Bestätigung ein, wenn die Lücken groß sind.

---

Phase 1 – Engineering Baseline

Abbruchkriterium: CI grün auf dem Standard-Branch, Paketmetadaten korrekt, Dockerfile vorhanden (falls es sich um einen MCP/CLI-Server handelt).

• CI: Füge GitHub Actions hinzu. Python: Matrix über unterstützte Versionen, aber beachte Extras, die einen neueren Interpreter benötigen (z. B. mcp>=2.0 benötigt py3.10+ – führe die Basis auf 3.9 aus, Extras auf 3.12). Immer Lint + Tests + einen Container-MCP-Handshake-Job einfügen, falls ein Server ausgeliefert wird.
• Dockerfile: Wird für Glama und Container-Benutzer benötigt. Für stdio-MCP-Server: Basis-Image + Paket installieren + CMD [der-server-befehl]. Aus dem Quellcode bauen (COPY src), es sei denn, das veröffentlichte Paket ist als gut verifiziert – eine veraltete PyPI/npm-Version wird still die Introspection brechen.
• .dockerignore: Image minimal halten (kein .git, Tests, Werbung, Doku).
• Version aus Metadaten: MCP serverInfo.version und CLI --version müssen die Paketversion auslesen, keinen hartcodierten String.
• Abhängigkeits-Untergrenze: Wenn dein Code eine neue SDK-API anspricht, setze die Abhängigkeits-Untergrenze (mcp>=2.0), nicht >=1.0 – pip/npm lösen auf die neueste auf und brechen frische Installationen.

Überprüfe: sauberes pip install .[extras] / npm install in einer temporären venv, dann führe den MCP-Handshake (initialize + tools/list) gegen den Container aus.

---

Phase 2 – Veröffentlichen

Abbruchkriterium: Paket in der Registry, GitHub Release mit Tag + Notizen, Saubere-Umgebung-Installation verifiziert.

• Versionssprung → Artefakte bauen (python -m build / npm pack).
• Tag + GitHub Release: Titel vX.Y.Z, Notizen mit Änderungen / Installation / Was-es-fixiert. Verwende gh release create und hänge die Artefakte an den Tag an.
• Registry veröffentlichen:
  • PyPI: benötigt ein Token (granular, auf das Paket beschränkt, Upload-Berechtigung). Wenn das Token fehlerhaft ist, gibt PyPI 403 Invalid or non-existent authentication information zurück – UUID-artige Zeichenketten sind falsch; echte PyPI-Token beginnen mit pypi-. twine upload mit --username __token__.
  • npm: Scoped-Namen benötigen die Existenz der Organisation; granulare Token mit Bypass-2FA für Automatisierung; --//registry.npmjs.org/:_authToken inline vermeidet das Schreiben von Anmeldeinformationen auf die Festplatte.
• Frisch-Installations-Verifizierung (nicht verhandelbar): Erstelle eine venv / ein sauberes Verzeichnis, installiere aus der Registry, importiere das Modul / führe die CLI aus / führe den MCP-Handshake durch. Dies fängt „funktioniert auf meinem Rechner"-Verpackungsfehler.
• Stolperfallen:
  • npm-CDN liefert für Minuten nach der ersten Veröffentlichung gecachte 404er – nicht in Panik verfallen, Cache mit einem Query-Parameter umgehen.
  • File already exists bei Wiederholung bedeutet normalerweise, dass der erste Versuch erfolgreich war.
  • Lockfile-Drift: Pakete umbenennen → immer npm install ausführen, um das Lock zu regenerieren, sonst schlägt npm ci in CI fehl.

---

Phase 3 – Directory-Listings

Abbruchkriterium: Auf Glama mit einem Score-Badge gelistet und awesome-PR offen (oder gemergt).

• Glama (glama.ai/mcp/servers): Benutzer reicht über den Browser ein (GitHub OAuth – kann nicht automatisiert werden). Vor dem Einreichen: Dockerfile muss existieren und die Introspection bestehen (siehe Phase 1). Nach dem Einreichen: Die Seite erscheint minuten bis stunden später – poll https://glama.ai/mcp/servers/<owner>/<repo> und /badges/score.svg. Füge das Badge in die README des Repos ein, sobald es live ist: [![owner/repo MCP server](https://glama.ai/mcp/servers/owner/repo/badges/score.svg)](https://glama.ai/mcp/servers/owner/repo)
• awesome-mcp-servers (und ähnliche kuratierte Listen): PRs werden von Bots geprüft. Format pro aktueller Konvention der Liste (Badge + Sprache + Umfang + OS + Installationsbefehl). Betreuer verlangen mittlerweile das Glama-Badge im Eintrag – reiche Glama zuerst ein. Füge 🤖🤖🤖 in den PR-Titel ein, um den Agenten-Fast-Track zu nutzen. Fork → Branch vom neuesten upstream-main abzweigen → Eintrag hinzufügen → PR. Wenn ein vorheriger PR wegen Inaktivität geschlossen wurde, force-pushe den Branch oder erstelle ihn neu.
• Andere Verzeichnisse (Smithery, PulseMCP, mcp.so…): Smithery liest eine smithery.yaml im Repository-Stammverzeichnis (stdio-Startbefehl + optionales Umgebungsschema).

---

Phase 4 – Werbematerial

Abbruchkriterium: Versionsnummern/Links/PR-Nummern in den Werbedokumenten stimmen mit der Realität überein; plattformspezifische Beiträge sind bereit zum Einfügen (Benutzer postet manuell – keine vorgetäuschte Automatisierung).

• Pflege promo/ mit plattformspezifischen Dateien (V2EX, 知乎, Reddit, X, Community).
• Frischeprüfung (laufen lassen, wann immer Versionen/PRs sich ändern): durchsuche Werbedateien nach alten Versionsnummern, toten PR-Links, veralteten Release-URLs. Aktualisiere oder markiere sie als veraltet.
• Faktendisziplin: Überprüfe jede Zahl/Behauptung vor dem Posten – führe das Tool erneut aus und vergleiche die Ausgabe. Falsche Behauptungen werden in den Kommentaren auseinandergenommen (z. B. eine „keine Lizenz"-Behauptung, die eigentlich nur eine GitHub-Metadaten-Eigenart ist).
• Halte Installationsbefehle unpinned (pip install pkg), damit Werbung nicht veraltet.

---

CLI-Kurzreferenz (shipit-skill)

Führe diese Befehle aus, um ein Repository durch die Phasen zu bewegen. Alles ist standardmäßig Nur-Ausgabe; die Nebeneffekt-Varianten sind via --execute aktivierbar.

Befehl	Tut	Auto / Ausgabe
doctor [--json]	Umgebungs-Selbsttest: gh authentifiziert, Tokens gesetzt, sauberer Baum auf main	Ausgabe; exit 1 bei Lücken
preflight [--dir .] [--version X.Y.Z] [--json]	Startbereitschafts-Lückenbericht	Ausgabe
init <dir> --server <srv> --pkg <pkg> [--force] [--dry-run]	CI/Dockerfile/smithery.yaml/promo bereitstellen	schreibt Dateien
ci --lang python [--server srv] [--write path] [--release]	ci.yml ausgeben; --release gibt release.yml aus	Ausgabe / schreiben
`bump patch	minor	major
release --lang python --pkg <pkg> [--repo o/r] [--execute]	doctor-Tor → Sprung→Build→publish→Tag→gh Release→Promo-Prüfung. Tag/Release wird nur nach erfolgreichem Publish erstellt; Publish-Fehler rollt den Commit zurück; Wiederholungen überspringen vorhandene Tags/Releases; Notizen aus CHANGELOG	Ausgabe / ausführen
publish --lang python --pkg <pkg> [--server srv] [--execute]	Registry-Upload (Token aus PYPI_TOKEN/NPM_TOKEN-Umgebungsvariable) + Frisch-Installations-Verifizierung	Ausgabe / ausführen
check-promo --dir promo --version X.Y.Z [--prs id=state,...] [--no-links] [--report] [--fix]	Veraltete Versionen / unbekannte PRs / defekte Links; --report gibt JSON aus; --fix überschreibt veraltete Versionen + markiert unbekannte PRs	Ausgabe / JSON / fix
check-glama --repo o/r [--poll N] [--add-badge] [--json]	Auf Glama-Listing warten; --add-badge schreibt README-Badge sobald live; --json strukturiert	Ausgabe / schreiben
awesome-pr --upstream o/r --repo o/r --fork o/r --branch b [--execute --category C --description D --install I]	PR-Rezept, oder tatsächlich fork→edit→push→gh pr create	Ausgabe / ausführen

Tokens: nie auf der Festplatte speichern. publish/release --execute liest PYPI_TOKEN oder NPM_TOKEN aus der Umgebung; fordere den Benutzer dafür auf und übergib es inline.

---

Automatisierungsgrenze

Schritt	Wer führt es aus
CI-Dateien, Dockerfile, Metadaten, Code-Fixes	Agent
Artefakte bauen, Frisch-Installations-Verifizierung	Agent
Registry veröffentlichen (PyPI/npm)	Agent, mit einem vom Benutzer bereitgestellten Token
Glama-Browser-Einreichung	Benutzer (OAuth)
awesome/anderen PR erstellen	Agent
Posten auf Plattformen	Benutzer

Erfinde niemals Anmeldeinformationen; frage explizit nach dem Token und verwende es inline, schreibe es nie in eine Datei.

Echte Narben (aus dem Ausliefern von wheel-hub + zspace-cli)

1. mcp>=1.0 in Extras + neues SDK → frische Installationen stürzen ab. Setze floors.
2. Python 3.9 kann mcp>=2.0 nicht installieren; CI-Matrix muss Basis vs. Extras trennen.
3. YAML-Block-Skalar + inline-Python-Heredoc = defekter Workflow. Verwende eine Skriptdatei.
4. MCP 2.x Server-Objekt hat kein list_tools – verwende @server.tool()-Dekorateure.
5. Glama-Introspection benötigt, dass stdin für einen Moment offen gehalten wird (sleep 1) in Rauchtests.
6. PyPI-Token-Formate: pypi-... echt, UUID = falsch.
7. npm-Typosquatting blockiert wheel-hub neben wheelhub; scoped-Namen funktionieren.
8. .dockerignore fehlt → riesige Images / Geheimnisse im Build-Kontext.