botsee

# 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 <domain> [--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 <domain>   - Create a new site
- /botsee archive-site [uuid]    - Archive a site

**Customer Types:**
- /botsee list-types             - List customer types
- /botsee get-type <uuid>        - View type details
- /botsee create-type <name> [desc] - Create customer type
- /botsee generate-types [count] - Generate customer types
- /botsee update-type <uuid> [name] [desc] - Update customer type
- /botsee archive-type <uuid>    - Archive customer type

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

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

**Results:**
- /botsee results-competitors <uuid>    - View competitor results
- /botsee results-keywords <uuid>       - View keyword results
- /botsee results-sources <uuid>        - View source results
- /botsee results-responses <uuid>      - View all AI responses
- /botsee results-keyword-opportunities <uuid> [--threshold 0.0-1.0] [--rank-threshold N] - Questions where brand is missing or ranks poorly
- /botsee results-source-opportunities <uuid>  - 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)

```bash
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**
```bash
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:
```bash
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:
```bash
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):

```bash
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]

```bash
# 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]

```bash
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]

```bash
# 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 <domain> [--types T] [--personas P] [--questions Q]

**Requires:** API key from `/botsee signup`

```bash
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:**
```bash
python3 ~/.claude/skills/botsee/scripts/botsee.py create-site <domain> --types 3 --personas 2 --questions 10
```

### /botsee config-show

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

### /botsee analyze

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

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

### /botsee content

```bash
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

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

### /botsee get-site [uuid]

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

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

### /botsee create-site <domain>

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

### /botsee archive-site [uuid]

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

---

## Customer Types Commands

### /botsee list-types

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

### /botsee get-type <uuid>

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

### /botsee create-type <name> [description]

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

### /botsee generate-types [count]

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

Defaults to 2 if count is omitted.

### /botsee update-type <uuid> [name] [description]

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

### /botsee archive-type <uuid>

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

---

## Personas Commands

### /botsee list-personas [type_uuid]

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

### /botsee get-persona <uuid>

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

### /botsee create-persona <type_uuid> <name> [description]

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

### /botsee generate-personas <type_uuid> [count]

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

Defaults to 2 if count is omitted.

### /botsee update-persona <uuid> [name] [description]

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

### /botsee archive-persona <uuid>

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

---

## Questions Commands

### /botsee list-questions [persona_uuid]

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

### /botsee get-question <uuid>

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

### /botsee create-question <persona_uuid> <question_text>

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

### /botsee generate-questions <persona_uuid> [count]

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

Defaults to 5 if count is omitted.

### /botsee update-question <uuid> <question_text>

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

### /botsee delete-question <uuid>

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

---

## Results Commands

### /botsee results-competitors <analysis_uuid>

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

### /botsee results-keywords <analysis_uuid>

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

### /botsee results-sources <analysis_uuid>

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

### /botsee results-responses <analysis_uuid>

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

### /botsee results-keyword-opportunities <analysis_uuid> [--threshold N] [--rank-threshold N]

```bash
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 <analysis_uuid>

```bash
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:
```bash
/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:**
```bash
# 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

```bash
# 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
```