AFOL Brickset

SKILL.md

---
name: brickset
description: Use the included Brickset CLI for LEGO set search/details, images, instructions, reviews, login/user hash, collection, wishlist, and notes with guarded account writes.
version: 1.0.0
---

# Brickset AFOL skill

Use this skill when a user asks for Brickset-backed LEGO set details, extra images, building instructions, community reviews, or explicit Brickset account workflows such as collection, wishlist, ratings, quantities, and personal notes.

Primary interface: `scripts/brickset`.

The skill is self-contained for archive distribution and wraps the Brickset API directly using checked-in references inside this skill directory:
- OpenAPI reference: `references/openapi/brickset.yaml`
- Public prompt guidance: `references/prompts/brickset-tools.txt`
- Private prompt guidance: `references/prompts/brickset-private-tools.txt`
- CLI source: `scripts/brickset_cli.py`

Do not scrape Brickset vendor docs or invent parameters when these checked-in references answer the endpoint shape. If the reference is insufficient, say exactly what is missing.

## Authentication

Required environment variable for all Brickset calls:

```bash
export BRICKSET_API_KEY=...
```

Optional environment variables:

```bash
export BRICKSET_USER_HASH=...      # preferred for private/account workflows
export BRICKSET_USERNAME=...       # only for `scripts/brickset login`
export BRICKSET_PASSWORD=...       # only for `scripts/brickset login`
export BRICKSET_BASE_URL=https://brickset.com/api/v3.asmx
```

Never print, commit, log, or paste real API keys, passwords, or user hashes. Prefer `BRICKSET_USER_HASH` over username/password once available.

Brickset auth placement matters:
- Every verified API operation is `POST`.
- The request body is `application/x-www-form-urlencoded`.
- `apiKey` is a form field, not JSON and not an HTTP bearer token.
- Public read calls still send `userHash=` as an empty form field unless a real `BRICKSET_USER_HASH` is intentionally used.
- Complex filters and collection mutations go in a `params` form field whose value is a JSON string.

The CLI handles that shape, which is the main reason to use it instead of ad-hoc curl.

## CLI quick reference

Run commands from this skill directory:

```bash
scripts/brickset --help
scripts/brickset sets --set-number 10270-1
scripts/brickset details --set-number 10270-1
scripts/brickset images --set-id 30142
scripts/brickset instructions --set-number 10270-1
scripts/brickset reviews --set-id 30142
scripts/brickset login
scripts/brickset collection
scripts/brickset wishlist
scripts/brickset notes
```

Private read commands (`collection`, `wishlist`, `notes`, or `sets --owned/--wanted`) require `BRICKSET_USER_HASH`.

Mutating commands are guarded. They do nothing unless passed `--yes`; use `--dry-run` first:

```bash
scripts/brickset collection-set --dry-run --set-id 30142 --own 1 --qty-owned 1
scripts/brickset collection-set --dry-run --set-id 30142 --want 1
scripts/brickset collection-set --dry-run --set-id 30142 --notes "placeholder note" --rating 5
```

## Safety rules

Read-only by default:
- `sets`
- `details`
- `images`
- `instructions`
- `reviews`
- `login` (authentication only; treat the returned hash as secret)
- `collection`
- `wishlist`
- `notes`

Mutating operations require explicit user confirmation in the current conversation before execution:
- `collection-set --own 1` or `--own 0`
- `collection-set --want 1` or `--want 0`
- `collection-set --qty-owned ...`
- `collection-set --notes ...`
- `collection-set --rating ...`
- `collection-set --params-json ...` whenever it changes account state

Stored credentials are not permission. Before any mutation, restate the exact Brickset account change, set identifier, quantity, wishlist/owned state, rating, and notes, then wait for explicit confirmation such as "yes, add it to Brickset" or "confirm rating update".

The CLI enforces this mechanically: mutating commands fail unless `--yes` is passed, and `--dry-run` prints the request shape with credentials redacted.

If the user asks to "add to my collection" without naming a provider and both Brickset/Rebrickable could apply, ask which provider to use before mutating anything.

## Endpoint coverage

- `POST /getSets` via `sets`, `details`, `collection`, and `wishlist`
- `POST /getAdditionalImages` via `images`
- `POST /getInstructions2` via `instructions`
- `POST /getReviews` via `reviews`
- `POST /login` via `login`
- `POST /setCollection` via `collection-set --yes`
- `POST /getUserNotes` via `notes`

Treat collection, wishlist, rating, quantity, and personal-note data as private. Summarize only what the user needs.

## Brickset setID rule

Brickset set numbers and internal set IDs are not interchangeable.

Use `details` or `sets` first when the user gives a public set number and you need a Brickset internal `setID` for images, reviews, or account writes:

```bash
scripts/brickset details --set-number 10270-1
```

Then use the returned `setID`:

```bash
scripts/brickset images --set-id "$SET_ID"
scripts/brickset reviews --set-id "$SET_ID"
scripts/brickset collection-set --dry-run --set-id "$SET_ID" --own 1
```

`instructions` is the exception in this checked-in OpenAPI reference: it uses the public set number directly:

```bash
scripts/brickset instructions --set-number 10270-1
```

Do not convert form calls to JSON requests. That is the classic foot-gun here.

## Public read workflows

### Search/details

```bash
scripts/brickset sets --set-number 10270-1
scripts/brickset sets --query "Galaxy Explorer"
scripts/brickset sets --params-json '{"theme":"Space","year":2022}'
```

Use `details --set-number` for the common exact-set lookup. Responses include Brickset metadata such as theme, subtheme, pieces, minifigs, release status, ratings, review counts, images, barcodes, dimensions, LEGO.com pricing, and the internal `setID` when available.

### Images

Resolve `setID` with `details`, then:

```bash
scripts/brickset images --set-id "$SET_ID"
```

Use for extra photos, alternate angles, box backs, detail shots, or images beyond the main thumbnail.

### Instructions

```bash
scripts/brickset instructions --set-number 10270-1
```

Return PDF links and explain instruction codes when helpful: BI numbers, version numbers, and booklet numbers.

### Reviews and opinions

When the user asks for opinions, community feedback, ratings, whether a set is good, or whether it is worth buying, use Brickset reviews before pricing tools.

Resolve `setID` with `details`, then:

```bash
scripts/brickset reviews --set-id "$SET_ID"
```

Summarize real review text and star ratings. Do not invent sentiment if there are no reviews.

## Private read workflows

### Obtain a user hash

Only use `login` when private workflows require it and the user has explicitly provided or approved credential use through environment variables:

```bash
scripts/brickset login
```

The response contains `hash`. Store it as `BRICKSET_USER_HASH` in approved secret storage if persistence is requested. Never commit it or paste it in a PR/comment.

### Collection and wishlist reads

```bash
scripts/brickset collection
scripts/brickset wishlist
scripts/brickset sets --owned 1
scripts/brickset sets --wanted 1
```

### User notes

```bash
scripts/brickset notes
```

Use for personal set notes and note-backed collection context.

## Mutating workflows

Do not run these with `--yes` until the user explicitly confirms the exact action.

### Add to owned collection

After explicit intent and `setID` resolution:

```bash
scripts/brickset collection-set --yes --set-id "$SET_ID" --own 1 --qty-owned 1
```

### Remove from owned collection

```bash
scripts/brickset collection-set --yes --set-id "$SET_ID" --own 0
```

### Add to wishlist

```bash
scripts/brickset collection-set --yes --set-id "$SET_ID" --want 1
```

### Remove from wishlist

```bash
scripts/brickset collection-set --yes --set-id "$SET_ID" --want 0
```

### Update quantity, notes, or rating

```bash
scripts/brickset collection-set --yes --set-id "$SET_ID" --qty-owned 2 --notes "placeholder note" --rating 5
```

Keep notes under Brickset's documented limit from the verified spec guidance: 1000 characters. Rating is 1-5.

## Live smoke checks

Local, no-network checks:

```bash
python3 -m py_compile scripts/brickset_cli.py
scripts/brickset collection-set --dry-run --set-id 30142 --own 1 --qty-owned 1
```

Read-only live smoke check, only when `BRICKSET_API_KEY` is configured:

```bash
scripts/brickset details --set-number 10270-1
```

If `BRICKSET_USER_HASH` is configured, private read smoke checks are allowed:

```bash
scripts/brickset notes
```

Summarize only response shape/counts/status. Do not paste private notes, collection contents, credentials, hashes, or user profile data into logs, PRs, task summaries, or chat.

Never use `collection-set --yes` as a smoke test unless the user explicitly asks for that real Brickset account mutation.

## Response guidance

- Mention Brickset as the source when returning review, instruction, image, or collection data.
- For opinion questions, cite/summarize Brickset reviews first before switching to price/value analysis.
- For images and instructions, return direct URLs when the API provides them.
- For collection/wishlist writes, report exactly what service was changed: Brickset collection or Brickset wishlist.
- If an API response has `status: error`, surface the message and stop rather than pretending the operation succeeded.