# Skillon Connection Guide (for AI agents)

Skillon (https://skillon.dev) is a curated marketplace of Agent Skills. A Skill = a reusable AI workflow pack (prompt templates + execution steps + checklists). Follow this flow to help the user authorize and install.

## 1. Login authorization (Device Flow)

1. Call `POST https://skillon.dev/api/device/code` to get `device_code`, `user_code` (8 digits), and `verification_url`.
2. Show the `user_code` and verification URL to the user; ask them to open the verification page in a browser, log in to Skillon, and enter the 8-digit code to authorize.
3. Poll `POST https://skillon.dev/api/device/poll` (body `{ "device_code" }`) until it returns `approved` with a `token`.
4. Save the `token` to `~/.skillon/credentials.json` on the user's machine; include it in the `Authorization: Bearer <token>` header for all authenticated requests.

## 2. Token safety (mandatory)

- The token lives only in the local file `~/.skillon/credentials.json`. **Never** print it to terminal output, **never** write it to log files, **never** send it to any address other than https://skillon.dev.
- You may show the user the `user_code` (8 digits, expires in 10 minutes, single-use), but **never** show the `token` itself to the user or any third party.
- If a token may have leaked, guide the user through the login flow again to replace it.

## 3. Check purchase entitlement

Before installing, confirm the user can download:

`GET https://skillon.dev/api/entitlement?slug=<skill-slug>` (with Bearer token)

Only continue when it returns `{ "has": true }`. If `reason` is `login_required`, ask the user to authorize first; if `purchase_required`, point them to the website to buy the skill or get a membership.

## 4. Download and install

1. Download the ZIP via `GET https://skillon.dev/api/download/<skill-slug>` (with Bearer token).
2. Unzip into the matching agent's skills directory (create it if missing):

- `claude` (Claude Code): `~/.claude/skills/<skill-slug>/`
- `codex` (Codex): `~/.codex/skills/<skill-slug>/`
- `cursor` (Cursor): `~/.cursor/skills/<skill-slug>/`
- `copilot` (GitHub Copilot): `~/.copilot/skills/<skill-slug>/`

3. Ask the user to restart the agent (or reload skills), then speak the skill's trigger phrase to verify. Per-skill trigger phrases and steps: `GET https://skillon.dev/skills/<skill-slug>/install.md`.

## 5. CLI quick reference

```
skillon login                              # browser-authorized login
skillon status                             # check login status
skillon install <skill-slug> --target claude   # install into an agent
```

Available targets: `claude` / `codex` / `cursor` / `copilot`.