# Einen Claude-Skill für Shager bauen: SKILL.md, Ordnerstruktur und die Regeln, die Posten auf vielen Konten wiederholbar machen _2026-09-30 · Shager-Distribution als Claude Agent Skill verpacken: Frontmatter, das zuverlässig auslöst, Referenzdateien, ein REST-Hilfsskript und der richtige Speicherort._ Ein Claude-Skill für Shager ist ein Ordner mit einer Datei `SKILL.md`, deren YAML-Frontmatter einen `name` und eine `description` enthält, gefolgt von Anweisungen, die Claude sagen, wie die Distribution über die Tools von Shager läuft: welche Aufrufe, in welcher Reihenfolge und welche Regeln nie gebogen werden. Leg ihn für dich selbst unter `~/.claude/skills/shager-distribution/` ab oder für dein Team in einem Repository unter `.claude/skills/shager-distribution/`. Claude Code lädt ihn, wenn eine Anfrage passt oder wenn du `/shager-distribution` eintippst. Die Verbindung zu Shager ist der einfache Teil. Im Skill steckt das Urteilsvermögen: Textvariation, Tracking-Links, standardmäßig Entwürfe und was zu tun ist, wenn die API Nein sagt. ## Warum ein Skill statt eines langen Prompts? Weil der Prompt, den du am Dienstag perfektionierst, am Donnerstag weg ist – und die Kollegin, die ihn nicht gesehen hat, schreibt einen schlechteren. Anthropics [Überblick zu Agent Skills](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) beschreibt Skills als Ressourcen im Dateisystem, die bei Bedarf geladen werden. Bis der Skill auslöst, liegen nur Name und Beschreibung im Kontext. Dann wird `SKILL.md` gelesen, und weitere Dateien, auf die sie verweist, erst dann, wenn sie gebraucht werden. Du kannst dir also ausführliche Anweisungen leisten, ohne in jeder Unterhaltung dafür zu bezahlen. Gerade bei Shager bleibt das Vorgehen stabil, während sich die Inhalte jede Woche ändern. Genau das ist das Profil eines guten Skills. ## Welche Regeln gelten für das Frontmatter von SKILL.md? Laut derselben Übersichtsseite sind `name` und `description` Pflicht. `name` hat höchstens 64 Zeichen, nur Kleinbuchstaben, Ziffern und Bindestriche, und darf die reservierten Wörter „anthropic“ oder „claude“ nicht enthalten. `description` darf nicht leer sein, hat höchstens 1.024 Zeichen und muss sagen, was der Skill tut und wann er eingesetzt wird – denn damit gleicht Claude Anfragen ab. Claude Code ergänzt optionale Felder, dokumentiert unter [Use Skills in Claude Code](https://code.claude.com/docs/en/skills): `allowed-tools` für Tools, die Claude ohne Nachfrage verwenden darf, solange der Skill aktiv ist, `disable-model-invocation`, um ihn nur manuell aufrufbar zu machen, `argument-hint` für die Autovervollständigung und weitere. Der Ordnername oder, falls gesetzt, `name` wird zum Slash-Befehl. ## Wie sollte der Ordner aussehen? ```text shager-distribution/ SKILL.md reference/ tools.md errors.md scripts/ shager.py ``` `SKILL.md` enthält das Vorgehen. `reference/tools.md` enthält die Details auf Feldebene für `create_post` und `upload_media_from_url` und wird nur gelesen, wenn Claude sie braucht. `scripts/shager.py` ist ein optionaler REST-Fallback für Umgebungen ohne MCP-Server. Die Dokumentation von Claude Code empfiehlt, `SKILL.md` unter 500 Zeilen zu halten und Details in separate Dateien auszulagern – genau diese Aufteilung. Shager veröffentlicht außerdem eine gepflegte Skill-Datei unter https://shager.ai/skills/shager/SKILL.md. Sie ist ein guter Ausgangspunkt, den du lesen solltest, bevor du deine eigene schreibst; die Version unten ergänzt agenturspezifische Regeln. ## Die SKILL.md ```markdown --- name: shager-distribution description: Distribute a post or video to many social accounts through Shager (Facebook Pages, Instagram professional accounts, YouTube channels). Use when the user asks to post, schedule, draft or distribute content to client accounts, account groups or "all locations", or asks which account drove clicks. argument-hint: "[workspace] [brief or media URL]" allowed-tools: mcp__shager__whoami mcp__shager__list_workspaces mcp__shager__list_channels mcp__shager__list_groups mcp__shager__get_post mcp__shager__list_posts mcp__shager__get_analytics --- # Shager distribution ## Before anything 1. Call whoami. Note the scopes and whether this is a sandbox. 2. Resolve the workspace by name with list_workspaces. If two match, ask. 3. Call list_channels and list_groups. Only target channels with status ACTIVE. ## Building the post 1. Media: call upload_media_from_url. For vertical video pass width, height and duration_ms so Shager can validate Reels, Shorts and Stories. 2. Captions: write one caption per channel in per_channel. Keep facts, prices and dates identical; vary the opening line, structure and the local detail (city, branch, presenter) taken from the channel name. 3. Links: never paste a raw URL into captions. Pass it as cta_url so each account gets its own short link and UTM tags. Put the call to action in first_comment for Facebook and YouTube. Instagram does not make comment links clickable, so for Instagram channels mention "link in bio". 4. Set campaign to a lowercase slug, e.g. "spring-open-day-2026". 5. Set label to something a human will recognize in the calendar. ## Drafts by default Create the post WITHOUT schedule_at unless the user gave an explicit date and time in this conversation. Show a table of channel, network, format and the first line of each caption, and wait for confirmation. ## Scheduling Only when confirmed: call schedule_post with schedule_at in ISO 8601 with the workspace's UTC offset. If the workspace requires approval, call request_approval instead and return the approval_url to the user. ## When Shager says no Read error.code, do not retry blindly. See reference/errors.md. ## Reporting For "how did it do", call get_analytics for the date range and present clicks by account, highest first, plus the top posts. Field details for create_post: reference/tools.md ``` Ein paar Entscheidungen darin lohnen eine Begründung. Die Liste `allowed-tools` enthält nur lesende Operationen. `create_post`, `schedule_post`, `request_approval` und `cancel_post` fragen in Claude Code weiterhin nach einer Berechtigung, ein Mensch sieht also jeden Schreibvorgang. MCP-Tools heißen `mcp____`; das setzt voraus, dass du den Server wie in [Shager mit Claude Code verbinden](/en/blog/connect-shager-to-claude-code) als `shager` registriert hast. Die Zeile zu Instagram spiegelt wider, wie sich das Netzwerk verhält: Links in Texten und Kommentaren sind dort nicht anklickbar. Der erste Kommentar mit dem Tracking-Link lohnt sich auf Facebook-Seiten und YouTube. „Drafts by default“ wird doppelt durchgesetzt. Einmal in den Anweisungen und noch einmal, indem die Umgebung des Skills einen Schlüssel ohne die Berechtigung `publish` bekommt. Anweisungen leiten, Berechtigungen erzwingen. ## reference/errors.md ```markdown # Shager error codes 401 unauthorized: key missing or malformed. Stop and tell the user. 403 forbidden: key lacks a scope. If scheduling, say a human must schedule or grant publish at app.shager.ai/dashboard/agents. 403 sandbox_unclaimed: show the claim link from signup; nothing else to do. 404 not_found: re-list channels or posts; ids are per workspace. 409 not_scheduled: the post is not scheduled; get_post and report status. 422 rejected: a network rule failed. Quote the message, fix the input (length, format, media), and try once more. 429 rate_limited: wait 60 seconds, then continue. Never loop per account. ``` ## scripts/shager.py: der REST-Fallback Wenn MCP nicht eingerichtet ist, kann der Skill trotzdem über die REST-API arbeiten, die im [OpenAPI-Dokument](https://app.shager.ai/api/v1/openapi.json) beschrieben ist. Ein kleines Hilfsskript verhindert, dass Claude jedes Mal HTTP-Code improvisiert: ```python #!/usr/bin/env python3 """Usage: shager.py METHOD PATH [JSON_BODY] Example: shager.py GET /workspaces shager.py POST /workspaces/WS_ID/posts '{"caption": "..."}'""" import json, os, sys, requests API = "https://app.shager.ai/api/v1" def main(): method, path = sys.argv[1].upper(), sys.argv[2] body = json.loads(sys.argv[3]) if len(sys.argv) > 3 else None r = requests.request( method, f"{API}{path}", headers={"Authorization": f"Bearer {os.environ['SHAGER_API_KEY']}"}, json=body, timeout=90, ) payload = r.json() if not r.ok: e = payload["error"] print(json.dumps({"status": r.status_code, "code": e["code"], "message": e["message"]})) sys.exit(1) print(json.dumps(payload["data"], indent=2)) if __name__ == "__main__": main() ``` Ergänze in `SKILL.md` eine Zeile wie „If the shager MCP tools are unavailable, run scripts/shager.py with the same operation paths“ und liste die Pfade in `reference/tools.md` auf. Die Übersichtsseite weist darauf hin, dass beim Ausführen eines mitgelieferten Skripts nur dessen Ausgabe in den Kontext gelangt, nicht der Code. ## Wo sollte der Skill liegen? | Umgebung | Ort | Erreicht er Shager? | |---|---|---| | Claude Code, persönlich | `~/.claude/skills/shager-distribution/` | Ja, über MCP oder das Skript. Skills dort haben denselben Netzwerkzugriff wie jedes Programm auf deinem Rechner | | Claude Code, Team | `.claude/skills/shager-distribution/`, in ein Repository eingecheckt | Ja, wie oben | | claude.ai | Als ZIP in den Einstellungen unter Features hochgeladen | Der Netzwerkzugriff hängt von Nutzer- und Admin-Einstellungen ab | | Claude API | Über die Skills API hochgeladen | Nein: Skills laufen auf der API ohne Netzwerkzugriff | Die letzte Zeile stammt direkt aus den Laufzeitbeschränkungen auf der Übersichtsseite und überrascht viele. Auf der API nutzt du für den Netzwerkteil den MCP-Server von Shager oder eigene Tool-Aufrufe und beschränkst den Skill auf Anweisungen. Beachte außerdem, dass eigene Skills nicht zwischen den Umgebungen synchronisiert werden: Ein auf claude.ai hochgeladener Skill ist nicht in Claude Code verfügbar. ## Wie testest du ihn? 1. Stell eine Anfrage, die ihn auslösen sollte, ohne ihn zu nennen: „Entwirf den Beitrag zum Tag der offenen Tür diese Woche für alle Standorte von Harbor Fitness.“ Prüfe, ob Claude den Skill liest. 2. Stell eine Anfrage, die ihn nicht auslösen sollte: „Wie lang sollte ein Text für Reels sein?“ Der Skill sollte außen vor bleiben. 3. Führ `/shager-distribution Harbor Fitness https://example.com/clip.mp4` aus und prüfe, ob er bei der Entwurfstabelle anhält. 4. Verwende einen Schlüssel ohne `publish` und bitte ihn, zu planen. Er sollte den 403 erklären, statt in eine Schleife zu geraten. ## FAQ ### Darf der Name des Skills „claude“ enthalten? Nein. Anthropics Regeln für Skills reservieren die Wörter „anthropic“ und „claude“ im Feld `name`. Nimm etwas wie `shager-distribution`; im Titel deiner Doku darf trotzdem stehen, dass es ein Claude-Skill ist. ### Sollte der Skill den API-Schlüssel speichern? Nein. Bewahre den Schlüssel in der Konfiguration des MCP-Clients oder in einer Umgebungsvariablen wie `SHAGER_API_KEY` auf. Ein Skill ist ein teilbarer Ordner und landet oft in Git; ein Schlüssel darin landet früher oder später in falschen Händen. ### Funktioniert derselbe Skill in Cursor oder Codex? Das Format `SKILL.md` stammt von Anthropic, aber die Anweisungen darin sind reiner Text. Teams kopieren den Inhalt oft in Cursor-Regeln oder eine Prompt-Datei für Codex. Die Tool-Namen sind in jedem Client gleich, weil sie vom MCP-Server von Shager kommen. ## Nächster Schritt Ein Skill, der auf Anfrage Entwürfe schreibt, ist das Fundament. Der nächste Artikel macht daraus eine [wöchentliche Distributionsroutine](/en/blog/skill-weekly-distribution-routine), die die Woche plant, die Beiträge jedes Kunden entwirft, Freigaben weiterleitet und Klicks berichtet – mit den menschlichen Kontrollpunkten an den richtigen Stellen. --- Source: https://shager.ai/de/blog/build-a-claude-skill-for-shager