Kelly Products

Overview

Use this skill as the seller's product-management command desk. It sits between kelly-picks (what to develop), kelly-listing (what copy/assets to publish), kelly-ads (how it performs in paid channels), and kelly-inquiry (what buyers ask). The desk consolidates product master data, SKU pricing, inventory cover, channel status, asset readiness, compliance notes, lifecycle state, and an approval-gated review queue in a Busabase-backed App-in-Skill. Reading a SKU master sheet, a marketplace export, or an inventory CSV is a genuine external operation a browser cannot perform: scripts/ingest_products.mjs is the only place a product, channel row, inventory row, or review item enters the system. The AirApp itself only reads Busabase and writes review decisions; every channel publish, price change, SKU archive, or quality-hold change is delegated to the agent (or the user) after explicit approval, recorded by scripts/execute_decisions.mjs.

Default behavior is AirApp-first. Unless the user explicitly asks only for explanation, ingest what's due and give the user the clickable AirApp URL (or the local preview URL when local preview is explicitly requested). Use chat-only mode only when the user says "纯聊天", "chat only", "不要打开 UI", or similar; then present numbered review items (Review #1) and take verdicts in conversation.

App UI Screenshots

<table> <tr> <td width="50%"><img src="assets/screenshots/overview.webp" alt="Kelly Products overview"></td> <td width="50%"><img src="assets/screenshots/products.webp" alt="Kelly Products catalog"></td> </tr> <tr> <td><strong>Overview</strong><br>Product command desk with visual product cards, margin, inventory value, activity, and approval queue.</td> <td><strong>Catalog</strong><br>Image-rich product library with SKU, lifecycle, owner, margin, inventory cover, and status badges.</td> </tr> <tr> <td width="50%"><img src="assets/screenshots/detail.webp" alt="Kelly Products detail"></td> <td width="50%"><img src="assets/screenshots/review.webp" alt="Kelly Products review queue"></td> </tr> <tr> <td><strong>Product detail</strong><br>Gallery, pricing, inventory, content readiness, compliance notes, channel matrix, and related review cards.</td> <td><strong>Review queue</strong><br>Approval-gated publish, price, quality-hold, and lifecycle recommendations with evidence.</td> </tr> </table>

Mandatory Dependencies

1. Read and follow $kelly-app-skill-creator for product behavior, visual quality, responsive layout, and the complete canonical content/kelly-products-app/ artifact.
2. Read and follow $busabase for connection, target Space, node discovery, ChangeRequests, review, and merge behavior.
3. Read and follow $busabase-app-creator for resource modeling, AirApp runtime limits, security, validation, and deployment.

If a dependency is unavailable, preserve this skill's local artifact and product contracts, stop before the unavailable Busabase operation, and report the exact missing dependency. Do not invent a second data backend.

Boundary

• The agent reads product exports, inventory sheets, channel-status exports, and listing handoffs; ingesting them is a local-file-only operation: scripts/ingest_products.mjs reads a JSON payload file the agent prepares and writes it to Busabase. It never fetches documents from remote systems on its own.
• The AirApp reads and writes Busabase records only. It never publishes a channel listing, changes a price, archives a SKU, lifts a quality hold, or performs any other external side effect.
• Publishing channels, changing prices, archiving SKUs, and lifting quality holds all require a human approval record on a review item; scripts/execute_decisions.mjs never performs the action itself — it only writes an execution marker. The agent performs the real follow-up outside the app after explicit approval and reports the concrete result back to the user.
• No seller credentials live in this repo or in Busabase. Never commit local payload files, env files, or generated exports.
• Never invent certifications, test reports, inventory, or supplier facts. Mark them missing and request evidence rather than weakening margin, MAP, low-stock, or compliance gates to make a product pass.

Busabase Resources

Five Bases under one application Folder (kelly-products), declared in content/kelly-products-app/app/js/config.js and the generated template sidecars under content/:

• products: catalog/SKU master data — lifecycle, status, owner, vendor, image/gallery, tags, and JSON-encoded pricing/inventory-rollup/content-readiness/compliance blocks.
• channels: one row per product × marketplace channel (Amazon/Shopify/TikTok Shop/eBay) — listing id, status, price, buybox, content score, and channel issue note.
• inventory: one row per product × warehouse — on-hand/available/reserved/inbound units, inbound ETA, days of cover, and stock-risk status.
• review: the approval-gated review queue — channel publish approvals, price-change review, quality holds, and lifecycle/archive decisions, with the human decision and execution marker on the same row.
• settings: one row (record-id: "config") with the seller profile, platform connectors, warehouses, and review policy.

Resources provision lazily through an idempotent Busabase ChangeRequest the first time the app runs in a Space; see references/products-schema.md for exact field shapes. Metrics and the recent-activity feed are recomputed client-side from the stored rows on every read (content/kelly-products-app/app/js/products-model.js's buildSnapshot/assembleSnapshot), so the desk is always fresh regardless of when a browser session loads it relative to the last ingest run.

First Run And Onboarding

On invocation, check the products Base. If it is empty, guide setup before ingesting real products: ask, turn by turn, seller profile (brand, entity, base currency), enabled marketplace platforms, warehouses, and the review policy (price-change threshold, margin floor, low-stock days). Write the answers onto the Settings row, then ingest:

node skills/kelly-products/scripts/ingest_products.mjs payload.json --apply

Local App

Default behavior is AirApp-first — give the user the clickable AirApp URL. Start pnpm --dir content/kelly-products-app dev only when local preview/debugging is explicitly requested.

Required app views (hash routes):

• #/overview: KPI cards (products, active products, average margin, inventory value), visual product cards, review-queue preview, and recent activity (derived from each product's/review item's own timestamps).
• #/products and #/products/<id>: catalog and product detail with gallery, pricing, inventory, content readiness, compliance notes, channel matrix, and linked review cards.
• #/inventory: warehouse and days-cover table with low-stock and stockout-risk badges.
• #/channels: product × platform status table with channel issue notes and content scores.
• #/review: approval queue with approve / request_changes / block decisions. Decisions write directly onto the review item's own record through busabase-sdk — there is no separate decisions bucket.
• #/settings: sanitized seller profile, platform connectors, warehouses, review policy, and data-provider state, read live off the Settings Base.

Demo mode:

• ?demo=overview, ?demo=products, ?demo=inventory, ?demo=channels, ?demo=review, and ?demo=detail open deterministic mock scenes for documentation and screenshots.
• lang=en or lang=zh forces UI chrome language; demo product names and agent notes localize with the chrome.
• Demo mode never reads or writes Busabase. Decision buttons still work in the UI but act on in-memory state only.
• Demo product images are the same real static PNG assets shipped under content/kelly-products-app/app/assets/product-images/ that the live app uses.

Ingest Workflow

1. Collect product sources: SKU master sheet, pricing/cost table, warehouse inventory, marketplace/channel exports, content asset checklist, and handoffs from kelly-picks or kelly-listing.
2. Build a payload shaped like the retired local app's products_snapshot.json contract (seller, platforms, warehouses, review_policy, sync, products, channel_matrix, inventory, review_items) — see references/products-schema.md for the exact field shapes.
3. Run the write path:

node skills/kelly-products/scripts/ingest_products.mjs payload.json --apply

The script upserts every row into Busabase by natural key (product_id, channel_id, inventory_id, item_id) so re-ingests are idempotent, and never clobbers a human decision already recorded on a review item. Without --apply it is a dry run.

Decisions And Execution Workflow

1. The reviewer decides at #/review: approve, request changes (with a note), or block. Decisions write status/decision-note/decided-at directly onto the review item's own record. From a standalone local preview the write merges immediately (trusted operator); from the deployed AirApp it creates a pending ChangeRequest for the trusted process to merge.
2. On explicit user request to execute, run scripts/execute_decisions.mjs (dry-run by default; --apply writes execution-status: "ready_for_agent" onto each decided review item with the concrete operation — publish_channel, apply_price_change, lift_quality_hold/maintain_quality_hold, archive_product, maintain_block, or request_revision — and a human-readable detail). No external side effects either way; the review item's status never changes.
3. The agent then performs the approved follow-up outside the app: publish the channel listing, apply the price change, archive the SKU, or lift/maintain the quality hold through the actual seller platform connectors, then reports the concrete result back to the user (and re-ingests the updated product/channel/inventory state with scripts/ingest_products.mjs).

Safety Defaults

• Never invent certifications, test reports, inventory, or supplier facts. Mark them missing and request evidence.
• Do not weaken margin, MAP, low-stock, or compliance gates to make a product pass.
• Keep channel publishing, price changes, SKU archival, and quality-hold changes approval-gated even if the connector credentials are ready.
• Use stable ids and natural-key upserts so repeated ingests and executions are idempotent.
• Keep demo data deterministic and image-rich so documentation screenshots remain stable.

Useful Commands

node skills/kelly-products/scripts/ingest_products.mjs payload.json --apply
node skills/kelly-products/scripts/execute_decisions.mjs
node skills/kelly-products/scripts/execute_decisions.mjs --apply
pnpm --dir skills/kelly-products/content/kelly-products-app dev

In normal use, invoke /kelly-products, let the skill ingest what's due, and open the AirApp.