Skills CLI

Scrumball Skills is a set of AI agent skills for influencer marketing. It maps a user's natural-language request to an executable business task, then calls the Scrumball API through an explicit operationId.

This is not just a prompt collection. It also ships:

5 agent skills grouped by business domain;
84 underlying API operations;
86 semantic tasks aimed at business users and AI agents;
the social data capabilities supported on each platform;
unified tooling for setup, connectivity checks, task discovery and demos;
a per-skill API index, parameter reference, response structure and runner script;
the OpenAPI schema and a machine-readable task map.

Typical use cases include creator discovery, audience fit, realtime data enrichment, campaign monitoring and TikTok Shop commerce intelligence.

Capability overview

Domain	Skill	Tasks	API operations	Platforms	Main capabilities
Creator discovery	`influencer-lead-discovery`	22	23	YouTube, TikTok, Instagram, cross-platform	Creator and content search, profiles, similar creators, brand deals, hashtag engagement
Audience fit	`influencer-audience-fit-scoring`	38	35	YouTube, TikTok, Instagram	Geography, language, age, gender, interests, engagement behavior, follower authenticity, rating
Realtime enrichment	`influencer-realtime-enrichment`	10	10	YouTube, TikTok, Instagram	Realtime profiles, videos, posts, stories and content details
Campaign monitoring	`influencer-campaign-monitoring`	11	11	YouTube, TikTok, Instagram, cross-platform	Create, query, refresh and stop monitoring tasks, read metrics and download assets
Commerce intel	`influencer-commerce-intel`	5	5	TikTok	Sales data, products, livestreams, ad videos and product details

Quick start

Initialize

The setup tool asks for the gateway URL, API key, optional auth prefix and timeout, writes them to .env, and calls /api/ping by default.

bash

npx skills add scrumball/skills

Verify

bash

python3 scripts/scrumball_cli.py doctor

A successful run returns:

json

{
  "ok": true
}

Find a task

bash

python3 scripts/scrumball_cli.py tasks --search creator

Preview a call

bash

python3 scripts/scrumball_cli.py demo \
  --task lead.find-tiktok-creators \
  --param query=nike \
  --dry-run

Run the call

Once the task, parameters and target environment are confirmed, drop --dry-run:

bash

python3 scripts/scrumball_cli.py demo \
  --task lead.find-tiktok-creators \
  --param query=nike

Security and production guidance

Credentials

Never commit .env or a real API key to the repository.
In production, use a secret manager or CI/CD secrets.
Never print a full API key in logs, errors, prompts or reports.
Use separate credentials for development, testing and production.
Rotate API keys regularly and follow least privilege.

Safe calls

Run a task with --dry-run first to check the mapping and parameters.
Do not treat documentation samples as real user input.
Add confirmation and auditing around creating, refreshing and stopping monitoring tasks.
Control concurrency, retries and timeouts for batch calls.
Rate limits and quotas follow the live Scrumball gateway policy; do not assume them client-side.
When comparing platforms, flag metric differences instead of equating them.

Data quality

If a realtime endpoint returns nothing, retry once and record the degraded result.
A missing audience dimension may keep scoring, but confidence must go down.
With no search results, relax one filter at a time and log the change.
When monitoring data lags, state the data freshness explicitly.
Keep the source identifier, call time and operationId with every conclusion for auditing.

Troubleshooting

Symptom or error	Common cause	What to do
`SCRUMBALL_BASE_URL is required`	No gateway URL configured	Set SCRUMBALL_BASE_URL in .env
`SCRUMBALL_API_KEY is required`	No API key configured	Set SCRUMBALL_API_KEY in .env
`Missing required ...`	A required query or body field is missing	Check the task's follow-up questions or the matching request-response.md
`Unknown operationId`	Typo, or the wrong skill is in use	Run that skill's list command
`HTTP 401 / 403`	Wrong API key, auth prefix or permissions	Check the key, SCRUMBALL_AUTH_PREFIX and the gateway permissions
`HTTP 404`	Wrong gateway URL, endpoint path or target resource	Check SCRUMBALL_BASE_URL, the operationId and the identifier fields
`Network error / DNS`	Gateway unreachable, VPN or DNS problem	Run doctor and confirm the network environment
`Request timeout`	Slow gateway response or a timeout set too low	Raise SCRUMBALL_TIMEOUT_SECONDS and log the retry
`Empty response`	Wrong identifier, data not collected yet, or realtime collection failed	Validate the platform identifier, retry once and explain the fallback
`Task map mismatch`	Operations were added or renamed without updating the task map	Run check-task-map --strict and update the mapping