AFOL BrickOwl

use this skill when the user asks for brickowl catalog lookup, brickowl store inventory, brickowl orders, brickowl wishlist creation, or brickowl marketplace listing management. the skill wraps the brickowl api directly through a checked-in cli and enforces explicit confirmation before any write operation.

intent

this skill provides read-only and write-safe access to the brickowl api for afol (adult fan of lego) inventory, order, catalog, and wishlist operations. use it when you need to search the brickowl catalog, inspect your own inventory or orders, create wishlists, or safely list/update/delete marketplace lots. the primary interface is a cli that handles auth splitting (query params for get, form body for post) and guards all mutations behind explicit --yes flags and dry-run preview.

inputs

required environment variable:

export BRICKOWL_API_KEY=<your-api-key>

optional override:

export BRICKOWL_BASE_URL=https://api.brickowl.com/v1

referenced files checked into this skill:

• openapi spec: references/openapi/brickowl.yaml
• domain guidance: references/prompts/brickowl-tools.txt
• cli source: scripts/brickowl_cli.py
• executable: scripts/brickowl

never print, commit, log, or paste the real api key. all commands reference $BRICKOWL_API_KEY indirectly through the cli.

brickowl auth placement (handled by cli):

• get endpoints: key as query parameter.
• post endpoints: key in application/x-www-form-urlencoded body.

procedure

1. read-only catalog and order queries

inputs: query terms, external ids, or order ids.

step 1a: user catalog search by text

• run scripts/brickowl catalog-search --query "<text>" --type Set --page 1
• output: json array of matching catalog entries with boid, name, description.

step 1b: user id lookup by known external id

• run scripts/brickowl id-lookup --id "<id>" --type Set --id-type set_number (or use item_no, design_id, bl_item_no as id-type)
• output: single catalog entry or not found.

step 1c: user lists own inventory

• run scripts/brickowl inventory-list --page 1
• output: json array of user's own lots with lot_id, boid, quantity, price, condition, listed_date.

step 1d: user views own orders

• run scripts/brickowl orders --status Pending --page 1 (optional status filter)
• output: json array of orders with order_id, buyer, total, date, status.

step 1e: user views single order details

• run scripts/brickowl order --order-id <order_id>
• output: single order with line items, addresses, and notes.

step 1f: user views account info

• run scripts/brickowl user
• output: authenticated user's profile data (store name, email, feedback rating).

2. create an inventory lot (mutation)

inputs: boid (required), quantity (required, integer), price (required, decimal), condition (required, lowercase id: news, newc, newi, usedc, usedi, usedn, usedg, useda, other), optional color_id, optional external_id.

step 2a: state back exact action

• restate to user: "confirm brickowl inventory create: boid , quantity , price , condition , optional color_id , optional external_id ."
• wait for explicit confirmation (e.g., "yes, create it").

step 2b: preview with dry run

• run scripts/brickowl inventory-create --dry-run --boid "$BOID" --quantity "$QUANTITY" --price "$PRICE" --condition "$CONDITION"
• output: request shape with api key redacted.
• show result to user for final check.

step 2c: execute on confirmation

• run scripts/brickowl inventory-create --yes --boid "$BOID" --quantity "$QUANTITY" --price "$PRICE" --condition "$CONDITION"
• output: response with new lot_id and external_lot_id.

3. update an inventory lot (mutation)

inputs: lot_id or external_lot_id (one required), plus fields to change (price, absolute_quantity, relative_quantity, condition, color_id, etc).

step 3a: state back exact action

• restate: "confirm brickowl lot update: lot_id or external_lot_id ; changes: =, ..."
• wait for explicit confirmation.

step 3b: preview with dry run

• run scripts/brickowl inventory-update --dry-run --lot-id "$LOT_ID" --price "$PRICE" (or --absolute-quantity or --relative-quantity for quantity changes)
• output: request shape with api key redacted.

step 3c: execute on confirmation

• run scripts/brickowl inventory-update --yes --lot-id "$LOT_ID" --price "$PRICE"
• output: response confirming update.

4. delete an inventory lot (mutation)

inputs: lot_id or external_lot_id.

step 4a: state back exact action

• restate: "confirm brickowl lot deletion: lot_id . this is permanent."
• wait for explicit confirmation naming the lot id.

step 4b: preview with dry run

• run scripts/brickowl inventory-delete --dry-run --lot-id "$LOT_ID"
• output: request shape.

step 4c: execute on confirmation

• run scripts/brickowl inventory-delete --yes --lot-id "$LOT_ID"
• output: response confirming deletion or error.

5. create a wishlist (mutation)

inputs: wishlist name (required), description (optional).

step 5a: state back exact action

• restate: "confirm brickowl wishlist creation: name "", description ""."
• wait for explicit confirmation.

step 5b: preview with dry run

• run scripts/brickowl wishlist-create --dry-run --name "$WISHLIST_NAME" --description "$WISHLIST_DESCRIPTION"
• output: request shape.

step 5c: execute on confirmation

• run scripts/brickowl wishlist-create --yes --name "$WISHLIST_NAME" --description "$WISHLIST_DESCRIPTION"
• output: response with new wishlist_id.

6. bulk requests (mutation)

inputs: json array of request objects, each with path (required) and optional method, body.

step 6a: inspect each embedded request

• scan requests for post endpoints (inventory/, wishlist/, or other mutations).
• identify all write requests (anything post to inventory or wishlist endpoints).

step 6b: if any mutations present, state back action

• restate each mutating request by name and target (e.g., "post to /inventory/create with boid 123456").
• wait for explicit confirmation of the whole batch.

step 6c: preview with dry run

• run scripts/brickowl bulk --dry-run --requests-json "$BULK_REQUESTS_JSON"
• output: request shape with api key redacted.

step 6d: execute on confirmation

• run scripts/brickowl bulk --yes --requests-json "$BULK_REQUESTS_JSON"
• output: array of responses (one per request).

note: bulk has a lower rate limit (200 requests/minute). do not hide writes inside bulk; always summarize them upfront.

decision points

if user has brickowl api key configured:

• proceed with any read-only command.
• for mutations, require explicit conversation confirmation before --yes.

if user lacks brickowl api key:

• halt and ask user to set export BRICKOWL_API_KEY=....
• do not attempt read-only commands.

if user asks to list, sell, update inventory, or delete lot without naming a platform:

• ask which marketplace (brickowl or bricklink) before mutating anything.
• do not assume brickowl.

if user asks for current marketplace prices or cross-seller offers on brickowl:

• explain that brickowl api does not provide marketplace offer data from other sellers.
• suggest bricklink pricing if available, or direct user to brickowl.com for manual browsing.

if user asks to bulk-update many lots or create many inventory entries:

• confirm whether bulk endpoint is appropriate (200 requests/minute limit) or suggest sequential single operations.

if api returns rate-limit error (429):

• inform user and suggest waiting before retry.
• for bulk, reduce batch size and retry.

if api returns auth error (401):

• inform user that api key is invalid or expired.
• ask user to verify $BRICKOWL_API_KEY and regenerate if needed.

if api returns network timeout or connection refused:

• inform user and suggest checking internet connection or base url override.
• do not retry automatically.

if user passes incomplete mutation parameters (missing boid, quantity, price, or condition):

• halt and ask for missing fields.
• do not proceed to dry run or confirmation.

if user tries to pass plain New as condition for inventory-create:

• reject and list valid lowercase condition ids: news, newc, newi, usedc, usedi, usedn, usedg, useda, other.

if dry-run shows unexpected request shape:

• halt, show user the redacted preview, and ask to re-confirm parameters.

if user answers confirmation prompt with anything other than explicit "yes" or "confirm":

• treat as refusal and do not execute mutation.

output contract

all read-only commands output json (valid or parse error) to stdout.

all mutations output json response (success or api error) to stdout only after --yes is passed.

all dry-run commands output redacted request shape (no api key) to stdout.

treat inventory, order, buyer, address, cost, and personal-note data as private. summarize only what the user needs (e.g., "lot_id 12345 listed at $49.99, quantity 2, new condition" instead of all extended fields).

successful inventory create returns lot_id and external_lot_id. successful inventory update returns updated lot record. successful inventory delete returns confirmation message or empty response. successful wishlist create returns list_id and list_name.

on api error, output json with error key and http status. do not retry automatically.

outcome signal

user knows the skill worked when:

1. read-only queries: json results appear on stdout matching the user's query (catalog search returns entries, inventory list shows lots, order view shows details, user profile shows account).

2. inventory create: user receives a new lot_id and external_lot_id. lot appears in inventory-list on next refresh.

3. inventory update: user receives confirmation with updated fields (new price, new quantity, etc.). next inventory-list refresh shows changes.

4. inventory delete: user receives confirmation message. lot no longer appears in inventory-list.

5. wishlist create: user receives a new list_id. wishlist appears in user's brickowl.com account.

6. bulk requests: user receives an array of responses. any embedded mutations show successful json responses. no silent drops or partial failures.

7. dry-run preview: user sees the request shape (method, path, redacted body) without execution. no api call made.

8. confirmation prompt: user receives exact restatement of action (lot id, quantity, price, condition, etc.) and must say "yes" or "confirm" to proceed.

9. api errors: user sees json error response with error key and appropriate http status (401 for auth, 404 for not found, 429 for rate limit, etc.).