skill.md: Wissen zwischen Index und Werkzeugen
llms.txt liefert Agenten eine Seitenkarte. MCP liefert Werkzeuge. Dazwischen fehlt oft die Ebene: Wie nutzt man das Produkt gut? skill.md (bzw. SKILL.md) ist ein installierbares Markdown-Briefing — Entscheidungstabellen, Grenzen, kanonische Pfade statt Prosa für Menschen, die browsen.
Discovery läuft über `/.well-known/agent-skills/` (Manifest unter index.json, Skill-Datei als SKILL.md) — analog zu etablierten Mustern wie /.well-known/skills/ in der Community. Viele Sites spiegeln zusätzlich `/skill.md` als Alias. Agenten installieren per npx skills add https://docs.kunde.de in Cursor, Claude Code, OpenCode u. a.
Für DACH-Beratungen: skill.md ist Phase-2 nach llms.txt — schnell lieferbar, hoher Hebel gegen falsche Integrationspfade.
Was eine gute Skill-Datei enthält
Minimum: Was das Produkt tut, wann welche Seite oder welches Tool, welche Pfade zählen, wo Grenzen liegen. Kein „Capabilities“-Block („kann Docs suchen“) — das Modell weiß das bereits. Stattdessen produktspezifische Fakten: deprecated v1-API, bevorzugter Auth-Pfad, <CodeGroup>-Konventionen.
Anthropic-Praxis, die sich bewährt: Entscheidungstabellen statt Fließtext, dritte Person in der YAML-Description (wird ins System-Prompt injiziert), explizite Boundaries („read-only Docs“, „kein DNS“, „Support-Kanal für Undokumentiertes“).
Progressive Disclosure: SKILL.md kurz halten (Ziel ~40–500 Zeilen), Tiefe über llms.txt und Volltext-Exporte — nicht alles in einen Skill packen.
Discovery-Pfade und Installation
Standard-Flow: GET /.well-known/agent-skills/index.json → Manifest mit name, description, files → Fetch von /.well-known/agent-skills/SKILL.md → lokale Installation z. B. ~/.cursor/skills/produkt/SKILL.md.
Regeln für name: lowercase, alphanumerisch und Bindestriche, max. 64 Zeichen. description: max. 1024 Zeichen, dritte Person, Trigger-Begriffe für Aktivierung. Test: CLI-Install, dann Produktfrage stellen und beobachten, welche Seiten der Agent liest.
Observe–Refine–Test-Loop: Fehlende Seite → in Dokumentations-Map prominenter; nutzloser Pfad → raus. Skill lebt mit der Docs-Änderung.
/.well-known/agent-skills/index.json
/.well-known/agent-skills/<skill-name>/SKILL.md
/skill.md (Convenience-Alias, optional)curl -s https://example.com/.well-known/agent-skills/index.json | jq .
curl -s https://example.com/.well-known/agent-skills/public-http-api/SKILL.md | headSkills vs. MCP — komplementär, nicht entweder-oder
Skills = Wissen (statisch, einmal geladen, lokal gecacht). MCP = Fähigkeiten (live Tools, JSON-RPC, Auth). Skill sagt „starte bei /guides/query-builder, nicht /api/raw-sql“; MCP-Tool search_docs holt live Snippets.
Pragmatik für Agenturen: skill.md in ~20 Minuten auslieferbar; MCP ist Betrieb (Server, Monitoring, OAuth). Start Skills, MCP wenn Live-Suche, Schreibzugriff oder private Daten nötig — siehe MCP für Docs und Remote MCP Setup.
Standards im Ökosystem: Cloudflare Skills RFC (öffnet in neuem Tab), agentskills.io (öffnet in neuem Tab), Vercel skills CLI (öffnet in neuem Tab).
Implementierung für Kunden-Docs in vier Schritten
1. `/.well-known/agent-skills/index.json` mit einem Skill-Eintrag. 2. `SKILL.md` mit Tabellen, Boundaries, Links zu llms.txt. 3. Optional `/skill.md` als Alias. 4. Install testen, Verhalten iterieren.
In Next.js: statische Dateien unter public/.well-known/agent-skills/ oder Route Handler für dynamische Generierung aus dem Docs-Repo. CI: Manifest-Schema und broken Links prüfen.
Kombination mit Content Negotiation: Skill zeigt Pfade, Negotiation liefert günstiges Markdown pro URL — zusammen deutlich weniger Halluzination als HTML-Scrape.
