Skills CLI
Scrumball Skills ist eine Sammlung von KI-Agent-Skills für Influencer-Marketing. Sie übersetzt eine Anfrage in natürlicher Sprache in eine ausführbare Aufgabe und ruft die Scrumball-API über eine explizite operationId auf.
Das Projekt ist keine reine Prompt-Sammlung. Es liefert zusätzlich:
- 5 Agent-Skills, nach Geschäftsbereich gegliedert;
- 84 zugrunde liegende API-Operationen;
- 86 semantische Aufgaben für Fachanwender und KI-Agenten;
- die je Plattform unterstützten Social-Daten-Funktionen;
- einheitliche Werkzeuge für Einrichtung, Erreichbarkeitsprüfung, Aufgabensuche und Demos;
- je Skill einen API-Index, Parameterbeschreibungen, Antwortstrukturen und ein Ausführungsskript;
- das OpenAPI-Schema und eine maschinenlesbare Aufgabenzuordnung.
Typische Einsatzfälle: Creator-Entdeckung, Zielgruppen-Passung, Echtzeit-Datenanreicherung, Kampagnen-Monitoring und TikTok-Shop-Commerce-Intelligence.
Funktionsüberblick
| Bereich | Skill | Aufgaben | API-Operationen | Plattformen | Hauptfunktionen |
|---|---|---|---|---|---|
| Creator-Entdeckung | influencer-lead-discovery | 22 | 23 | YouTube, TikTok, Instagram, plattformübergreifend | Creator- und Content-Suche, Profile, ähnliche Creator, Markenkooperationen, Hashtag-Engagement |
| Zielgruppen-Passung | influencer-audience-fit-scoring | 38 | 35 | YouTube, TikTok, Instagram | Geografie, Sprache, Alter, Geschlecht, Interessen, Engagement-Verhalten, Follower-Echtheit, Bewertung |
| Echtzeit-Anreicherung | influencer-realtime-enrichment | 10 | 10 | YouTube, TikTok, Instagram | Echtzeit-Profile, -Videos, -Beiträge, -Stories und Inhaltsdetails |
| Kampagnen-Monitoring | influencer-campaign-monitoring | 11 | 11 | YouTube, TikTok, Instagram, plattformübergreifend | Monitoring-Aufgaben erstellen, abfragen, aktualisieren und stoppen, Kennzahlen lesen und Assets herunterladen |
| Commerce-Intelligence | influencer-commerce-intel | 5 | 5 | TikTok | Verkaufsdaten, Produkte, Livestreams, Werbevideos und Produktdetails |
Schnelleinstieg
Initialisierung
Das Setup-Tool fragt Gateway-URL, API-Schlüssel, optionales Auth-Präfix und Timeout ab, schreibt sie in .env und ruft standardmäßig /api/ping auf.
bash
npx skills add scrumball/skills
Prüfung
bash
python3 scripts/scrumball_cli.py doctor
Bei Erfolg wird zurückgegeben:
json
{"ok": true}
Aufgabe finden
bash
python3 scripts/scrumball_cli.py tasks --search creator
Aufruf vorab prüfen
bash
python3 scripts/scrumball_cli.py demo \--task lead.find-tiktok-creators \--param query=nike \--dry-run
Aufruf ausführen
Wenn Aufgabe, Parameter und Zielumgebung bestätigt sind, entfernen Sie --dry-run:
bash
python3 scripts/scrumball_cli.py demo \--task lead.find-tiktok-creators \--param query=nike
Sicherheit und Produktivbetrieb
Verwaltung von Zugangsdaten
- Committen Sie niemals .env oder einen echten API-Schlüssel.
- Nutzen Sie in der Produktion einen Secret-Manager oder CI/CD-Secrets.
- Geben Sie einen vollständigen API-Schlüssel nie in Logs, Fehlern, Prompts oder Berichten aus.
- Verwenden Sie getrennte Zugangsdaten für Entwicklung, Test und Produktion.
- Wechseln Sie API-Schlüssel regelmäßig und folgen Sie dem Least-Privilege-Prinzip.
Sichere Aufrufe
- Führen Sie eine Aufgabe zuerst mit --dry-run aus, um Zuordnung und Parameter zu prüfen.
- Behandeln Sie Beispielwerte aus der Dokumentation nicht als echte Nutzereingaben.
- Ergänzen Sie Bestätigung und Audit beim Erstellen, Aktualisieren und Stoppen von Monitoring-Aufgaben.
- Steuern Sie Parallelität, Wiederholungen und Timeouts bei Batch-Aufrufen.
- Ratenlimits und Kontingente richten sich nach der tatsächlichen Scrumball-Gateway-Policy; nehmen Sie sie nicht clientseitig an.
- Weisen Sie beim Plattformvergleich auf Metrik-Unterschiede hin, statt sie gleichzusetzen.
Datenqualität
- Liefert ein Echtzeit-Endpunkt nichts, wiederholen Sie einmal und protokollieren Sie das eingeschränkte Ergebnis.
- Fehlt eine Zielgruppen-Dimension, darf weiter bewertet werden – die Konfidenz muss jedoch sinken.
- Ohne Suchtreffer lockern Sie jeweils nur einen Filter und protokollieren die Änderung.
- Bei verzögerten Monitoring-Daten geben Sie die Aktualität ausdrücklich an.
- Bewahren Sie zu jeder Schlussfolgerung Quell-ID, Aufrufzeit und operationId für die Nachvollziehbarkeit auf.
Fehlerbehebung
| Symptom oder Fehler | Häufige Ursache | Vorgehen |
|---|---|---|
SCRUMBALL_BASE_URL is required | Keine Gateway-URL konfiguriert | Ergänzen Sie SCRUMBALL_BASE_URL in .env |
SCRUMBALL_API_KEY is required | Kein API-Schlüssel konfiguriert | Ergänzen Sie SCRUMBALL_API_KEY in .env |
Missing required ... | Ein erforderliches Query- oder Body-Feld fehlt | Prüfen Sie die Rückfragen der Aufgabe oder die passende request-response.md |
Unknown operationId | Tippfehler oder falscher Skill im Einsatz | Führen Sie den list-Befehl dieses Skills aus |
HTTP 401 / 403 | Falscher API-Schlüssel, Auth-Präfix oder fehlende Rechte | Prüfen Sie Schlüssel, SCRUMBALL_AUTH_PREFIX und die Gateway-Rechte |
HTTP 404 | Falsche Gateway-URL, Endpunktpfad oder Zielressource | Prüfen Sie SCRUMBALL_BASE_URL, die operationId und die Kennungsfelder |
Network error / DNS-Fehler | Gateway nicht erreichbar, VPN- oder DNS-Problem | Führen Sie doctor aus und prüfen Sie die Netzwerkumgebung |
Zeitüberschreitung der Anfrage | Langsame Gateway-Antwort oder zu kurzes Timeout | Erhöhen Sie SCRUMBALL_TIMEOUT_SECONDS und protokollieren Sie den Neuversuch |
Leere Antwort | Falsche Kennung, Daten noch nicht erfasst oder Echtzeit-Erfassung fehlgeschlagen | Prüfen Sie die Plattform-Kennung, wiederholen Sie einmal und erläutern Sie den Fallback |
Abweichende Aufgabenzuordnung | Operationen ergänzt oder umbenannt, ohne die Aufgabentabelle zu aktualisieren | Führen Sie check-task-map --strict aus und aktualisieren Sie die Zuordnung |