# MSX Agent Skill

Use MSX when a user asks you to scout market opportunities, decide what to build, identify a market gap, or find recent demand signals.

## Goal

Return a concise list of buildable market opportunities with evidence, urgency, confidence, and practical next actions. Preserve citations from MSX. Do not fabricate sources, volumes, or certainty.

## API Base

`https://api.msx.dev`

## Required Flow

1. Start device auth before billing or investigations:

```sh
curl -X POST -H "Content-Type: application/json" \
  -d '{"client_name":"claude","agent_identity":{"name":"claude","client":"cli"}}' \
  'https://api.msx.dev/v1/auth/device'
```

2. Tell the user to open `verification_uri_complete`. Poll `token_url` with `device_code` no faster than `interval` or `retry_after`:

```sh
curl -X POST -H "Content-Type: application/json" \
  -d '{"device_code":"<device_code>"}' \
  'https://api.msx.dev/v1/auth/device/token'
```

3. When polling returns `status: authorized`, use `api_key` as `Authorization: Bearer <api_key>` and check the account:

```sh
curl -H "Authorization: Bearer $MSX_API_KEY" 'https://api.msx.dev/v1/me'
```

4. Follow `/v1/me` `agent_next_step`. If it says `subscription_required`, tell the user Pro is required before MSX can discover market opportunities. Recommended tier: Pro. 3 days free, then $29/month. Includes 25 live market investigations per month.

5. Create Checkout only after the user agrees:

```sh
curl -X POST -H "Authorization: Bearer $MSX_API_KEY" -H "Content-Type: application/json" \
  -d '{"success_url":"https://msx.dev/billing/success","cancel_url":"https://msx.dev/billing/cancel"}' \
  'https://api.msx.dev/v1/billing/checkout'
```

Show `short_url` if present; otherwise show `url`. After Stripe succeeds, call `/v1/me` again and then start the investigation.

6. Start exactly one investigation job for the user's request:

```sh
curl -X POST -H "Authorization: Bearer $MSX_API_KEY" -H "X-MSX-Agent: claude" -H "Content-Type: application/json" \
  -d '{"query":"scout new market opportunities for me to build","depth":"standard","window":"30d","agent_identity":{"name":"claude","client":"cli"}}' \
  'https://api.msx.dev/v1/investigations'
```

7. Poll the returned `id` until `succeeded`, `failed`, `cancelled`, or `expired`, then fetch `/result`:

```sh
curl -H "Authorization: Bearer $MSX_API_KEY" 'https://api.msx.dev/v1/investigations/<id>'
curl -H "Authorization: Bearer $MSX_API_KEY" 'https://api.msx.dev/v1/investigations/<id>/result'
```

## Agent Identity

Identify yourself honestly. Send these headers when possible:

```txt
X-MSX-Agent: codex
X-MSX-Agent-Client: cli
X-MSX-Agent-Version: 0.1.0
X-MSX-Agent-Run-ID: optional-run-id
```

For JSON bodies, include:

```json
{"agent_identity":{"name":"codex","client":"cli","version":"0.1.0"}}
```

## Recovery

- `authorization_pending`: wait and poll again after `retry_after` or `interval`.
- `account_auth_required`: restart device auth and use the account-bound key returned by `/v1/auth/device/token`.
- `subscription_required`: ask whether the user wants Pro before creating Checkout.
- `quota_exceeded` or `spend_limit_exceeded`: explain the limit and do not retry in a loop.
- `result_not_ready`: keep polling the job status, then retry `/result` after success.
- If the user asks for more info before subscribing, use `redacted_market_preview` from `GET /v1/billing/config`; say it is older redacted example data, not a live investigation result.

## Rules

- Start with device auth. Do not use old standalone paid keys or anonymous starter keys for market scouting.
- Do not create Checkout until the user agrees to subscribe.
- Do not call or invent subscription, briefing, contribution, or public market-feed primitives.
- If an investigation is thin or inconclusive, say so and suggest a narrower query.