Claude Skill

Work with your Vizzybl GEO data — Share of Voice, monitored prompts, the actual AI answers, and citations — directly inside Claude. The Vizzybl skill teaches Claude to call the Vizzybl public API, so you can ask questions in plain language instead of opening a dashboard.

Vizzybl covers Claude natively, alongside ChatGPT, Gemini, Perplexity, Grok, Copilot, Google AI Overviews and Google AI Mode.

Before you begin

You need:

• An Ultra or Enterprise plan — API access is available on these tiers.
• The owner or admin role in your workspace, to create keys.
• Claude Code, the Claude desktop app, or any Claude surface that supports Agent Skills.

Step 1: Create an API key

1. Open Settings → API Keys.
2. Click Create API key, name it (for example, "Claude skill"), and choose scopes. All read access is the simplest starting point. Leave the write scopes unchecked unless you want Claude to be able to run audits or scrape prompts — you can always create a second, write-scoped key later and revoke it when you're done.
3. Copy the key immediately. It starts with vzbl_live_ and is shown only once — store it like a password.

You can revoke a key at any time from the same screen. Revocation takes effect immediately.

Step 2: Add the skill

The skill is a folder — SKILL.md plus a full references/api-reference.md and an openapi.json spec. How you add it depends on where you use Claude.

⬇ Download the packaged skill (.zip)

Claude Code — as a plugin (recommended). Add the Vizzybl marketplace once, then install:

/plugin marketplace add vizzybl-ai/claude-plugins
/plugin install vizzybl-geo@vizzybl

Installing this way means updates arrive automatically — Claude Code checks the marketplace in the background and prompts you to reload when a new version ships.

Claude Code — as a folder. Or copy the folder into your skills directory:

• Every project: ~/.claude/skills/vizzybl-geo/
• One project: .claude/skills/vizzybl-geo/

Claude Desktop or claude.ai. Upload the skill .zip under Settings → Features → Skills (Pro, Max, Team, or Enterprise). The skill calls the Vizzybl API, so it only works where Claude has network access — enable network access for skills in your workspace. Skills on the Claude API surface have no network access and can't reach the API.

Because the skill calls the Vizzybl API, claude.ai must be allowed to reach it. In your Claude settings:

1. Turn on Allow network egress (it may already be enabled for your workspace).
2. Under Domain allowlist → Additional allowed domains, add vizzybl.ai and click Add.

Without this, the skill's requests fail with a network / connection error.

Step 3: Set your API key

The skill reads your key from the VIZZYBL_API_KEY environment variable:

export VIZZYBL_API_KEY="vzbl_live_..."

If it isn't set, Claude asks for it once and uses it for the session.

Step 4: Ask a question, or run a command

Five commands cover the common workflows:

Command	What it does
/vizzybl-geo:pulse [days]	Week-over-week share of voice, rank, and sentiment
/vizzybl-geo:answers [topic]	The verbatim AI answers for your monitored prompts, grouped by engine
/vizzybl-geo:gaps [domain]	Citation gaps — domains AI engines cite where yours isn't
/vizzybl-geo:scorecard [days]	Per-engine visibility breakdown
/vizzybl-geo:audit <url>	Run a GEO audit on a URL — spends credits

/vizzybl-geo:audit is the one command Claude can never trigger on its own: it is marked user-invoked only, so an audit runs when you type it and not otherwise.

For anything else, just ask in plain language:

• "How is my brand doing in AI search over the last 90 days?"
• "What did ChatGPT and Claude actually say about us for our top prompts?"
• "Which competitor domains get cited where we don't?"
• "Which of our products show up in AI answers, and which rivals come up instead?"
• "How much AI-crawler traffic did we get last month, and did anything get blocked?"

Claude calls the API, paginates when there is more data, and summarizes the results — grouped by engine when you compare answers.

If your key carries a write scope, you can also ask it to act — "audit our pricing page" or "start tracking these five questions" — and it will confirm the cost with you before spending anything.

What you can query

Area	Endpoint
Snapshot + trend	/api/v1/stats, /api/v1/visibility
Brand, engines, plan	/api/v1/brand/me, /api/v1/engines, /api/v1/quota
Monitored prompts	/api/v1/prompts, /api/v1/prompts/{promptId}, /api/v1/prompts/{promptId}/metrics-history, /api/v1/tags
Verbatim AI answers	/api/v1/prompt-responses
Citations	/api/v1/citations, /api/v1/citations/prompts, /api/v1/citations/stats
Recommendations	/api/v1/recommendations
AI-bot crawler traffic	/api/v1/bot-traffic
Products	/api/v1/products, /api/v1/products/{productId}/metrics-history
GEO audits	/api/v1/audits, /api/v1/audits/{auditId}

Actions it can take, with your confirmation

Action	Endpoint	Scope	Cost
Run a GEO audit on a URL	POST /api/v1/audits	write:audits	Credits, settled when the audit completes
Create monitored prompts (up to 50)	POST /api/v1/prompts	write:prompts	Free
Re-scrape a prompt across engines	POST /api/v1/prompts/{promptId}/scrape	write:prompts	Charges prompt_monitor_run

The skill is instructed to state what it is about to do and get your agreement before any call that spends credits, and to check your balance with /api/v1/quota first. Audits and scrapes are asynchronous — the skill gets an ID back immediately and polls for the result, so a "running…" answer is expected before scores appear.

Most of the API is read-only, and every key is scoped to a single workspace. Three endpoints write: they run a GEO audit, create monitored prompts, or re-scrape a prompt. Those need the exact write:audits / write:prompts scope — the read:* wildcard never grants a write — and the metered ones draw on your credit balance. If you created the key with All read access, the skill physically cannot spend anything. The full endpoint reference, parameters, and response shapes are in the references/api-reference.md file bundled with the skill.

Security

• Treat keys like passwords — anyone with a key can read your workspace's GEO data.
• A read-only key cannot spend anything. A key holds only the scopes you grant, and read:* covers every read scope and no write scope — so a read-only key can never run an audit, create a prompt, or trigger a scrape.
• A key with a write scope can spend credits. Grant write:audits / write:prompts only when you want Claude to take those actions, and expect the skill to confirm with you each time. Check the balance with GET /api/v1/quota. No API key can change workspace settings, billing, or other keys.
• Revoke a key the moment it is no longer needed, or if it may have leaked.
• Keys are disabled automatically if your plan drops below Ultra.

Troubleshooting

• 401 — the key is missing, revoked, expired, or malformed. Re-check VIZZYBL_API_KEY.
• 403 — the key lacks the scope for that data, or the plan is no longer Ultra or Enterprise.
• 429 rate limited — wait and retry; Claude honors the retry delay automatically.
• 402 — not enough credits for a metered action. Claude reports your balance instead of retrying.
• 429 monthly limit — the monthly cap for that action is spent. Unlike a rate limit, waiting will not help.
• 422 — the monitored-prompt cap is full. Pause or archive a prompt, then try again.

Next steps

• Coding Agent Quickstart — Every way to reach Vizzybl from an agent, side by side
• MCP Server — The same data as typed tools, over OAuth
• API Endpoints — The REST surface the skill calls