Community研究與資料分析github.com

skuio/sku-skills

SKU.io API 的開源電商代理技能 — 一次撰寫,為 Claude、OpenAI 和 Gemini 生成。

sku-skills 是什麼?

這個技能讓 AI 代理能夠使用 SKU.io API 查找和解析產品資訊。它支援多種查找方式,包括透過精確 SKU、掃描條碼(UPC/EAN/GTIN)、模糊名稱或 SKU 搜尋,以及直接使用數位產品 ID 查詢。技能會引導代理選擇最精確的查找方式,並正確處理結果:當找到唯一匹配時直接使用,搜尋結果過多時要求使用者確認,無匹配時報告情況而非虛構 ID。它支援 Claude Code、OpenAI 和 Gemini 等主流代理平台,並包含完整的分頁、錯誤處理和驗證指引。這個技能是 skuio/sku-skills 開源倉庫的一部分,旨在協助開發者與電商整合。

相容平台✓Claude Code✓Codex CLI~Cursor✓Gemini CLI
npx skills add skuio/sku-skills

Installed? Explore more 研究與資料分析 skills: affaan-m/uspto-database, affaan-m/scholar-evaluation, affaan-m/literature-review · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

尋找產品

使用此技能將「藍色小工具」或掃描的條碼轉換為具體的 SKU.io 產品 — 其 id、sku、名稱和詳細資訊 — 以便下游技能擁有明確的參考。

選擇正確的查找方式

您擁有…呼叫原因
精確的 SKUGET /api/products/by-sku?sku=WIDGET-BLUE-01直接,單一結果
掃描的條碼 (UPC/EAN/GTIN)GET /api/products/barcode-lookup?code=0123456789012將條碼解析為其產品(參數為 code)
部分名稱或 SKUGET /api/products/search?query=blue widget模糊搜尋,可能返回多個匹配
數位產品 IDGET /api/products/{id}當您已有 ID 時取得完整記錄

始終優先選擇您能進行的最具體查找。僅在您沒有精確 SKU 或條碼時使用 search — 它可能返回多個候選項,您需要進行區分。

步驟

  1. 根據您擁有的資訊選擇上述查找方式。

  2. 使用您的 Bearer token(範圍 products:read)發送請求:

    curl -sS "https://$SKU_TENANT.sku.io/api/products/by-sku?sku=WIDGET-BLUE-01" \
      -H "Authorization: Bearer $SKU_PAT" -H "Accept: application/json"
    
  3. 處理結果:

    • 完全匹配一個 → 擷取其 id 和 sku;完成。
    • 搜尋返回多個 → 透過匹配精確的 sku 來縮小範圍,或向使用者顯示前幾個候選項(名稱 + sku)並詢問選擇哪一個。請不要默默地選擇第一個。
    • 無匹配 → 產品可能不存在或已歸檔。報告此情況,而不是憑空捏造一個 ID。在放棄之前,考慮使用更廣泛的 search 查詢。

備註

  • search 支援分頁 — 請參閱 shared/pagination.md。最佳匹配位於第一頁;在查找時您很少需要翻頁。
  • 產品 id 是其他技能期望的穩定鍵(例如銷售訂單行中的 product_id)。建議將 id 傳遞給下游,而不是每次重新透過 SKU 解析。

API 操作

方法路徑功能
GET/api/products/search依名稱或 SKU 片段模糊搜尋產品。
GET/api/products/by-sku依精確 SKU 擷取單一產品。
GET/api/products/barcode-lookup將掃描的條碼 (UPC/EAN/GTIN) 解析為產品。
GET/api/products/{id}依數位 ID 擷取完整產品記錄。

驗證

每個請求都使用 SKU.io 個人存取令牌,以 Bearer 令牌形式發送:

Authorization: Bearer <YOUR_SKU_PAT>
  • 基礎 URL: https://{tenant}.sku.io(將 {tenant} 替換為您的帳戶子域名)
  • 所需範圍: products:read

在 SKU.io 網頁應用程式的 設定 → 開發者 → 個人存取令牌 下建立一個令牌。 完整流程請參閱 shared/authentication.md。


改進此技能

此技能是否不足 — 步驟不明確、端點錯誤或無法完成?請不要繞過它:記錄問題所在並開啟拉取請求,以便下一個代理能做得更好。

  • 倉庫:https://github.com/skuio/sku-skills
  • 編輯 skills/<domain>/<name>/ 下的規範技能(而非此生成的檔案),然後執行 npm run build 並開啟 PR。外部貢獻者:請 fork 倉庫並從 fork 發起 PR。
  • 完整的代理工作流程請參閱 AGENTS.md。

您的代理可以端到端完成此操作。每次有人發送修正,此函式庫都會變得更好。

相關技能