DataShrimp/skills

Quellherkunft

• Offizielles Repository: anthropics/skills — mcp-builder/SKILL.md
• Zusätzliche Skillentwicklungs-Referenzen enthalten:
  • Claude Code Skills — Dynamische Kontextinjektion (!Befehl``)
  • OpenAI ChatGPT & Codex Skills (agents/openai.yaml)
  • Agent Skills Specification — Script Harness (agentskills.io)

---

Teil 1: Anthropic Official mcp-builder/SKILL.md (3-stufiges Beispiel für progressive Offenlegung)

Übersicht

Erstellen Sie MCP-Server (Model Context Protocol), die LLMs die Interaktion mit externen Diensten über durchdachte Tools ermöglichen. Die Qualität eines MCP-Servers wird daran gemessen, wie gut er LLMs in die Lage versetzt, reale Aufgaben zu bewältigen.

---

Prozess

🚀 Hochrangiger Arbeitsablauf

Die Erstellung eines hochwertigen MCP-Servers umfasst vier Hauptphasen:

Phase 1: Gründliche Recherche und Planung

1.1 Modernes MCP-Design verstehen

API-Abdeckung vs. Workflow-Tools: Bringen Sie eine umfassende Abdeckung der API-Endpunkte mit spezialisierten Workflow-Tools in Einklang. Workflow-Tools können für bestimmte Aufgaben bequemer sein, während eine umfassende Abdeckung den Agenten Flexibilität bei der Zusammenstellung von Operationen bietet. Die Leistung variiert je nach Client – manche Clients profitieren von Codeausführung, die grundlegende Tools kombiniert, während andere besser mit übergeordneten Workflows arbeiten. Wenn Sie unsicher sind, priorisieren Sie eine umfassende API-Abdeckung.

Tool-Benennung und Auffindbarkeit: Klare, beschreibende Toolnamen helfen Agenten, die richtigen Tools schnell zu finden. Verwenden Sie konsistente Präfixe (z.B. github_create_issue, github_list_repos) und handlungsorientierte Benennung.

Kontextmanagement: Agenten profitieren von prägnanten Toolbeschreibungen und der Möglichkeit, Ergebnisse zu filtern/zu paginieren. Entwerfen Sie Tools, die fokussierte, relevante Daten zurückgeben. Einige Clients unterstützen die Codeausführung, was Agenten helfen kann, Daten effizient zu filtern und zu verarbeiten.

Aktionsorientierte Fehlermeldungen: Fehlermeldungen sollten Agenten mit konkreten Vorschlägen und nächsten Schritten zur Lösung führen.

1.2 MCP-Protokoll-Dokumentation studieren

Navigieren Sie durch die MCP-Spezifikation: Beginnen Sie mit der Sitemap, um relevante Seiten zu finden: https://modelcontextprotocol.io/sitemap.xml Rufen Sie dann bestimmte Seiten mit dem Suffix .md für das Markdown-Format ab (z.B. https://modelcontextprotocol.io/specification/draft.md).

Wichtige Seiten zur Überprüfung:

• Überblick und Architektur der Spezifikation
• Transportmechanismen (streamable HTTP, stdio)
• Tool-, Ressourcen- und Prompt-Definitionen

1.3 Framework-Dokumentation studieren

Empfohlener Stack:

• Sprache: TypeScript (hochwertige SDK-Unterstützung und gute Kompatibilität in vielen Ausführungsumgebungen wie z.B. MCPB. Zudem sind KI-Modelle gut darin, TypeScript-Code zu generieren, was von der breiten Nutzung, statischen Typisierung und guten Linting-Tools profitiert)
• Transport: Streamable HTTP für entfernte Server, unter Verwendung von zustandslosem JSON (einfacher zu skalieren und zu warten, im Gegensatz zu zustandsbehafteten Sitzungen und Streaming-Antworten). stdio für lokale Server.

Framework-Dokumentation laden:

• MCP Best Practices: 📋 Best Practices anzeigen - Kernrichtlinien für alle MCP-Server
• Für TypeScript (empfohlen): ⚡ TypeScript-Anleitung - TypeScript-Muster und -Beispiele
• Für Python: 🐍 Python-Anleitung - Python/FastMCP-Muster und -Beispiele

1.4 Planen Sie Ihre Implementierung

Verstehen Sie die API: Überprüfen Sie die API-Dokumentation des Dienstes, um wichtige Endpunkte, Authentifizierungsanforderungen und Datenmodelle zu identifizieren. Verwenden Sie bei Bedarf Websuche und Web-Fetch.

Tool-Auswahl: Priorisieren Sie eine umfassende API-Abdeckung. Listen Sie die zu implementierenden Endpunkte auf, beginnend mit den häufigsten Operationen.

---

Phase 2: Implementierung

2.1 Projektstruktur einrichten

Siehe sprachspezifische Anleitungen zur Projekteinrichtung:

• ⚡ TypeScript-Anleitung - Projektstruktur, package.json, tsconfig.json
• 🐍 Python-Anleitung - Modulorganisation, Abhängigkeiten

2.2 Kerninfrastruktur implementieren

Erstellen Sie gemeinsam genutzte Hilfsprogramme:

• API-Client mit Authentifizierung
• Hilfsprogramme zur Fehlerbehandlung
• Antwortformatierung (JSON und Markdown)
• Paginierungsunterstützung

2.3 Tools implementieren

Für jedes Tool:

Eingabeschema:

• Verwenden Sie Zod (TypeScript) oder Pydantic (Python)
• Fügen Sie Einschränkungen und klare Beschreibungen hinzu
• Fügen Sie Beispiele in Feldbeschreibungen ein

Ausgabeschema:

• Definieren Sie outputSchema wo möglich für strukturierte Daten
• Verwenden Sie structuredContent in Tool-Antworten (TypeScript SDK-Funktion)
• Hilft Clients, Tool-Ausgaben zu verstehen und zu verarbeiten

Tool-Beschreibung:

• Prägnante Zusammenfassung der Funktionalität
• Parameterbeschreibungen
• Rückgabewertschema

Implementierung:

• Async/await für I/O-Operationen
• Ordnungsgemäße Fehlerbehandlung mit umsetzbaren Meldungen
• Unterstützung der Paginierung, wo anwendbar
• Rückgabe von sowohl Textinhalt als auch strukturierten Daten bei Verwendung moderner SDKs

Annotationen:

• readOnlyHint: true/false
• destructiveHint: true/false
• idempotentHint: true/false
• openWorldHint: true/false

---

Phase 3: Überprüfung und Test

3.1 Code-Qualität

Überprüfen auf:

• Keine duplizierten Code (DRY-Prinzip)
• Konsistente Fehlerbehandlung
• Vollständige Typabdeckung
• Klare Tool-Beschreibungen

3.2 Build und Test

TypeScript:

• Führen Sie npm run build aus, um die Kompilierung zu überprüfen
• Testen Sie mit dem MCP Inspector: npx @modelcontextprotocol/inspector

Python:

• Syntax überprüfen: python -m py_compile your_server.py
• Testen Sie mit dem MCP Inspector

Siehe sprachspezifische Anleitungen für detaillierte Testansätze und Qualitätschecklisten.

---

Phase 4: Evaluierungen erstellen

Erstellen Sie nach der Implementierung Ihres MCP-Servers umfassende Evaluierungen, um seine Effektivität zu testen.

Laden Sie die ✅ Evaluierungsanleitung für vollständige Evaluierungsrichtlinien.

4.1 Zweck der Evaluierung verstehen

Verwenden Sie Evaluierungen, um zu testen, ob LLMs Ihren MCP-Server effektiv nutzen können, um realistische, komplexe Fragen zu beantworten.

4.2 10 Evaluierungsfragen erstellen

Um effektive Evaluierungen zu erstellen, befolgen Sie den in der Evaluierungsanleitung beschriebenen Prozess:

1. Tool-Inspektion: Verfügbare Tools auflisten und ihre Fähigkeiten verstehen
2. Inhaltserkundung: READ-ONLY-Operationen verwenden, um verfügbare Daten zu erkunden
3. Fragenerstellung: 10 komplexe, realistische Fragen erstellen
4. Antwortüberprüfung: Jede Frage selbst lösen, um Antworten zu überprüfen

4.3 Evaluierungsanforderungen

Stellen Sie sicher, dass jede Frage ist:

• Unabhängig: Nicht von anderen Fragen abhängig
• Nur lesend: Nur nicht-destruktive Operationen erforderlich
• Komplex: Mehrere Tool-Aufrufe und tiefgehende Erkundung erforderlich
• Realistisch: Basierend auf realen Anwendungsfällen, die Menschen wichtig finden
• Überprüfbar: Einzelne, klare Antwort, die durch Zeichenfolgenvergleich überprüft werden kann
• Stabil: Antwort ändert sich im Laufe der Zeit nicht

4.4 Ausgabeformat

Erstellen Sie eine XML-Datei mit dieser Struktur:

<evaluation>
  <qa_pair>
    <question>Finden Sie Diskussionen über KI-Modellveröffentlichungen mit Tier-Codenamen. Ein Modell benötigte eine spezifische Sicherheitsbezeichnung, die das Format ASL-X verwendet. Welche Nummer X wurde für das nach einer gefleckten Wildkatze benannte Modell ermittelt?</question>
    <answer>3</answer>
  </qa_pair>
<!-- Weitere qa_pairs... -->
</evaluation>

---

Referenzdateien

📚 Dokumentationsbibliothek

Laden Sie diese Ressourcen nach Bedarf während der Entwicklung:

Kern-MCP-Dokumentation (zuerst laden)

• MCP-Protokoll: Beginnen Sie mit der Sitemap unter https://modelcontextprotocol.io/sitemap.xml, rufen Sie dann bestimmte Seiten mit dem Suffix .md ab
• 📋 MCP Best Practices - Universelle MCP-Richtlinien einschließlich:
  • Server- und Tool-Namenskonventionen
  • Richtlinien zum Antwortformat (JSON vs. Markdown)
  • Paginierungs-Best Practices
  • Transportauswahl (streamable HTTP vs. stdio)
  • Sicherheits- und Fehlerbehandlungsstandards

SDK-Dokumentation (während Phase 1/2 laden)

• Python SDK: Abrufen von https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md
• TypeScript SDK: Abrufen von https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md

Sprachspezifische Implementierungsanleitungen (während Phase 2 laden)

• 🐍 Python Implementierungsanleitung
• ⚡ TypeScript Implementierungsanleitung

Evaluierungsanleitung (während Phase 4 laden)

• ✅ Evaluierungsanleitung

---

Teil 2: Claude Code Dynamische Kontextinjektion (!Befehl``) Skill-Beispiel

• Quelle: Claude Code Skills Dokumentation

---
name: pr-summary
description: Änderungen in einem Pull Request zusammenfassen. Verwenden Sie dies, wenn der Benutzer darum bittet, den aktuellen PR oder Branch-Diff zu überprüfen, zusammenzufassen oder zu prüfen.
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---

## Pull-Request-Kontext
- PR-Diff: !`gh pr diff`
- PR-Kommentare: !`gh pr view --comments`
- Geänderte Dateien: !`gh pr diff --name-only`

## Ihre Aufgabe
Fassen Sie diesen Pull Request mit konkreten, dateibezogenen Risiken, bahnbrechenden Änderungen und Überprüfungsschritten zusammen...

---

Teil 3: OpenAI Codex / ChatGPT agents/openai.yaml Sidecar-Schema

• Quelle: OpenAI Build Skills Dokumentation

interface:
  display_name: "Selbstentwickelnder Meta-Prompt- und Rollenarchitekt"
  short_description: „Erstellen, bewerten und passen Sie Prompts, Skills und Agentenrollen über Tools hinweg an"
  icon_small: "./assets/icon-small.svg"
  icon_large: "./assets/icon-large.png"
  brand_color: "#2563EB"
  default_prompt: „Entwerfen oder optimieren Sie eine Prompt-, Skill- oder Agentenrollendefinition mit einer Bewertungstabelle."

policy:
  allow_implicit_invocation: true

dependencies:
  tools:
    - type: "mcp"
      value: "git"
      description: „Git MCP-Server für Repository-Inspektion"

---

Teil 4: Agent Skills PEP 723 In sich geschlossenes Script-Harness-Beispiel

• Quelle: Agent Skills — Verwenden von Skripten (agentskills.io)

# /// script
# dependencies = [
#   "pydantic>=2.0",
# ]
# requires-python = ">=3.10"
# ///
"""In sich geschlossenes, nicht-interaktives CLI-Skript, das für den Aufruf von Agent Skills via `uv run` konzipiert ist."""

import argparse
import json
import sys


def main() -> int:
    parser = argparse.ArgumentParser(
        description="Überprüft Skill- oder Rollen-Frontmatter und Token-Budget ohne interaktive Eingabeaufforderungen."
    )
    parser.add_argument("--input", required=True, help="Pfad zur Ziel-Markdown-Datei")
    parser.add_argument("--max-chars", type=int, default=12000, help="Zeichenbudget-Obergrenze")
    parser.add_argument("--dry-run", action="store_true", help="Prüfungen in der Vorschau anzeigen, ohne zu schreiben")
    args = parser.parse_args()

    try:
        with open(args.input, "r", encoding="utf-8") as f:
            text = f.read()
    except FileNotFoundError:
        sys.stderr.write(
            f"Fehler: Datei '{args.input}' nicht gefunden. Übergeben Sie einen gültigen Pfad via --input <Pfad>.\n"
        )
        return 1

    char_count = len(text)
    passed = char_count <= args.max_chars
    result = {
        "file": args.input,
        "char_count": char_count,
        "max_chars": args.max_chars,
        "passed": passed,
        "remediation": None if passed else f"Kürzen Sie {char_count - args.max_chars} Zeichen oder verschieben Sie Details nach references/.",
    }
    sys.stdout.write(json.dumps(result, ensure_ascii=False, indent=2) + "\n")
    return 0 if passed else 2


if __name__ == "__main__":
    sys.exit(main())