Skills CLI
Scrumball Skills est un ensemble de compétences d'agent IA pour le marketing d'influence. Il traduit une demande en langage naturel en tâche métier exécutable, puis appelle l'API Scrumball via un operationId explicite.
Ce n'est pas une simple collection de prompts. Le projet fournit aussi :
- 5 compétences d'agent organisées par domaine métier ;
- 84 opérations d'API sous-jacentes ;
- 86 tâches sémantiques destinées aux équipes métier et aux agents IA ;
- les capacités de données sociales prises en charge par plateforme ;
- un outillage unifié pour l'initialisation, les tests de connectivité, la recherche de tâches et les démos ;
- pour chaque compétence : index d'API, description des paramètres, structure de réponse et script d'exécution ;
- le schéma OpenAPI et une table de correspondance des tâches lisible par machine.
Les cas d'usage typiques : découverte de créateurs, adéquation d'audience, enrichissement de données en temps réel, suivi de campagne et intelligence commerce TikTok Shop.
Vue d'ensemble des capacités
| Domaine | Compétence | Tâches | Opérations d'API | Plateformes | Capacités principales |
|---|---|---|---|---|---|
| Découverte de créateurs | influencer-lead-discovery | 22 | 23 | YouTube, TikTok, Instagram, multiplateforme | Recherche de créateurs et de contenus, profils, créateurs similaires, collaborations de marque, engagement par hashtag |
| Adéquation d'audience | influencer-audience-fit-scoring | 38 | 35 | YouTube, TikTok, Instagram | Géographie, langue, âge, genre, centres d'intérêt, comportement d'engagement, authenticité des abonnés, notation |
| Enrichissement temps réel | influencer-realtime-enrichment | 10 | 10 | YouTube, TikTok, Instagram | Profils, vidéos, publications, stories et détails de contenu en temps réel |
| Suivi de campagne | influencer-campaign-monitoring | 11 | 11 | YouTube, TikTok, Instagram, multiplateforme | Créer, consulter, rafraîchir et arrêter des tâches de suivi, lire les indicateurs et télécharger les médias |
| Intelligence commerce | influencer-commerce-intel | 5 | 5 | TikTok | Données de vente, produits, lives, vidéos publicitaires et détails produit |
Mise en route
Initialisation
L'outil d'initialisation demande l'URL de la passerelle, la clé API, un préfixe d'authentification optionnel et le délai d'attente, les écrit dans .env et appelle /api/ping par défaut.
bash
npx skills add scrumball/skills
Vérification
bash
python3 scripts/scrumball_cli.py doctor
Une exécution réussie renvoie :
json
{"ok": true}
Trouver une tâche
bash
python3 scripts/scrumball_cli.py tasks --search creator
Prévisualiser un appel
bash
python3 scripts/scrumball_cli.py demo \--task lead.find-tiktok-creators \--param query=nike \--dry-run
Exécuter l'appel
Une fois la tâche, les paramètres et l'environnement cible confirmés, retirez --dry-run :
bash
python3 scripts/scrumball_cli.py demo \--task lead.find-tiktok-creators \--param query=nike
Sécurité et bonnes pratiques en production
Gestion des identifiants
- Ne versionnez jamais .env ni une clé API réelle.
- En production, utilisez un gestionnaire de secrets ou les secrets CI/CD.
- N'affichez jamais une clé API complète dans les logs, erreurs, prompts ou rapports.
- Utilisez des identifiants distincts pour le développement, les tests et la production.
- Renouvelez régulièrement les clés API et appliquez le moindre privilège.
Sécurité des appels
- Lancez d'abord une tâche avec --dry-run pour vérifier la correspondance et les paramètres.
- Ne considérez pas les exemples de la documentation comme de vraies saisies utilisateur.
- Ajoutez confirmation et audit pour la création, le rafraîchissement et l'arrêt des tâches de suivi.
- Maîtrisez la concurrence, les reprises et les délais pour les appels en lot.
- Les limites de débit et quotas suivent la politique réelle de la passerelle Scrumball ; ne les présumez pas côté client.
- Lors d'une comparaison entre plateformes, signalez les différences de mesure au lieu de les assimiler.
Qualité des données
- Si un endpoint temps réel ne renvoie rien, réessayez une fois et consignez le résultat dégradé.
- Une dimension d'audience manquante n'empêche pas la notation, mais la confiance doit baisser.
- Sans résultat de recherche, assouplissez un filtre à la fois et journalisez le changement.
- Si les données de suivi accusent un retard, indiquez explicitement leur fraîcheur.
- Conservez l'identifiant source, l'heure d'appel et l'operationId avec chaque conclusion pour l'audit.
Dépannage
| Symptôme ou erreur | Cause fréquente | Que faire |
|---|---|---|
SCRUMBALL_BASE_URL is required | URL de passerelle non configurée | Renseignez SCRUMBALL_BASE_URL dans .env |
SCRUMBALL_API_KEY is required | Clé API non configurée | Renseignez SCRUMBALL_API_KEY dans .env |
Missing required ... | Un champ obligatoire de requête ou de corps manque | Consultez les questions de relance de la tâche ou le request-response.md correspondant |
Unknown operationId | Faute de frappe ou mauvaise compétence utilisée | Exécutez la commande list de cette compétence |
HTTP 401 / 403 | Clé API, préfixe d'authentification ou droits incorrects | Vérifiez la clé, SCRUMBALL_AUTH_PREFIX et les droits de la passerelle |
HTTP 404 | URL de passerelle, chemin d'endpoint ou ressource cible incorrects | Vérifiez SCRUMBALL_BASE_URL, l'operationId et les champs d'identifiant |
Network error / erreur DNS | Passerelle injoignable, problème de VPN ou de DNS | Lancez doctor et vérifiez l'environnement réseau |
Délai de requête dépassé | Réponse lente de la passerelle ou délai trop court | Augmentez SCRUMBALL_TIMEOUT_SECONDS et journalisez la reprise |
Réponse vide | Identifiant erroné, données pas encore collectées ou collecte temps réel en échec | Validez l'identifiant de plateforme, réessayez une fois et expliquez le repli |
Incohérence de la table des tâches | Opérations ajoutées ou renommées sans mise à jour de la table | Exécutez check-task-map --strict et mettez à jour la correspondance |