back
loading skill details...
Use the included Brickset CLI for LEGO set search/details, images, instructions, reviews, login/user hash, collection, wishlist, and notes with guarded accou...
---
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.
don't have the plugin yet? install it then click "run inline in claude" again.
expanded flat reference into 15 explicit numbered procedure steps with inputs/outputs per step, extracted decision logic into dedicated section, documented all edge cases and auth mechanics, clarified output contract for each operation class, added smoke check guidance and outcome signals
use this skill when a user asks for brickset-backed lego set details, images, building instructions, community reviews, or account workflows such as collection management, wishlist changes, ratings, quantities, and personal notes. the skill wraps the brickset api via a local cli and enforces read-only defaults with explicit user confirmation required before any account mutation. useful for afol (adult fan of lego) queries about set availability, community sentiment, build instructions, and personal collection tracking.
required environment variables:
BRICKSET_API_KEY: brickset api key (obtain from brickset.com/api). never print, commit, or paste real keys.optional environment variables:
BRICKSET_USER_HASH: user account hash from login workflow. preferred over username/password for private/account operations. treat as secret.BRICKSET_USERNAME: lego.com or brickset username, used only for scripts/brickset login. do not store in plaintext.BRICKSET_PASSWORD: lego.com or brickset password, used only for scripts/brickset login. do not store in plaintext.BRICKSET_BASE_URL: override default api endpoint (default: https://brickset.com/api/v3.asmx).checked-in references (all in skill directory):
references/openapi/brickset.yaml: openapi schema for all endpoints.references/prompts/brickset-tools.txt: public read operation guidance.references/prompts/brickset-private-tools.txt: account/private operation guidance.scripts/brickset_cli.py: main cli entrypoint.scripts/brickset: executable bash wrapper.external connections:
POST with application/x-www-form-urlencoded body. apiKey is a form field, not a bearer token or json property. public reads still include empty userHash= form field unless a real user hash is intentionally set.inputs: user request mentioning lego set number, set name, or search query.
step: if user provides a public lego set number (e.g. 10270-1) or set name, run:
scripts/brickset details --set-number 10270-1
# or
scripts/brickset sets --query "Galaxy Explorer"
outputs: json response with setID (brickset internal id), setNumber, name, theme, subtheme, pieces, minifigs, year, rrp, imageUrl, barcodes, dimensions, ratings, review counts, and release status.
edge cases: if set number is ambiguous (e.g. variant years), use sets --params-json '{"theme":"Space","year":2022}' to narrow. if set does not exist, api returns empty result set (do not invent data).
inputs: setNumber (from user or step 1 output).
step: run:
scripts/brickset sets --set-number 10270-1
outputs: as step 1.
inputs: setID (from step 1 or 2 output). this is the brickset internal id, not the public set number.
step: run:
scripts/brickset images --set-id "$SET_ID"
outputs: json array of image objects with url, caption, index, or similar fields per openapi schema.
edge cases: if no extra images exist, api returns empty array. do not pretend images exist if response is empty.
inputs: setNumber (public lego set number, e.g. 10270-1).
step: run:
scripts/brickset instructions --set-number 10270-1
outputs: json with pdf links, instruction codes (BI numbers, version numbers, booklet numbers), and instruction set metadata.
edge cases: if set has no published instructions, response is empty or error status. if instructions endpoint is down or rate-limited, wait and retry. if user asks for "all instruction variants", iterate over booklet numbers in response.
inputs: setID (from step 1 or 2 output).
step: run:
scripts/brickset reviews --set-id "$SET_ID"
outputs: json array of review objects with author, rating, reviewText, date, or similar fields per openapi schema. may also include aggregated rating stats.
edge cases: if no reviews exist, response is empty array. do not invent sentiment. if review count is high, summarize representative reviews (5-10) rather than listing all.
inputs: BRICKSET_USERNAME and BRICKSET_PASSWORD in environment, or user approval to use credentials.
step: only if user explicitly requests account features and has provided or approved credentials, run:
scripts/brickset login
outputs: json with hash (user hash string). store as BRICKSET_USER_HASH in approved secret storage if persistence is requested.
edge cases: if credentials are invalid, api returns error status. if login endpoint is rate-limited, wait 60 seconds and retry. never print hash in logs, prs, or chat. if user has not provided credentials, ask before running this step.
inputs: BRICKSET_USER_HASH in environment (from step 6 or prior session).
step: run:
scripts/brickset collection
outputs: json array of owned sets with setNumber, setID, qty, rating, notes, dateAdded, or similar fields.
edge cases: if user hash is missing or invalid, api returns error status. if collection is very large (1000+ sets), response may be paginated or truncated per openapi schema. if user has not authenticated, offer to run step 6 first.
inputs: BRICKSET_USER_HASH in environment (from step 6 or prior session).
step: run:
scripts/brickset wishlist
outputs: json array of wanted sets with setNumber, setID, dateAdded, or similar fields.
edge cases: if user hash is missing or invalid, api returns error status. if wishlist is empty, response is empty array (do not invent entries).
inputs: BRICKSET_USER_HASH in environment (from step 6 or prior session).
step: run:
scripts/brickset notes
outputs: json array or object with personal notes, possibly per set, with setID, note, dateAdded, or similar fields.
edge cases: if user hash is missing or invalid, api returns error status. if user has not set any notes, response is empty. do not expose raw notes in logs or summaries unless user explicitly asks.
inputs: explicit user confirmation ("yes, add to brickset", "confirm", etc.). setID (from step 1 or 2). qty (optional, default 1).
step: first run dry-run to show the user what will change:
scripts/brickset collection-set --dry-run --set-id "$SET_ID" --own 1 --qty-owned 1
step: only after user confirms the exact output above, run:
scripts/brickset collection-set --yes --set-id "$SET_ID" --own 1 --qty-owned 1
outputs: json with status (success or error message). if error, surface the message and do not retry without user approval.
edge cases: if user hash is missing, api returns error (private operation). if quantity exceeds 99, api may reject (per brickset limits). if set already owned at different quantity, this updates the quantity (not additive). if network timeout, retry once. if user has not authenticated, offer step 6 first.
inputs: explicit user confirmation ("yes, remove from brickset", "confirm", etc.). setID.
step: dry-run first:
scripts/brickset collection-set --dry-run --set-id "$SET_ID" --own 0
step: after confirmation:
scripts/brickset collection-set --yes --set-id "$SET_ID" --own 0
outputs: json with status.
edge cases: if set is not currently owned, api may error or succeed silently (check openapi spec). if network timeout, retry once.
inputs: explicit user confirmation. setID.
step: dry-run:
scripts/brickset collection-set --dry-run --set-id "$SET_ID" --want 1
step: after confirmation:
scripts/brickset collection-set --yes --set-id "$SET_ID" --want 1
outputs: json with status.
edge cases: if set is already wishlisted, api may error or succeed silently. if network timeout, retry once.
inputs: explicit user confirmation. setID.
step: dry-run:
scripts/brickset collection-set --dry-run --set-id "$SET_ID" --want 0
step: after confirmation:
scripts/brickset collection-set --yes --set-id "$SET_ID" --want 0
outputs: json with status.
edge cases: if set is not currently wishlisted, api may error or succeed silently.
inputs: explicit user confirmation restating exact changes (e.g. "update rating to 5, add note 'incomplete'"). setID. optional: qty, notes (max 1000 chars per brickset spec), rating (1-5 integer).
step: dry-run:
scripts/brickset collection-set --dry-run --set-id "$SET_ID" --qty-owned 2 --notes "placeholder" --rating 5
step: after confirmation:
scripts/brickset collection-set --yes --set-id "$SET_ID" --qty-owned 2 --notes "placeholder" --rating 5
outputs: json with status.
edge cases: if notes exceed 1000 chars, api rejects. if rating is outside 1-5, api rejects. if user provides only qty-owned without --own 1, api may interpret as wishlist-only change (check openapi). if network timeout, retry once.
inputs: user request to add/update a set without naming brickset or rebrickable.
step: ask user which service: "add to brickset collection or rebrickable inventory?" do not mutate until user picks one.
outputs: clarification, no api call yet.
if user provides a set number and needs images or reviews: resolve setID via step 1 or 2 first, then use setID for step 3 or 5. the instructions endpoint is the exception and takes setNumber directly (step 4).
if user asks for collection/wishlist/notes without prior authentication: offer to run step 6 (login) and set BRICKSET_USER_HASH. do not run steps 7-9 without a user hash in environment.
if user requests a collection mutation without explicit confirmation: run dry-run (step 10-14) and restate the exact change (set name, quantity, notes, rating, owned/wanted state). wait for explicit "yes" or "confirm" before running with --yes flag.
if user asks to add to collection without naming brickset: run step 15 to clarify (brickset vs rebrickable). do not mutate either service until user picks one.
if api returns error status: surface the error message exactly and stop. do not retry or invent success. if error is transient (rate limit, timeout), offer to retry after 60 seconds.
if api response is empty (no results, no reviews, no images, empty collection): report that explicitly (e.g. "no reviews for this set yet"). do not pretend data exists.
if user hash is expired or invalid: offer to re-run step 6 (login) to refresh BRICKSET_USER_HASH.
if user provides credentials via env vars and asks for account operations: use them. if user does not provide credentials and asks for account operations, offer step 6 first.
public read operations (steps 1-5):
private read operations (steps 6-9):
mutation operations (steps 10-14):
smoke checks:
python3 -m py_compile scripts/brickset_cli.py returns exit 0.scripts/brickset collection-set --dry-run --set-id 30142 --own 1 --qty-owned 1 outputs request shape with credentials redacted.BRICKSET_API_KEY): scripts/brickset details --set-number 10270-1 returns set details.BRICKSET_USER_HASH): scripts/brickset notes returns notes count or empty array.user knows the skill worked when:
BRICKSET_USER_HASH for future use.no data is leaked: real api keys, user hashes, passwords, collection contents, or personal notes do not appear in logs, prs, task summaries, or chat unless user explicitly asks for that.
credits: original skill by musketyr (clawhub). enriched with explicit procedure steps, decision logic, edge cases, and output contracts per implexa quality standards.