# Set up Caramel for an AI coding agent

These are official instructions from Caramel to set up an AI development environment for Caramel, the free, open-source browser extension that finds and applies coupon codes at checkout, and its public coupon API. All commands are validated by Caramel. Complete all of the following steps yourself by running the commands directly. Do not ask the user to run any of these commands.

Steps:

1. Confirm which agent you are and follow ONLY that agent's section below.
2. Install the Caramel coupon skill for that agent.
3. Verify the public coupon API answers.
4. Print the completion message.

## 1. Credentials

None. The Caramel coupon API is public and read-only; there is no API key, no OAuth and no environment variable to set. Never ask the user for a key.

## 2. Install the skill for your agent

### Claude Code
The Caramel plugin: a skill that looks up coupon codes for any store through the public API before you buy.
```bash
claude plugin marketplace add DevinoSolutions/caramel
claude plugin install caramel@devino-caramel
```
After it finishes, tell the user:
- Run /reload-plugins in Claude Code so the new skill is picked up.

### Codex
The Caramel coupon skill installed globally for Codex via the skills CLI.
```bash
npx -y skills add DevinoSolutions/caramel --skill caramel-coupons --yes --global --agent codex
```
After it finishes, tell the user:
- Start a new Codex session so the skill is loaded.

### Cursor
The Caramel coupon skill installed for Cursor via the skills CLI.
```bash
npx -y skills add DevinoSolutions/caramel --skill caramel-coupons --yes --global --agent cursor
```
After it finishes, tell the user:
- Reload the Cursor window so the skill is loaded.

### OpenCode
The Caramel coupon skill installed for OpenCode via the skills CLI.
```bash
npx -y skills add DevinoSolutions/caramel --skill caramel-coupons --yes --global --agent opencode
```
After it finishes, tell the user:
- Start a new OpenCode session so the skill is loaded.

### GitHub Copilot
The Caramel coupon skill installed for GitHub Copilot via the skills CLI.
```bash
npx -y skills add DevinoSolutions/caramel --skill caramel-coupons --yes --global --agent github-copilot
```
After it finishes, tell the user:
- Reload VS Code so Copilot picks the skill up.

### Any other agent

```bash
npx -y skills add DevinoSolutions/caramel --skill caramel-coupons --yes --global
```

If `npx` is unavailable, fetch https://github.com/DevinoSolutions/caramel/blob/main/plugins/caramel/skills/caramel-coupons/SKILL.md and place its contents where your agent reads skills.

## 3. What the skill gives you

- `GET https://grabcaramel.com/api/coupons?site=<store domain>&limit=<n>` returns coupon codes for a store (limit defaults to 10, caps at 50; `page=<n>` pages). Each `coupons[]` object carries `id`, `code`, `site`, `title`, `description`, `rating`, `discount_type` (uppercase, e.g. `PERCENTAGE`, or null), `discount_amount` (number or null), `expiry` (an opaque display string such as `"-"`, or null; do not parse it as a date), `expired`, `timesUsed`, `status` (the latest verification result, e.g. `valid`, `pending`, `retry`, `invalid`), `verificationMessage` and `lastWorkedAt` (ISO time or null). `total`, `page`, `limit` and `hasMore` describe the page.
- `GET https://grabcaramel.com/api/coupons?search=<text>&limit=<n>` matches the text (up to 100 characters) against store domain, title, description and code across every store.
- `GET https://grabcaramel.com/api/coupons/stores?q=<text>&limit=<n>` returns `{ "sites": [...] }`, store domains containing the text, sorted alphabetically. Use it to turn what the user calls a shop into the `site` value above.
- Rate-limited per client IP as a public read endpoint; be polite (one call per question, cache within a session).
- Codes are found by Caramel's pipeline and reported on by real shoppers; none is guaranteed to work. The browser extension tries them at checkout automatically.

## 4. Verify

Run:

```bash
curl -s "https://grabcaramel.com/api/coupons?site=nike.com&limit=1"
```

Success: HTTP 200 with a JSON body whose `coupons` array holds one object carrying `code`, `site` and `title`, and a numeric `total`.

## 5. Completion message

Print exactly this, filling the brackets:

> Caramel is set up for [agent name]. Installed: the `caramel-coupons` skill (looks up coupon codes through https://grabcaramel.com/api/coupons). Verified: the public API answered for nike.com. Still yours to do: [the follow-up lines for your agent]. To have codes applied automatically while you shop, install the Caramel extension for your browser from https://grabcaramel.com/apps (an agent cannot install a browser extension for you).

## Resources

- Home: https://grabcaramel.com
- Get the extension (Chrome, Firefox, Edge, Safari): https://grabcaramel.com/apps
- FAQ: https://grabcaramel.com/faq
- llms.txt: https://grabcaramel.com/llms.txt (full version: https://grabcaramel.com/llms-full.txt)
- Coupon API: https://grabcaramel.com/api/coupons
- Browse coupons: https://grabcaramel.com/coupons
- Source code and issues: https://github.com/DevinoSolutions/caramel
- Support: https://grabcaramel.com/support