AFOL Rebrickable

Use the Rebrickable API through the included CLI for LEGO catalog lookup, user set/part lists, build analysis, lost parts, and guarded collection writes.

installs

stars

karma

SkillRank score ↗

8.4/ 10

evaluated by implexa, claude-haiku-4-5 · 2026-06-20

afol-rebrickable wraps the rebrickable api via cli for lego catalog queries, user collection management, build analysis, and lost-parts tracking. read-only by default, mutations require explicit user confirmation and dry-run verification.

structure

9.0

trigger phrases

9.0

procedure

9.0

edge cases

7.0

documentation

8.0

strengths

view original SKILL.md from clawhubclick to expand

---
name: rebrickable
description: Use the Rebrickable API through the included CLI for LEGO catalog lookup, user set/part lists, build analysis, lost parts, and guarded collection writes.
version: 1.0.0
---

# Rebrickable AFOL skill

Use this skill when the user asks for Rebrickable catalog lookup, Rebrickable set or part list management, user collection analysis, buildability checks, minifigs from owned sets, all-parts inventory, or lost-parts tracking.

Primary interface: `scripts/rebrickable`.

The skill is self-contained for archive distribution and wraps the Rebrickable API directly using checked-in references inside this skill directory:
- OpenAPI reference: `references/openapi/rebrickable.yaml`
- Domain guidance: `references/prompts/rebrickable-tools.txt`
- CLI source: `scripts/rebrickable_cli.py`

Do not scrape vendor docs or invent parameters when the checked-in OpenAPI reference covers the endpoint. If the reference is insufficient, say what is missing.

## Authentication

Required environment variable:

```bash
export REBRICKABLE_API_KEY=...
```

Optional environment variables:

```bash
export REBRICKABLE_USER_TOKEN=...       # needed for user collection endpoints
export REBRICKABLE_BASE_URL=https://rebrickable.com/api/v3
```

Never print, commit, log, or paste real API keys or user tokens. Commands should reference credentials only indirectly through the CLI.

Rebrickable auth placement matters: API authentication goes in the `Authorization` header as `key <REBRICKABLE_API_KEY>`. The CLI handles that header and redacts it in dry runs.

User-specific endpoints include the user token in the URL path. Treat `REBRICKABLE_USER_TOKEN` as private even though it is not the API key.

## CLI quick reference

Run commands from this skill directory:

```bash
scripts/rebrickable --help
scripts/rebrickable colors --page-size 5
scripts/rebrickable sets --search "Millennium Falcon" --page-size 5
scripts/rebrickable set --set-num 75192-1
scripts/rebrickable set-parts --set-num 75192-1 --page-size 20
scripts/rebrickable parts --part-num 3001
scripts/rebrickable element --element-id 300121
scripts/rebrickable minifigs --search "Darth Vader" --page-size 5
scripts/rebrickable part-categories --page-size 20
scripts/rebrickable themes --page-size 20
```

User read-only examples, only when `REBRICKABLE_USER_TOKEN` is configured or passed with `--user-token`:

```bash
scripts/rebrickable profile
scripts/rebrickable set-lists
scripts/rebrickable set-list-sets --list-id 123
scripts/rebrickable all-sets --search "Star Wars" --page-size 20
scripts/rebrickable part-lists
scripts/rebrickable part-list-parts --list-id 456 --page-size 20
scripts/rebrickable all-parts --part-num 3001 --page-size 20
scripts/rebrickable all-minifigs --search "astromech" --page-size 20
scripts/rebrickable build --set-num 8043-1
scripts/rebrickable lost-parts --page-size 20
```

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

```bash
scripts/rebrickable create-set-list --dry-run --name "Wanted builds" --is-buildable true
scripts/rebrickable add-sets-to-list --dry-run --list-id 123 --sets-json '[{"set_num":"8043-1","quantity":1}]'
scripts/rebrickable update-set-in-list --dry-run --list-id 123 --set-num 8043-1 --quantity 2
scripts/rebrickable remove-set-from-list --dry-run --list-id 123 --set-num 8043-1
scripts/rebrickable create-part-list --dry-run --name "Missing dark bluish gray"
scripts/rebrickable add-part-to-list --dry-run --list-id 456 --part-num 3001 --color-id 72 --quantity 4
scripts/rebrickable update-part-in-list --dry-run --list-id 456 --part-num 3001 --color-id 72 --quantity 8
scripts/rebrickable remove-part-from-list --dry-run --list-id 456 --part-num 3001 --color-id 72
scripts/rebrickable add-lost-part --dry-run --inv-part-id 806698 --lost-quantity 1
scripts/rebrickable remove-lost-part --dry-run --lost-part-id 999
```

## Safety rules

Read-only by default:
- public catalog commands: `colors`, `color`, `element`, `minifigs`, `minifig`, `minifig-parts`, `minifig-sets`, `part-categories`, `part-category`, `parts`, `part`, `part-colors`, `part-color`, `part-color-sets`, `sets`, `set`, `set-parts`, `set-minifigs`, `set-alternates`, `themes`, `theme`
- user read commands: `profile`, `set-lists`, `set-list`, `set-list-sets`, `all-sets`, `part-lists`, `part-list-parts`, `all-parts`, `all-minifigs`, `build`, `lost-parts`

Mutating operations require explicit user confirmation in the current conversation before execution:
- `create-set-list`, `update-set-list`, `delete-set-list`
- `add-sets-to-list`, `update-set-in-list`, `remove-set-from-list`
- `create-part-list`, `delete-part-list`
- `add-part-to-list`, `update-part-in-list`, `remove-part-from-list`
- `add-lost-part`, `remove-lost-part`

Stored credentials are not permission. Before any mutation, restate the exact platform, list ID, set number, part number, color ID, quantity, lost-part record, and whether the operation creates, updates, or deletes data. Wait for explicit confirmation such as "yes, add set 8043-1 to Rebrickable list 123".

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

If the user asks to "add to my collection" or "show my collection" without naming a platform and Brickset/Rebrickable are both configured, ask which service to use before mutating or reading private collection data. If they explicitly name Rebrickable, use only Rebrickable.

## Endpoint coverage

Catalog coverage:
- `GET /lego/colors/` and `GET /lego/colors/{id}/`
- `GET /lego/elements/{element_id}/`
- `GET /lego/minifigs/`, `GET /lego/minifigs/{set_num}/`, `GET /lego/minifigs/{set_num}/parts/`, `GET /lego/minifigs/{set_num}/sets/`
- `GET /lego/part_categories/` and `GET /lego/part_categories/{id}/`
- `GET /lego/parts/`, `GET /lego/parts/{part_num}/`, `GET /lego/parts/{part_num}/colors/`, `GET /lego/parts/{part_num}/colors/{color_id}/`, `GET /lego/parts/{part_num}/colors/{color_id}/sets/`
- `GET /lego/sets/`, `GET /lego/sets/{set_num}/`, `GET /lego/sets/{set_num}/parts/`, `GET /lego/sets/{set_num}/minifigs/`, `GET /lego/sets/{set_num}/alternates/`
- `GET /lego/themes/` and `GET /lego/themes/{id}/`

User coverage:
- `GET /users/{user_token}/profile/`
- `GET/POST /users/{user_token}/setlists/`
- `GET/PATCH/DELETE /users/{user_token}/setlists/{list_id}/`
- `GET/POST /users/{user_token}/setlists/{list_id}/sets/`
- `GET/PATCH/DELETE /users/{user_token}/setlists/{list_id}/sets/{set_num}/`
- `GET /users/{user_token}/sets/`
- `GET /users/{user_token}/partlists/`
- `POST /users/{user_token}/partlists/`
- `DELETE /users/{user_token}/partlists/{list_id}/`
- `GET/POST /users/{user_token}/partlists/{list_id}/parts/`
- `PUT/DELETE /users/{user_token}/partlists/{list_id}/parts/{part_num}/{color_id}/`
- `GET /users/{user_token}/parts/`
- `GET /users/{user_token}/allparts/`
- `GET /users/{user_token}/minifigs/`
- `GET /users/{user_token}/build/{set_num}/`
- `GET/POST /users/{user_token}/lost_parts/`
- `DELETE /users/{user_token}/lost_parts/{id}/`

Treat set-list names, part-list names, owned sets, part inventories, build analysis, lost parts, emails, and profile data as private. Summarize only what the user needs.

## Known Rebrickable endpoint quirks

Use `sets --search` for fuzzy set lookup, but use `set --set-num` when the user gives an exact Rebrickable set number:

```bash
scripts/rebrickable set --set-num 75192-1
scripts/rebrickable sets --search "Millennium Falcon" --page-size 5
```

When adding sets to a set list, Rebrickable requires a JSON array even for a single set. The CLI validates this before sending the request:

```bash
scripts/rebrickable add-sets-to-list --dry-run --list-id 123 --sets-json '[{"set_num":"8043-1","quantity":1}]'
```

The `all-parts` endpoint is explicitly resource-intensive in the checked-in OpenAPI reference. Use filters such as `--part-num`, `--part-cat-id`, `--color-id`, and small `--page-size` values whenever possible.

`update-set-in-list` updates only the specified set in the specified list. Rebrickable also has broader `/users/{user_token}/sets/{set_num}/` semantics that can create or delete based on quantity; this CLI intentionally does not expose that broader mutation because it is too easy to misuse.

## Live smoke checks

Only run live smoke checks when `REBRICKABLE_API_KEY` is configured. Summarize response shape only, never private field values.

Public read-only smoke:

```bash
scripts/rebrickable sets --search "Millennium Falcon" --page-size 1
```

Optional private read-only smoke, only when `REBRICKABLE_USER_TOKEN` is configured and the user context permits private collection reads:

```bash
scripts/rebrickable profile
scripts/rebrickable set-lists --page-size 1
```

Do not run mutation smoke tests against the live API. Use `--dry-run` for write-shape verification.

## Verification

Local, no-network checks:

```bash
python3 -m py_compile scripts/rebrickable_cli.py
scripts/rebrickable add-sets-to-list --dry-run --user-token dummy --list-id 123 --sets-json '[{"set_num":"8043-1","quantity":1}]'
python3 -m unittest discover -s tests -p 'test_*.py'
scripts/validate-skills.sh
git diff --check
```

don't have the plugin yet? install it then click "run inline in claude" again.

added explicit decision points for platform disambiguation, search strategy, resource-intensive endpoints, missing credentials, error handling and rate limits; clarified inputs with env var names and rate limits; broke procedure into 7 numbered steps with input/output; added output contract for success and failure cases; expanded outcome signal with mutation confirmations and error reporting.

AFOL Rebrickable

intent

use this skill when a user asks for rebrickable catalog lookup (sets, parts, minifigs, colors, themes), user collection management (set lists, part lists, all-owned inventory), build feasibility checks, lost-parts tracking, or any mutation to rebrickable lists. the skill wraps rebrickable's public and user-authenticated API through a checked-in CLI. read-only queries run by default. mutations require explicit user confirmation and the --yes flag to execute.

inputs

required environment variables:

REBRICKABLE_API_KEY: API key for public catalog access. obtain from https://rebrickable.com/api. never log or commit this value.

optional environment variables:

REBRICKABLE_USER_TOKEN: user authentication token for private collection endpoints (set lists, part lists, owned sets, build analysis, lost parts). treat as sensitive even though it is not the API key. obtain from https://rebrickable.com/api after login.
REBRICKABLE_BASE_URL: defaults to https://rebrickable.com/api/v3. override only for testing or proxied environments.

included references (checked in):

references/openapi/rebrickable.yaml: complete OpenAPI spec for all catalog and user endpoints.
references/prompts/rebrickable-tools.txt: domain guidance for set numbering, color IDs, part categories, and quirks.
scripts/rebrickable_cli.py: CLI source. does not invent parameters beyond the OpenAPI reference.

external service:

rebrickable.com API v3. rate limits: 500 requests per hour per IP or API key (public), 1000 per hour (authenticated). timeouts default to 30 seconds.

procedure

step 1: parse user intent

input: user query.
determine whether the request is read-only (catalog lookup, collection read, build check, lost-parts list) or mutating (create/update/delete list, add/remove items, mark parts lost).
output: intent category (read-only or mutating) and specific command.

step 2: validate environment and credentials

input: required and optional env vars, intent category.
check REBRICKABLE_API_KEY is set. fail if missing.
if intent is mutating or user-specific, check REBRICKABLE_USER_TOKEN is set. if missing, ask user to provide it via --user-token flag or set env var.
output: credentials validated (pass) or credentials missing (fail with guidance).

step 3: for read-only queries, run the CLI command

input: parsed command, set numbers, part numbers, search terms, page sizes, filters.
call scripts/rebrickable <command> <args> from the skill directory.
examples: scripts/rebrickable sets --search "Millennium Falcon" --page-size 5, scripts/rebrickable set --set-num 75192-1, scripts/rebrickable all-parts --part-num 3001 --page-size 10, scripts/rebrickable build --set-num 8043-1, scripts/rebrickable lost-parts --page-size 20.
output: JSON response from Rebrickable API.

step 4: for mutations, obtain explicit confirmation

input: mutation command, target resource (list ID, set number, part number, color ID, quantity, lost-part record).
restate the exact platform (Rebrickable), resource IDs, operation type (create/update/delete), and data being written. wait for user to confirm with "yes" or equivalent.
output: user confirmation received (pass) or user declines (stop).

step 5: for mutations, run with --dry-run first

input: mutation command with --dry-run flag.
call scripts/rebrickable <mutation> <args> --dry-run.
output: dry-run response showing request shape with Authorization header and REBRICKABLE_USER_TOKEN redacted.

step 6: for mutations, execute with --yes

input: mutation command with --yes flag (user already confirmed in step 4).
call scripts/rebrickable <mutation> <args> --yes.
output: mutation response from Rebrickable API.

step 7: parse and summarize response

input: API response (read or mutate).
summarize results: result count, relevant fields (set names, part counts, colors, minifig names, build status, lost-part records), next-page links if pagination applies.
never output email, real user token, API key, or private profile fields. filter to user-relevant data only.
output: human-readable summary.

decision points

if user asks to add/update/remove items without naming a platform (Brickset and Rebrickable both configured):

ask which service to use before proceeding. if user explicitly names Rebrickable, proceed with Rebrickable only.

if user asks for exact set by set number (e.g., "75192-1"):

use scripts/rebrickable set --set-num 75192-1 (direct lookup).
else use scripts/rebrickable sets --search <name> (fuzzy search).

if user requests all-parts endpoint without filters:

warn that this endpoint is resource-intensive. require filters such as --part-num, --part-cat-id, --color-id, and use small --page-size (5-10). if user insists on unfiltered, fail with guidance.

if REBRICKABLE_USER_TOKEN is missing and user requests user-specific data (profile, set-lists, all-parts, build, lost-parts):

ask user to provide token via --user-token <token> or export REBRICKABLE_USER_TOKEN=.... do not proceed without it.

if API returns 401 (Unauthorized):

API key or user token is invalid or expired. ask user to verify credentials. do not retry automatically.

if API returns 429 (Too Many Requests):

rate limit hit. advise user to wait 1 minute and retry. summarize requests in current session to help user plan future queries.

if API returns empty result set (e.g., no sets match search, no owned sets, no lost parts):

report clearly: "no results found for ". do not treat as error.

if network timeout or connection error occurs:

fail with error message. do not retry silently. user may be offline or endpoint unreachable. check REBRICKABLE_BASE_URL if custom.

if user asks to mutate but has not yet confirmed in the current conversation:

restate the exact operation (platform, list ID, set/part/color, quantity, create/update/delete), then wait for explicit yes/no. do not execute until user confirms.

output contract

read-only query success:

HTTP 200 response from Rebrickable API.
JSON data matching OpenAPI schema for the endpoint.
user-facing summary: count, relevant fields, no sensitive values.

mutation (create/update/delete) success:

HTTP 201 (create), 200 (update), 204 (delete) from Rebrickable API.
user-facing confirmation: exact resource (list name, set number, part number, color ID, quantity), operation type, and status (created/updated/deleted).
no API key, user token, or email in output.

dry-run success:

request shape printed with Authorization header redacted as <redacted> and REBRICKABLE_USER_TOKEN path segment redacted.
user can verify request before execution.

failure cases:

400 Bad Request: malformed command, invalid set/part number, invalid JSON. report the error and suggest correction.
401 Unauthorized: bad or missing credentials. ask user to verify API key or user token.
429 Too Many Requests: rate limited. advise wait time.
5xx Server Error: Rebrickable service issue. do not retry; ask user to check https://rebrickable.com status.
network error: report timeout or connection failure. suggest retry and verify REBRICKABLE_BASE_URL.

outcome signal

user knows the skill worked when:

read-only query: results appear on screen with set names, part counts, minifig names, colors, or build status matching the query.
mutation (create): skill confirms "created list '' with ID " or "added set to list " exactly.
mutation (update): skill confirms "updated set in list to quantity " or equivalent.
mutation (delete): skill confirms "removed set from list " or "deleted list " exactly.
dry-run: skill shows request shape and user can compare intent to request before running with --yes.
build check: skill reports buildable sets, missing minifigs, or missing parts with counts.
lost-parts: skill lists lost-part records with part number, color, and quantity.
error: skill reports specific error (401, 429, 400, timeout, empty result) and next action (verify credentials, wait, retry, filter query).

credits: original skill by musketyr. enriched for Implexa standards by clarifying decision points, env var setup, API quirks, rate-limit handling, empty result sets, and mutation confirmation flow.

AFOL Rebrickable

related skills

AFOL Rebrickable

intent

inputs

procedure

decision points

output contract

outcome signal