Botsee

Generated note: shared plugin assets for this package live at the plugin root. Common local references were rewritten when they appeared in backticks or markdown links.

BotSee Skill

Monitor your brand's AI visibility (AI SEO/GEO) across ChatGPT, Claude, Perplexity, and Gemini. Provided by botsee.io, the AI Visibility tool for Claude Code and agents.

Commands:

Workflow:

• /botsee - Quick status and help
• /botsee signup [--email EMAIL] [--name NAME] [--company COMPANY] [--api-key KEY] - Signup with credit card
• /botsee signup-usdc [--email EMAIL] [--name NAME] [--company COMPANY] [--no-email] - Signup with USDC on Base
• /botsee signup-pay-usdc --amount-cents N [--token TOKEN] [--payment PROOF] - Pay for USDC signup via x402
• /botsee signup-status [--token TOKEN] - Check signup completion and save API key
• /botsee topup-usdc --amount-cents N [--payment PROOF] - Add credits with USDC on Base via x402
• /botsee create-site [--types N] - Save custom config
• /botsee config-show - Display saved config
• /botsee analyze - Run competitive analysis
• /botsee content - Generate blog post from analysis

Sites:

• /botsee list-sites - List all sites
• /botsee get-site [uuid] - View site details
• /botsee create-site - Create a new site
• /botsee archive-site [uuid] - Archive a site

Customer Types:

• /botsee list-types - List customer types
• /botsee get-type - View type details
• /botsee create-type [desc] - Create customer type
• /botsee generate-types [count] - Generate customer types
• /botsee update-type [name] [desc] - Update customer type
• /botsee archive-type - Archive customer type

Personas:

• /botsee list-personas [type] - List personas (all or by type)
• /botsee get-persona - View persona details
• /botsee create-persona [desc] - Create persona
• /botsee generate-personas [count] - Generate personas for type
• /botsee update-persona [name] [desc] - Update persona
• /botsee archive-persona - Archive persona

Questions:

• /botsee list-questions [persona] - List questions (all or by persona)
• /botsee get-question - View question details
• /botsee create-question - Create question
• /botsee generate-questions [count] - Generate questions for persona
• /botsee update-question - Update question text
• /botsee delete-question - Delete question

Results:

• /botsee results-competitors - View competitor results
• /botsee results-keywords - View keyword results
• /botsee results-sources - View source results
• /botsee results-responses - View all AI responses
• /botsee results-keyword-opportunities [--threshold 0.0-1.0] [--rank-threshold N] - Questions where brand is missing or ranks poorly
• /botsee results-source-opportunities - Sources AI cited when brand was NOT mentioned

Implementation

When user invokes a BotSee command, run the corresponding Python script. All commands use a single bundled script that handles API calls internally.

/botsee (status)

python3 ~/.claude/skills/botsee/scripts/botsee.py status

/botsee signup [--email EMAIL] [--name NAME] [--company COMPANY] [--api-key KEY]

New user signup flow (credit card):

Step 1: Get signup URL

python3 ~/.claude/skills/botsee/scripts/botsee.py signup

The command prints a line like:

Complete signup: https://app.botsee.io/setup?token=...

Extract that URL and tell the user: "To complete your BotSee signup, visit this URL: [URL from above]

After completing signup on that page, come back here and run /botsee signup-status."

Step 2: Save your API key

After completing signup on that page, run:

/botsee signup-status

The script retrieves your API key from the server automatically using your signup token. If prompted for a token, use the token from the URL on the setup page.

/botsee signup-usdc [--email EMAIL] [--name NAME] [--company COMPANY] [--no-email]

USDC signup flow (x402 on Base):

Step 1 — Ask the user before calling the API

When signup-usdc is invoked without already knowing the user's preference, ask:

"Do you want to associate an email with this account?

• Yes (email) — You'll get a setup link to verify your email and access the dashboard later
• No (API only) — Skip email entirely and go straight to payment"

Step 2a — Email path

Call:

python3 ~/.claude/skills/botsee/scripts/botsee.py signup-usdc

(no --no-email flag)

The command prints a line like:

Setup URL: https://app.botsee.io/setup?token=...

Extract that URL and tell the user: "Visit this URL to enter and verify your email and read the setup instructions: [URL from above]

Once you've done that, come back here and we'll complete the USDC payment."

Do NOT call signup-pay-usdc yet. Wait for the user to confirm they've completed the setup URL step.

Step 2b — No-email path

Call:

python3 ~/.claude/skills/botsee/scripts/botsee.py signup-usdc --no-email

No setup URL will be returned. Immediately proceed to payment.

Step 3 — Payment (both paths)

After the email-path user confirms they visited the setup URL (or immediately for no-email path):

python3 ~/.claude/skills/botsee/scripts/botsee.py signup-pay-usdc --amount-cents 250
python3 ~/.claude/skills/botsee/scripts/botsee.py signup-status

x402 flow details:

1. signup-usdc creates a USDC signup token via POST /api/v1/signup/usdc
2. signup-pay-usdc --amount-cents N calls POST /api/v1/signup/:token/pay-usdc without a payment header → server returns 402 with payment requirements (network, amount, payTo address)
3. Use a wallet (Pinch, Coinbase CDP Agentic Wallet) to send USDC to the returned address
4. Retry with the payment proof: signup-pay-usdc --amount-cents N --payment <proof>
5. signup-status polls until complete and saves the API key

/botsee signup-pay-usdc --amount-cents N [--token TOKEN] [--payment PROOF]

# Step 1: Get 402 challenge (no --payment → returns payment requirements)
python3 ~/.claude/skills/botsee/scripts/botsee.py signup-pay-usdc --amount-cents 250

# Step 2: Retry with proof after wallet pays
python3 ~/.claude/skills/botsee/scripts/botsee.py signup-pay-usdc --amount-cents 250 --payment <proof>

Omit --payment to get a 402 challenge with network, amount, and payTo address. Include --payment <base64-proof> on the final retry after your wallet has made the payment.

/botsee signup-status [--token TOKEN]

python3 ~/.claude/skills/botsee/scripts/botsee.py signup-status

Saves API key to ~/.botsee/config.json automatically once signup is completed.

/botsee topup-usdc --amount-cents N [--payment PROOF]

# Step 1: Get 402 challenge (no --payment → returns payment requirements)
python3 ~/.claude/skills/botsee/scripts/botsee.py topup-usdc --amount-cents 5000

# Step 2: Retry with proof after wallet pays
python3 ~/.claude/skills/botsee/scripts/botsee.py topup-usdc --amount-cents 5000 --payment <proof>

Omit --payment to get a 402 challenge with network, amount, and payTo address. Include --payment <base64-proof> on the final retry after your wallet has made the payment.

/botsee create-site [--types T] [--personas P] [--questions Q]

Requires: API key from /botsee signup

python3 ~/.claude/skills/botsee/scripts/botsee.py create-site <domain>

Optional parameters:

• --types (default: 2, range: 1-3)
• --personas (default: 2, range: 1-3)
• --questions (default: 5, range: 3-10)

What happens:

1. Creates a site for the domain
2. Generates customer types, personas, and questions
3. Saves configuration to workspace and user config

Customize generation counts:

python3 ~/.claude/skills/botsee/scripts/botsee.py create-site <domain> --types 3 --personas 2 --questions 10

/botsee config-show

python3 ~/.claude/skills/botsee/scripts/botsee.py config-show

/botsee analyze

python3 ~/.claude/skills/botsee/scripts/botsee.py analyze

Starts analysis, polls until complete, then displays competitors, keywords, and sources.

/botsee content

python3 ~/.claude/skills/botsee/scripts/botsee.py content

Generates blog post from latest analysis. Auto-saves to botsee-YYYYMMDD-HHMMSS.md.

Sites Commands

/botsee list-sites

python3 ~/.claude/skills/botsee/scripts/botsee.py list-sites

/botsee get-site [uuid]

python3 ~/.claude/skills/botsee/scripts/botsee.py get-site [uuid]

If uuid is omitted, uses the site from ~/.botsee/config.json.

/botsee create-site

python3 ~/.claude/skills/botsee/scripts/botsee.py create-site <domain>

/botsee archive-site [uuid]

python3 ~/.claude/skills/botsee/scripts/botsee.py archive-site [uuid]

Customer Types Commands

/botsee list-types

python3 ~/.claude/skills/botsee/scripts/botsee.py list-types

/botsee get-type

python3 ~/.claude/skills/botsee/scripts/botsee.py get-type <uuid>

/botsee create-type [description]

python3 ~/.claude/skills/botsee/scripts/botsee.py create-type "Enterprise Buyers" "Large companies seeking solutions"

/botsee generate-types [count]

python3 ~/.claude/skills/botsee/scripts/botsee.py generate-types 3

Defaults to 2 if count is omitted.

/botsee update-type [name] [description]

python3 ~/.claude/skills/botsee/scripts/botsee.py update-type <uuid> --name "New Name" --description "New description"

/botsee archive-type

python3 ~/.claude/skills/botsee/scripts/botsee.py archive-type <uuid>

Personas Commands

/botsee list-personas [type_uuid]

python3 ~/.claude/skills/botsee/scripts/botsee.py list-personas
python3 ~/.claude/skills/botsee/scripts/botsee.py list-personas <type_uuid>

/botsee get-persona

python3 ~/.claude/skills/botsee/scripts/botsee.py get-persona <uuid>

/botsee create-persona [description]

python3 ~/.claude/skills/botsee/scripts/botsee.py create-persona <type_uuid> "Sarah Chen" "VP of Marketing at mid-sized SaaS company"

/botsee generate-personas [count]

python3 ~/.claude/skills/botsee/scripts/botsee.py generate-personas <type_uuid> 3

Defaults to 2 if count is omitted.

/botsee update-persona [name] [description]

python3 ~/.claude/skills/botsee/scripts/botsee.py update-persona <uuid> --name "New Name" --description "New description"

/botsee archive-persona

python3 ~/.claude/skills/botsee/scripts/botsee.py archive-persona <uuid>

Questions Commands

/botsee list-questions [persona_uuid]

python3 ~/.claude/skills/botsee/scripts/botsee.py list-questions
python3 ~/.claude/skills/botsee/scripts/botsee.py list-questions <persona_uuid>

/botsee get-question

python3 ~/.claude/skills/botsee/scripts/botsee.py get-question <uuid>

/botsee create-question

python3 ~/.claude/skills/botsee/scripts/botsee.py create-question <persona_uuid> "What are the best email marketing tools?"

/botsee generate-questions [count]

python3 ~/.claude/skills/botsee/scripts/botsee.py generate-questions <persona_uuid> 5

Defaults to 5 if count is omitted.

/botsee update-question

python3 ~/.claude/skills/botsee/scripts/botsee.py update-question <uuid> "What are the best affordable email marketing tools?"

/botsee delete-question

python3 ~/.claude/skills/botsee/scripts/botsee.py delete-question <uuid>

Results Commands

/botsee results-competitors

python3 ~/.claude/skills/botsee/scripts/botsee.py results-competitors <analysis_uuid>

/botsee results-keywords

python3 ~/.claude/skills/botsee/scripts/botsee.py results-keywords <analysis_uuid>

/botsee results-sources

python3 ~/.claude/skills/botsee/scripts/botsee.py results-sources <analysis_uuid>

/botsee results-responses

python3 ~/.claude/skills/botsee/scripts/botsee.py results-responses <analysis_uuid>

/botsee results-keyword-opportunities [--threshold N] [--rank-threshold N]

python3 ~/.claude/skills/botsee/scripts/botsee.py results-keyword-opportunities <analysis_uuid>
python3 ~/.claude/skills/botsee/scripts/botsee.py results-keyword-opportunities <analysis_uuid> --threshold 0.8
python3 ~/.claude/skills/botsee/scripts/botsee.py results-keyword-opportunities <analysis_uuid> --rank-threshold 3

Returns questions where the brand's mention rate is below the threshold, with per-provider breakdown showing which AI models missed the brand, what rank it appeared at (if at all), and the search keywords each provider used.

• --threshold (0.0–1.0, default 1.0): questions where mention_rate < threshold qualify. At 1.0, any question not mentioned in every response is included.
• --rank-threshold (integer): additionally flags questions where brand appeared but at rank worse than this value.

/botsee results-source-opportunities

python3 ~/.claude/skills/botsee/scripts/botsee.py results-source-opportunities <analysis_uuid>

Returns sources that AI cited in responses where the brand was NOT mentioned — ideal targets for content and link-building campaigns.

Getting the Analysis UUID: The analysis UUID is displayed when you run /botsee analyze:

📊 Analysis started: abc-def-123

Copy the UUID and use it with the results commands to view detailed analysis data.

Agent Usage Notes

This skill is designed for non-interactive agent usage. All commands accept arguments via command-line flags - no prompts or user input required.

Key Considerations for Agents

1. Signup Flow Requires Human Intervention

For new users without an API key, the signup command creates a signup token and displays a URL:

/botsee signup
# Outputs signup URL for browser completion

Agents should:

• Use the --api-key flag if API key is available
• Inform user if signup is needed (cannot be completed by agent)
• Consider API key as a prerequisite for autonomous operation

2. Async Operations with Polling

Two commands can involve waiting/polling:

• /botsee signup-status (checks signup completion)
• /botsee analyze: up to 10 minute timeout

Commands will block until complete or timeout. No intermediate progress updates.

3. Analysis Discovery

To view detailed results after analysis:

1. Run /botsee analyze and capture the analysis UUID from output
2. Use UUID with /botsee results-* commands

Recommended pattern:

# Run analysis
output=$(/botsee analyze)
# Extract UUID (line containing "Analysis started:")
uuid=$(echo "$output" | grep "Analysis started:" | awk '{print $NF}')
# View results
/botsee results-competitors "$uuid"

4. Configuration Files

Two config files exist:

• User config: ~/.botsee/config.json (API key + site UUID)
• Workspace config: .context/botsee-config.json (generation defaults, optional)

Agents can discover state via:

• /botsee - Shows account status
• /botsee config-show - Shows workspace config

5. Credit Costs

All operations that consume credits display remaining balance. Agents should:

• Check balance before expensive operations (/botsee command)
• Handle "Insufficient credits" errors gracefully
• Monitor credit usage (shown after each operation)

Costs:

• Setup (~75 credits with defaults 2/2/5)
• Analysis (~660 credits per run)
• Content generation (15 credits)

6. Error Handling

All errors exit with code 1 and print to stderr. Error messages include:

• HTTP status codes (when relevant)
• Actionable next steps
• No API key leakage (sanitized)

7. Idempotency

• Safe to retry: Status, list, get commands (read-only)
• Not idempotent: Create commands (will create duplicates)
• Updates: Require specific UUID, safe to retry

8. Output Format

• CRUD operations: JSON output for parsing
• Workflow commands: Human-readable formatted text
• Status/balance: Always displayed at command completion

Example Agent Workflow

# 1. Check status (discover state)
/botsee

# 2. Save API key if provided by user
/botsee signup --api-key bts_live_abc123

# 3. Create a site
/botsee create-site https://example.com

# 4. Run analysis (captures UUID)
analysis_output=$(/botsee analyze)
uuid=$(echo "$analysis_output" | grep -oP '(?<=Analysis started: )\S+')

# 5. View results
/botsee results-competitors "$uuid"

# 6. Generate content
/botsee content

# 7. Check final balance
/botsee