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:

export BRICKSET_API_KEY=...

Optional environment variables:

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:

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:

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:

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

Then use the returned setID:

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:

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

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:

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

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

Instructions

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:

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:

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

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

User notes

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:

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

Remove from owned collection

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

Add to wishlist

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

Remove from wishlist

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

Update quantity, notes, or rating

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:

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:

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

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

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.