2026 Cursor Agent Skills Komplettanleitung: SKILL.md-Format, dreistufiges Laden und Mac-Cloud 7×24 in der Praxis (mit Entscheidungsmatrix)

1. Drei Schmerzpunkte: warum Agent Skills noetig sind

Teams, die Cursor oder Claude Code produktiv einsetzen, stossen im Sommer 2026 auf dieselben drei Engpaesse — unabhaengig davon, ob sie iOS-Apps, Backend-Services oder Agent-Gateways wie OpenClaw und Hermes betreiben. Der erste Engpass ist Wiederverwendbarkeit: Deploy-Runbooks, Security-Audit-Checklisten und PR-Vorlagen leben in Slack-Threads oder persoenlichen Chat-Verlaeufen. Jeder neue Kollege kopiert Prompt-Fragmente, Variationen entstehen, und niemand weiss, welche Version «aktuell» ist. Der zweite Engpass ist Kontextverschwendung: Wer ganze Styleguides in .cursorrules packt, belegt bei jedem Session-Start Token — auch wenn der Agent gerade nur eine Diff in einer Swift-Datei lesen soll. Rules sind sinnvoll fuer Dauerprinzipien, aber ungeeignet fuer seltene, mehrstufige Workflows. Der dritte Engpass ist Hardware-Realitaet: Selbst perfekt geschriebene Skills helfen wenig, wenn das Gateway nach dem Zuklappen des MacBooks offline ist oder auf einem Linux-VPS laeuft, der weder Xcode noch launchd-Semantik nativ bietet — siehe unseren Beitrag zu Hermes Agent und dreischichtigem Gedaechtnis.

1. Komplexe Prompts lassen sich nicht versionieren. Deployment-Checklisten, Audit-Protokolle und PR-Templates muessen jedes Mal eingefuegt werden; Teamwissen bleibt in privaten Chats gefangen, Onboarding wird teuer.
2. Der Kontext fuellt sich mit irrelevanten Regeln. Ein dickes .cursorrules-File belegt dauerhaft Token; beim eigentlichen Codieren uebersieht der Agent oft die relevanten Datei-Diffs.
3. Skills und Hardware passen nicht zusammen. OpenClaw- oder Hermes-Skills brauchen ein 7×24-Gateway; Laptops trennen beim Zuklappen, guenstige Linux-VPS haben kein natives macOS — Skills «existieren», laufen aber nicht zuverlaessig.

Kurz gesagt: Ein Skill ist ein Runbook fuer den AI-Agenten, das zum richtigen Zeitpunkt geladen wird, damit der Agent das Richtige tut — nicht alles auf einmal im Prompt.

2. Was ist ein Skill? Kernvergleich mit Rule

Cursor unterscheidet seit Version 2.4 zwischen Rules (Regeln) und Skills (Faehigkeiten). Rules sind wie das Employee Handbook: immer da, wenn die Schicht beginnt. Skills sind wie das Runbook fuer einen Release-Freitag: nur relevant, wenn jemand «deployen» sagt oder eine CI-Pipeline rot wird. Diese Unterscheidung ist kein Marketing-Label — sie steuert direkt, wie viele Token Ihr Agent verbraucht und wie deterministisch wiederholbare Workflows aussehen.

Skills koennen Slash-Commands und Shell-Skripte kapseln und mit MCP-Servern zusammenspielen: MCP liefert die Werkzeuge (API-Aufrufe, Datenbank, Browser), der Skill definiert Reihenfolge, Abbruchbedingungen und menschliche Freigabepunkte. Wer beides verwechselt, baut entweder zu viele Rules (langsam, teuer) oder zu viele Skills ohne klare Trigger (werden nie geladen).

3. SKILL.md-Dateistruktur und Format

Der Offstandard auf agentskills.io ist bewusst minimal und portabel — dieselbe Datei funktioniert in Cursor, Claude Code, Codex und Gemini CLI. Die Verzeichnisstruktur folgt einem erkennbaren Muster:

Minimales SKILL.md-Beispiel:

description ist der Routing-Schluessel, keine Zusammenfassung. Falsch: «Dieser Skill enthaelt Deploy-Anweisungen.» Richtig: klar formulieren, wann geladen wird — Triggerwoerter, Szenario, optional paths-Glob. Gute descriptions lesen sich wie Suchanfragen Ihrer Entwickler: «PR review nach Conventional Commits», «Staging deploy nach gruenem CI», «Secrets rotieren vor Release».

4. Dreistufiges progressives Laden

Agent Skills nutzen ein dreistufiges Lademodell, damit Hunderte Skills im Repository moeglich sind, ohne den Kontext zu sprengen. Stufe eins ist Discovery: Der Agent sieht nur name und description aller registrierten Skills und entscheidet anhand der Nutzeranfrage, ob ein Skill relevant sein koennte. Stufe zwei ist Activation: Bei Treffer wird die vollstaendige SKILL.md mit Schrittfolge, Guardrails und Verweisen auf scripts geladen. Stufe drei ist On demand: Dateien unter references/ werden erst bei Bedarf gezogen; scripts/ werden ausgefuehrt und nur die stdout/stderr-Ausgabe zurueckgegeben — der Quellcode selbst verbraucht keine Body-Token.

Standardpfade: .cursor/skills/ (projektbezogen, Git-versioniert), .agents/skills/ (alternativer Pfad in manchen CLIs), ~/.cursor/skills/ (persoenlich, maschinenweit). Cursor 2.4+ bietet /create-skill fuer interaktives Anlegen und /migrate-to-skills zum Ueberfuehren alter Rules und Slash-Commands. Teams sollten projektbezogene Skills committen und persoenliche Experimente in ~/.cursor/skills/ halten, um Review-Drift zu vermeiden.

5. Entscheidungsmatrix: Skill fertig — wo laeuft er?

Ein Skill ist nur so gut wie die Maschine, die sein Gateway traegt. Die folgende Matrix fasst die drei gaengigen Optionen fuer Entwickler- und Agent-Teams im Juni 2026 zusammen:

agentskills.io ist plattformuebergreifend; produktive Teams versionieren Skills in Git und validieren Gateways auf Mac-Cloud-Hardware — analog zu unserem OpenClaw skill-browser-Deployment. Wer nur Linux mietet, verliert Xcode-notarization, Metal-Inferenz und die launchd-Plist-Semantik, die in den meisten Agent-Dokumentationen vorausgesetzt wird.

6. Fuenf-Schritte-Runbook: vom Nullpunkt zum produktionsreifen Skill

Schritt 1 — Triggerszenario definieren

Waehlen Sie eine haeufig wiederholte Aufgabe — z. B. «Staging deploy nach gruenem CI» oder «Security-Review vor Merge». Schreiben Sie echte Nutzerformulierungen und optional Datei-Globs in description. Testen Sie mental: Wuerde ein Kollege genau diese Woerter sagen?

Schritt 2 — SKILL.md erstellen

mkdir -p .cursor/skills/my-skill; name muss dem Verzeichnisnamen entsprechen. Frontmatter validieren, Schritte nummerieren, Abbruchbedingungen explizit machen.

Schritt 3 — references und scripts trennen

Langtexte, Compliance-Passagen und API-Beispiele nach references/; wiederholbare Checks nach scripts/. Im Skill-Body kurz erklaeren, warum ein Schritt noetig ist — das hilft dem Modell bei Abweichungen.

Schritt 4 — Smoke-Test

Automatischen Trigger mit realistischer Nutzeranfrage pruefen; manuell /my-skill aufrufen; Verhalten bei disable-model-invocation: true verstehen (Skill wird angezeigt, Ausfuehrung nur auf Nutzerwunsch).

Schritt 5 — Mac cloud deployen

rsync des skills-Verzeichnisses auf einen VPSMAC-Knoten; Gateway per launchd dauerhaft betreiben — Details im Artikel Mac-Cloud Agent-Automatisierungsknoten.

7. Zitierfaehige Technik-Fakten (2026)

• Offstandard: Agent-Skills-Spezifikation auf agentskills.io; Pflichtfelder name + description; optional paths, disable-model-invocation, metadata.
• Cursor-Builtin-Befehle: /create-skill interaktiv; /migrate-to-skills (2.4+) fuer Legacy-Rules und Slash-Commands.
• Sicherheitsgrenze: Drittanbieter-Skills von ClawHub vor exec- und Netzwerkrechten auditieren — Checkliste in OpenClaw Production Hardening.

8. FAQ

Skill vs MCP? MCP verbindet APIs und externe Tools; Skills orchestrieren mehrstufige Ablaeufe. Wird der Agent starr? Nein — das Modell entscheidet weiterhin innerhalb der Skill-Grenzen. Wo ablegen? Allgemeine Skills in ~/.cursor/skills/, projektbezogene in .cursor/skills/ und in Git committen.

9. Fazit: Skill loest «wie», Mac cloud loest «dauerhaft»

Prompt-Stapel und ueberladene Rules verschwenden Token und lassen sich schlecht reviewen; Laptops trennen, Linux-VPS fehlt die Apple-Toolchain. Skills kapseln Prozesse in versionierbare SKILL.md-Dateien; eine gemietete VPSMAC Mac cloud liefert Bare-Metal-macOS und launchd 7×24, damit Gateway und Skills wirklich durchlaufen — nicht nur auf dem Papier existieren.