SKILL.md-Offenstandard · dreistufiges Laden · Cursor / Claude Code · Remote-Mac-Abnahme
Wer kennt das Problem? Sie nutzen bereits Cursor, Claude Code oder Gemini CLI mit einem Agenten zum Codieren — und muessen bei jeder Session erneut einfuegen, wie deployt, ein PR eroeffnet oder ein Audit laeuft. Der Kontext fuellt sich, die Token-Rechnung nicht weniger. Kernaussage: Verpacken Sie Ablaeufe als Agent Skill (Ordner mit YAML-Frontmatter in SKILL.md); der Agent laedt bei Bedarf, wiederverwendbar ueber Chats hinweg. Enthaelt scripts/ macOS- oder Xcode-Schritte, validieren Sie die Ausgabe auf einem gemieteten VNC-Remote-Mac. Aufbau: Skill vs. Rule → Dateistruktur → dreistufiges Laden → Erstellung & Migration → Best Practices → Oekosystem 2026 → Praxisfaelle → FAQ.
Die Entwicklung von AI-Agenten folgt einer klaren Linie: Chatbot → Aufgabenassistent → Agent mit Fachdomaenen-Know-how. Klassische Prompts scheitern an drei Punkten: komplexe Ablaeufe muessen in jeder Konversation neu beschrieben werden; irrelevante Regeln fuellen das Kontextfenster; Teamwissen laesst sich nicht projektuebergreifend versionieren.
Agent Skills kapseln „Wie mache ich X?“ in wiederverwendbare Module: bei Bedarf geladen, Token-sparend, team- und projektuebergreifend teilbar. Seit Anthropic Ende 2025 den Offenstandard agentskills.io vorangetrieben hat, unterstuetzen Cursor, Claude Code, OpenAI Codex und Gemini CLI dieselbe SKILL.md-Ordnerstruktur.
Kurzdefinition: Ein Skill ist ein Handbuch fuer den AI-Agenten — damit er zur richtigen Zeit das Richtige tut, statt jedes Mal von null zu schlussfolgern.
Wiederholungsarbeit: Deploy-, Test- und PR-Beschreibungen als Prompt kosten oft 2k–8k Token pro Durchlauf.
Kontextverschmutzung: 500 Zeilen Konventionen in Rules — jede Dateibearbeitung traegt das gesamte Paket mit.
Nicht versionierbar: Muendliche Absprachen ohne PR-Review; Onboarding per kopiertem Chatverlauf.
Plattformbruch: Derselbe Deploy-Workflow in Cursor und Claude Code doppelt pflegen — mit dem Skill-Standard teilen Sie per Git.
| Dimension | Rule (Regel) | Skill (Faehigkeit) |
|---|---|---|
| Ladezeitpunkt | Immer geladen | Bei Bedarf / bei Relevanz |
| Einsatz | Dauerhafte Konventionen (Naming, Stil) | Komplexe Workflows (Deploy, Audit) |
| Kontext | Fester Overhead | Dynamisch, effizient |
| Ausloeser | Automatisch im System-Prompt | Agent-Routing + /skill-name |
| Analogie | Onboarding-Handzettel | Fachliches Runbook |
Was Skills zusaetzlich koennen: eigene /-Befehle (z. B. /deploy), mehrstufige Workflows, Domänenwissen, eingebettete Bash-/Python-/Node-Skripte sowie Anbindung an Hooks und MCP. Unser Artikel zum OpenClaw-Skill-Marktplatz behandelt produktinterne Plugins; hier geht es um das editoruebergreifende Skill-Dateiformat — aehnliche Idee, andere Oekosysteme.
Standardverzeichnis (Ordnername = Skill-Name):
.cursor/skills/
└── deploy-app/
├── SKILL.md # Pflicht
├── scripts/ # optional: ausfuehrbare Skripte
│ ├── deploy.sh
│ └── validate.py
├── references/ # optional: Referenzdocs bei Bedarf
└── assets/ # optional: Vorlagen und statische DateienKompatible Pfade: .agents/skills/ (Claude Code, Codex, Gemini CLI), ~/.cursor/skills/ (global pro Nutzer), ~/.agents/skills/ (global cross-tool).
--- name: deploy-app description: >- Wenn der Nutzer eine App nach staging oder production deployen will. Schluesselwoerter: Deploy, Release, Go-Live, Umgebungswechsel. paths: - "apps/web/**" disable-model-invocation: false --- # App deployen ## Schritte 1. `scripts/validate.py` ausfuehren — Umgebungsvariablen pruefen 2. `scripts/deploy.sh <environment>` starten 3. Health-Check-Endpoint auf HTTP 200 verifizieren
| Feld | Pflicht | Bedeutung |
|---|---|---|
| name | Ja | Kleinbuchstaben + Bindestriche, identisch zum Ordnernamen |
| description | Ja | Routing-Schluessel: Trigger-Bedingungen, keine Zusammenfassung |
| paths | Nein | Glob begrenzt gueltige Dateipfade |
| disable-model-invocation | Nein | true = nur manuell via /skill-name |
Agent Skills nutzen Progressive Disclosure — in offizieller Doku und auf agentskills.io in drei Phasen beschrieben:
Entdeckung (Session-Start): Nur name + description jedes Skills — Relevanzpruefung.
Aktivierung (bei Match): Vollstaendiger SKILL.md-Text wird gelesen und ausgefuehrt.
On-demand (waehrend Ausfuehrung): references/ bei Bedarf; bei scripts/ nur die Skript-Ausgabe im Kontext, nicht der Quelltext.
Ausloeser: automatisch (Agent entscheidet, Standard); manuell /skill-name; mit Kontext @skill-name. Bei riskanten Operationen disable-model-invocation: true setzen und menschliche Bestaetigung vor dem Laden erzwingen.
Zahl aus der Community: Anfang 2026 existieren ueber 31.000 Skills. Waeren alle als Rules eingebunden, koennte der Kontext pro Chat um den Faktor 10+ wachsen — progressive disclosure bedeutet: der Agent „weiss von vielen Handbuechern, oeffnet aber nur das aktuelle“.
Schnellster Weg: In Cursor Agent /create-skill eingeben, Skill beschreiben — Agent erzeugt Ordner und SKILL.md.
Manuell: Unter .cursor/skills/ihr-skill-name/ eine SKILL.md mit Frontmatter und Schritten anlegen.
Skripte optional: Wiederholbare Befehle nach scripts/, im Text per relativem Pfad referenzieren.
Erkennung pruefen: Cursor Settings → Rules, oder Agent-Session neu starten — Skill in der Liste?
Migration: Ab Cursor 2.4+ /migrate-to-skills wandelt dynamic rules und Slash-Commands in Skill-Ordner um.
Entwickler unter Windows schreiben Skills in Cursor; enthaelt scripts/ bash, xcodebuild oder notarytool, ist lokale Ausfuehrung unmoeglich. Empfohlener Ablauf: Git-Sync auf gemieteten Remote-Mac → VNC mit Cursor oder Terminal → Skill ausloesen → Exit-Code und Logs pruefen. Schluesselbund, Notarisierung und TCC-Schritte erfordern VNC — siehe unsere TCC-Berechtigungs-Checkliste.
① description ist Routing, nicht Abstract. Falsch: „Dieser Skill enthaelt Deploy-Anweisungen.“ Richtig: „Wenn der Nutzer Deploy, Go-Live oder staging/production erwaehnt, anwenden.“
② Progressive disclosure: SKILL.md unter 500 Zeilen halten; Details in references/; Ausfuehrungslogik in scripts/.
③ Single responsibility: Ein Skill, ein Domänengebiet — „Deploy + Security-Audit + Tests schreiben“ gehoert in drei Skills.
④ Begruendung statt nur Befehl: „Vor Deploy validate.py, damit fehlende Env-Vars keinen Startabbruch verursachen“ — nicht nur „validate.py ausfuehren“.
⑤ Gather → Act → Verify: Information sammeln, handeln, verifizieren — der Agent kann bei Abweichungen sinnvoll reagieren.
⑥ Konsistente Terminologie, POSIX-Pfade, klares Fehlerverhalten: Bei Skriptfehler Retry, Rollback oder Abbruch — im Text festlegen.
| Kategorie | Beispiele | Zweck |
|---|---|---|
| Entwicklerproduktivitaet | Prompt Lookup, Skill Installer, Ralph Coding Loop | Bessere Prompts, Skill-Installation, TDD-Autonomie |
| Frontend / Web | React Best Practices, Web Design Audit, Next.js Cache Optimizer | Performance- und A11y-Audits (u. a. Vercel) |
| Workflow | PR Skill, TDD Skill, Skill Writer | Commit → Push → PR, Test-Driven, Meta-Skills |
| Kreativ | Remotion Video Editor | Video per React-Beschreibung schneiden |
Oekosystem 2026: agentskills.io als plattformuebergreifende Basis; Cursor Marketplace fuer Rules+Skills+MCP-Bundles; in Monorepos verschachtelte Pfade wie .cursor/skills/shipping/deploy-staging/SKILL.md fuer Scope-Isolation.
Verhaeltnis zu MCP: MCP verbindet externe APIs (DB, Browser, GitHub). Skills definieren wann und in welcher Reihenfolge Tools genutzt werden. Ein PR-Skill kann git status, dann GitHub-MCP aufrufen — komplementaer, nicht ersetzend.
Szenario: Jede Freigabe = Commit → Push → PR → Beschreibung. Skill: Aenderungen committen, Branch pushen, gh pr create, Template ausfuellen — ein /pr fuer alles.
Szenario: Code aendern bis Tests gruen. Skill: Tests laufen → bei Fehler Agent patcht → wiederholen. Hooks koennen bei CI-Fehlschlag den Agenten wecken.
Szenario: Windows-Entwickler pflegt Skill mit xcodebuild archive und notarytool submit. Lokal nur Markdown editierbar; echte Abnahme auf VNCMac Remote Mac: VNC → Skill triggern → Agent fuehrt Skripte aus → Schluesselbund „Immer erlauben“ per GUI. Entspricht unserer Notarytool-Stapler-Checkliste — SSH allein reicht nicht.
| Abnahmepunkt | Lokal Windows | Remote Mac + VNC |
|---|---|---|
| SKILL.md bearbeiten | Ja | Ja |
| Bash-Deploy-Skripte | WSL teilweise | Volle macOS-Umgebung |
| xcodebuild / Notarisierung | Nein | Pflicht |
| Schluesselbund / TCC-Dialoge | Nein | VNC-GUI-Klick |
Skills sind strukturierte Anleitung, kein Zwang. Das Modell entscheidet weiterhin selbst; klare description und Schritte erhoehen Konsistenz. Community-Skills vor Installation in scripts/ lesen.
Mit echten Aufgaben testen; Trigger-Woerter in description pruefen. Falls no auto-load: manuell /skill-name. Synonyme im ersten Absatz der description ergaenzen.
Allgemeine Workflows (Commit, Tests) nach ~/.cursor/skills/; repo-spezifische Pfade und interne APIs in .cursor/skills/ im Projekt und per Git committen.
Aehnliche Idee (wiederverwendbare Module), aber OpenClaw nutzt ClawHub und Gateway-Plugins; Cursor Agent Skills folgen SKILL.md und agentskills.io. Beides kann parallel existieren: OpenClaw 7×24 Gateway, Cursor Skills fuer Coding-Workflows.
Agent Skills machen aus „nur alte Hasen wissen das“ versionierbare SKILL.md-Runbooks mit Review und Cross-Platform-Sharing. description = Trigger, Body = Gather-Act-Verify, Skripte in scripts/ — dann wird der Agent vom Wiederhol-Lehrer zum Handbuch-Nutzer.
Realistische Grenze: Skills mit macOS-Build, Notarisierung und Schluesselbund lassen sich unter Windows schreiben, nicht validieren; reines SSH auf Remote Mac reicht fuer Systemdialoge nicht. Ein eigenes Mac mini lohnt bei dauerhaftem 7×24-Agent-Betrieb; wer monatlich iOS/macOS-Skripte abnimmt, trennt Schreiben auf der Hauptmaschine und Ausfuehren per VNC-Remote-Mac — oft guenstiger als Hardware fuer gelegentliche Beduerfnisse.
Skills leben von Wiederverwendung — Wiederverwendung braucht eine laufende Umgebung. Oeffnen Sie die Remote-Mac-Tarife und reservieren Sie einen VNC-Knoten fuer macOS-Skill-Abnahme.