_{Commerce Agent OS on a seeded demo tenant — verified evidence, pending human approvals, and the agents that produced them, on one screen.}

In Claude Code — installs the 9 skills; only their names and descriptions load until one is used:

/plugin marketplace add kangise/ecommerce-ai-skills
/plugin install ecommerce-ai-skills@ecommerce-ai-skills

Run the operations UI locally:

pip install "ecommerce-ai-skills[mcp] @ git+https://github.com/kangise/ecommerce-ai-skills"
opc-ecommerce demo-seed --db ./demo.sqlite && opc-ecommerce demo --db ./demo.sqlite --port 8788
# then open http://127.0.0.1:8788/app

What This Is

An AI operations knowledge base for cross-border e-commerce. One source, three uses:

Use	What it is	Entry
Read it	69 chapters, sourcing to growth, complete in zh/en/ja	Online site
Install it for your agent	Knowledge + domain model + guarded capabilities: a Claude Code plugin, or one MCP config line for Claude Desktop / Cursor	dist/
Run it	Commerce Agent OS — an operations runtime on real store data, with multi-agent review and human approval	opc-ecommerce demo

All three are held to the same CI gates. Gates fail, nothing ships.

Run It — Commerce Agent OS

The first two uses hand knowledge to an AI. The third puts it to work — the same ontology and skills inside a runtime with approval, audit, and failure recovery.

pip install "ecommerce-ai-skills[mcp] @ git+https://github.com/kangise/ecommerce-ai-skills"

opc-ecommerce demo-seed --db ./demo.sqlite     # isolated demo tenant
opc-ecommerce demo --db ./demo.sqlite --port 8788
# open http://127.0.0.1:8788/app

The demo tenant is marked DEMO DATA throughout and is physically isolated from real data.

What it does today

Capability	Detail
Real data in	Amazon SP-API / Amazon Ads / Shopify connectors; Business Report, Ads, FBA, returns, and listing CSV/XLSX import once as durable Evidence
Multi-agent review	Weekly Ops Council: an evidence agent and one specialist per marketplace review in parallel, then a cross-platform controller and store manager set priorities
Human approval gate	Writes go through proposal → approval → execution; advertising actions carry an extra capability gate and are blocked without authorization
Durable execution	Four worker classes (job / schedule / report-sync / daily-ops) resume after interruption, with idempotency leases and recovery
Full audit trail	Every conclusion must cite its input source; tenant isolation, API key rotation, operation audit log
Operations UI	/app with seven views — briefing, agents, evidence, approvals, connections, automation, audit; persisted zh/en/ja preference, light and dark themes

_{Approvals: every external write is a proposal with a rollback plan and an expiry; another authorized user approves before an operator can execute.}

Model providers: OpenAI by default; set EAI_AGENT_PROVIDER=anthropic to run on Claude. Both providers share one contract — credentials stay environment-only, the endpoint is pinned to the official host, and the audit record names the provider actually used. An unrecognised value fails at startup rather than rerouting silently.

What it deliberately refuses to do — without real credentials or complete evidence it fails explicitly rather than producing plausible-looking placeholder results. Same principle as the data discipline in the knowledge layer.

Integration details in integration/runtime-api.md.

Who You Are → Where to Start

Why Not Just Another Prompt Collection

Ask an AI "roughly how much does this category sell per month?" and it will almost always hand you a plausible-looking number — one it does not actually know.

Sourcing, restocking, and pricing have real money behind them. The agent era makes it worse: a model acts on numbers it doesn't know to adjust prices and place orders.

The difference isn't fancier prompts — it's drawing the line where AI stops.

30-Second Demo

Paste this into ChatGPT or Claude:

<role>Cross-border sourcing consultant familiar with Amazon [US/DE/JP]</role>

<my_conditions>
- Startup capital: ¥[X]0K
- Experience level: [beginner/experienced/veteran]
- Preferred categories: [write your preference, or "no preference"]
- Risk appetite: [conservative/medium/aggressive]
</my_conditions>

<tool_data>
[Optional. Paste category data exported from Helium 10 / Jungle Scout. If empty, see data_discipline below]
</tool_data>

<task>
Recommend 5 category directions, each with:
1. Category name and brief description
2. Why this may be an opportunity now (state the basis for your judgment)
3. What data I need to verify to confirm it (name the specific metrics and the tool to pull them from)
4. Main risks and mitigations
5. Order-of-magnitude read on startup capital (can my stated budget cover it?)
6. Recommended entry strategy (differentiation direction)
</task>

<data_discipline>
- **Do not give specific monthly sales, price, or margin figures** unless they appear in <tool_data>. You do not have live market data, and an invented number leads me to stock the wrong product
- When <tool_data> is empty, item 3 matters most: tell me what to look up rather than guessing the answer for me
- Tag each conclusion: [tool data] or [category-level inference]
- If you lack the basis for a judgment, ask me for the data before concluding
</data_discipline>

<constraints>
- Don't recommend already-red-ocean categories (phone cases, cables)
- Prioritize categories with room for differentiation
- Respect my capital and experience limits
</constraints>

<output_format>
Recommend exactly 5 category directions, each following the fixed 6-item structure from <task> above:
1. Category name and brief description (1–2 sentences)
2. Why this may be an opportunity now (basis for the judgment)
3. Data to verify (specific metrics + the tool to pull them)
4. Main risks and mitigations
5. Order-of-magnitude read on startup capital (can my budget cover it?)
6. Recommended entry strategy (differentiation direction)
</output_format>

<self_check>
Before delivering, confirm: (1) no number appears that I didn't provide, (2) every category states what to verify next, (3) exactly 5 recommendations
</self_check>

Note:
- Don't recommend already-red-ocean categories (phone cases, cables)
- Prioritize categories with room for differentiation
- Account for my capital and experience limits

<copy_discipline>
- Never write a feature, material, certification, or result the product doesn't have. Any attribute I didn't state above must not appear in the copy
- For anything sent to a customer (replies, emails, templates), don't make commitments I haven't authorized: refund amounts, compensation, timelines, or exceptions to platform policy must be confirmed by me before they go in
- Flag any claim touching efficacy, safety, environmental, or patent language separately for manual review
</copy_discipline>

Notice how it doesn't fabricate numbers — it tells you exactly which figures to look up yourself. From A1 Product Research · 3.7 Category Opportunity Discovery.

Three Real Usage Scenarios

1 · Write an Amazon Listing for a new product (no coding required)

Open A2 Listing Optimization, copy the "full-listing generation" prompt, and fill in your product info.

You get a listing with platform hard constraints baked in: title ≤200 characters with the highest-search-volume keyword in the first 80, 5 bullets each ≤200 characters with no HTML, backend Search Terms ≤250 bytes per line.

These aren't rules we made up — they're Amazon's actual limits, stored in ontology/constraints.yaml, and the prompt's <self_check> block verifies each one. Change a constraint once, and gate O5 makes every prompt referencing it change together.

2 · Turn Claude Desktop into an e-commerce consultant (5 minutes)

Install the server dependencies first:

python3 -m pip install "ecommerce-ai-skills[mcp] @ git+https://github.com/kangise/ecommerce-ai-skills"

{
  "mcpServers": {
    "opc-ecommerce": {
      "command": "opc-ecommerce",
      "args": ["mcp"]
    }
  }
}

opc-ecommerce is the command the pip install created; the knowledge package ships inside it, so no clone is needed. If Claude Desktop cannot find the command, put the absolute path from which opc-ecommerce in command. Working from a clone instead: "command": "python3", "args": ["/path/to/ecommerce-ai-skills/integration/mcp-server.py", "--dist", "/path/to/ecommerce-ai-skills/dist"].

After install:

You ask	What it does
"ACOS is up to 40%, what do I do?"	Routes to ecom-advertising — a diagnostic path, not generic advice
"Should I use AI for demand forecasting?"	Routes to ecom-applicability — answers "not with under a year of data", because it has every chapter's failure boundaries installed
"How do I reply to a complaint that the product doesn't match the photos?"	Routes to ecom-customer-service — reply templates with copy discipline

See dist/integration/mcp.md.

3 · Cross-platform launches for your team, no rules to memorize

The same "title" is a different thing on each of three platforms — look it up in ontology/constraints.yaml:

amazon.listing.title.max_length:       200  characters
shopify.product_page.title.max_length:  70  characters
tiktok_shop.product.title.max_length:   80  characters

When the team asks in the group chat again, just share the link. Or use the ecom-listing skill to generate compliant variants for all three platforms in one go.

Not Just a Book — Four Layers

Layer	Contents	Scale	For
Knowledge Base	69 chapters, trilingual (zh/en/ja)	69 chapters	Human reading · agent retrieval
Ontology	E-commerce domain model	100 entities · 322 constraints · 78 relations · 8 processes	Shared contract between agents
Skills + Prompts	Guarded executable capabilities	878 prompts · 9 installable skills	Agent direct invocation
Runtime	Multi-agent operations runtime + UI	54 API endpoints · 7 views · 3 platform connectors	Day-to-day operation of a real store

The first three layers are knowledge; the fourth connects them to real data and executes. The first three ship in dist/; the fourth is the pip install runtime package.

dist/ directory structure:

dist/
  SKILL.md       ← Agent entry point — read it to know how to route requests
  ontology.json  ← E-commerce domain model (entities, relations, constraints)
  prompts.json   ← Guardrailed prompts, trilingual
  skills/        ← 9 domain skills, each with manifest + playbook + boundaries
  knowledge/     ← Structured index of the 69 chapters
  integration/   ← MCP server setup guide

The MCP server exposes 8 resources (the five ontology files + knowledge index + full chapter text + glossary) and 5 tools (route_query / get_constraints / search_knowledge / read_chapter / list_skills). Check it yourself:

python3 integration/mcp-server.py --cli

Point it at a running runtime (OPC_RUNTIME_URL + OPC_RUNTIME_API_KEY) and four read-only ops tools appear: briefing, metric observations, pending actions, imported evidence. The agent then knows not only what to do about a 40% ACOS, but what the ACOS actually is.

Approval is not exposed. Writes go proposal → human approval → execution, and making approve a tool would hand the model the key to the gate. An agent can see what is waiting; a person still approves it.

Why Trust This Content

Not because "we're careful" — because of 43 CI gates. Every gate must pass or the build stops:

Gate	What it checks
M1	Every hard number in the text has a source, a verification date, a hedge word, or an explicit flag
M2	Every how-to chapter has a "when this doesn't work" section
M4	Every external link has been probed and isn't dead
M7	verified markers older than 18 months auto-expire with an error
N3 N4	Every prompt has a self-check block and an output format
O5	Constraint values written in the text must match the ontology
parity	All three language files exist and have matching structure

Run it yourself:

python3 scripts/verify_all.py

The full gate list and design rationale are in scripts/README.md. Known open items are written down in CONTRIBUTING.md, not hidden.

Where to Start

You are	Start here
Wanting to know what AI can actually do	AI Landscape Assessment — 30 minutes on maturity per step
An operator, ready to use it today	A1 Product Research · A2 Listing · A3 Advertising
Already using AI, want automation	A14 Agentified Operations — decide which steps are worth it first
Technical, building your own	B4 Agent Workflow · B6 MCP Integration
Facing compliance right now	Tariffs & de minimis · EU AI Act

Other Things You Might Care About

• Content that doesn't rot in three months — chapters only describe capability tiers; model ids and prices live on one model matrix page with verification dates, and M7 errors when they expire
• Built for the agent era — not just prompts, but how to migrate them into skill files and which actions must never go to an agent
• CC0 — take it, no attribution required, no need to tell me

---

Content Index

Domain	Topics
AI Foundations	AI Evolution · Prompt Engineering · RAG · Agents · RPA · Tool Comparison · AI Landscape
Product Research	Product Research · Pricing Strategy · IP Protection
Supply Chain	Inventory & Supply Chain
Content & Conversion	Listing Optimization · Visual Content · Brand Building
Traffic & Acquisition	Advertising · SEO / GEO · Growth Hacking
Social Media	Instagram / Facebook · YouTube · Xiaohongshu (RED) · Pinterest · WhatsApp · Reddit · Cross-Channel
Customer Operations	Customer Service & After-Sales
Compliance & Finance	Compliance & Risk · Financial Analysis · AI Risk Governance
Marketplaces — Shelf	Walmart · eBay · AliExpress · Temu · Faire
Marketplaces — DTC	Shopify
Marketplaces — Short Video	TikTok Shop
Marketplaces — APAC	Southeast Asia · Japan (Rakuten) · Korea (Coupang)
Marketplaces — EU & LatAm	Mercado Libre · Otto / Zalando
Cross-Platform Strategy	Cross-Platform Synergy · Platform Comparison
Building AI Systems	Data Pipeline · Prediction Models · RAG Knowledge Base · Agent Workflow · Local Deployment · MCP · Review NLP · Dashboard · Image Pipeline
Team & Management	AI Assessment · Team Building · ROI Evaluation · Competitive Intelligence

---

Six Tracks

Track	Who It's For	Coding?	What You Get
0 · AI Foundations (7 guides)	Everyone	No	A working mental model of LLMs, prompts, RAG, agents
A · Operators (13 guides)	Product research / ops / ads / CS	No	A reusable AI workflow for every step from sourcing to growth, Amazon-first
B · Developers (9 guides)	Engineering / data / BI	Python	Deployable systems: pipelines, forecasts, RAG, agents, dashboards
C · Managers (5 guides)	Team leads / founders	No	An AI adoption roadmap: assessment, training, ROI, risk governance
D · Marketplaces (14 guides)	Multi-platform sellers	No	Platform-specific playbooks: Shopify, TikTok Shop, Walmart, and 10 more
E · Social Media (7 guides)	Content & growth	No	Channel strategies that map to the buyer journey, from discovery to decision

---

Top 10 Prompts (Ready to Use)

Hand-picked from the guides — copy into ChatGPT / Claude and get results instantly.

1. Competitor Review Pain Point Analysis — Extract product improvement ideas from negative reviews

You are a senior Amazon product manager. I'll give you a set of 1-3 star competitor reviews.
Analyze and output: Top 5 user pain points (by frequency), representative review quotes, improvement suggestions, and difficulty rating. Present in table format.
[Paste negative reviews here]

Full guide →

2. Market Feasibility Quick Assessment — 5-dimension scoring to decide if a product is worth pursuing

You are a cross-border e-commerce product research expert. Assess this product:
Product: [product name] Target market: Amazon [US/DE/JP]
Analyze across 5 dimensions (score 1-5 each): market demand, competition intensity, profit margin, supply chain difficulty, compliance risk.
Give a final recommendation: Enter / Proceed with caution / Pass.

Full guide →

3. Full Listing Generation — Title, bullet points, description, and search terms in one go

You are an Amazon Listing optimization expert for the [target market].
Product: [name] Selling points: [point 1/2/3] Keywords: [keyword list]
Generate: Title (≤200 chars), 5 Bullet Points, Product Description (≤200 words), Backend Search Terms (5 lines).
Integrate keywords naturally, highlight differentiation.

Full guide →

4. Multilingual Localization — Not translation, but market adaptation

You are an Amazon Listing localization expert fluent in [target language].
[Paste English listing]
Localize to [target language]: match local search habits, replace with local keywords, reorder selling points for local priorities, annotate all localization changes with reasons.

Full guide →

5. Competitor Listing Strategy Breakdown — Compare and find differentiation opportunities

Analyze these 3 competitor Amazon Listings and compare their strategies:
[Competitor A/B/C titles and bullet points]
Output: Each competitor's core positioning, shared selling points, differentiation opportunities, keyword coverage comparison table, and positioning recommendations for my listing.

Full guide →

6. Search Term Report Analysis — Find ad spend waste and optimization opportunities

You are an Amazon PPC advertising expert. Here's my search term report (past 30 days):
[Paste data]
Output: High-converting keywords TOP 10, high-spend low-conversion TOP 10, low CTR analysis, negative keyword suggestions, budget reallocation plan.

Full guide →

7. Ad Copy A/B Testing — 5 headline styles for Sponsored Brands

Product: [description] Key selling point: [main benefit]
Generate 5 Sponsored Brands Headlines (≤50 chars each): feature-driven, scenario-driven, emotion-driven, data-driven, problem-solving.
Annotate expected impact and target audience for each.

Full guide →

8. Bulk Negative Review Analysis — Categorize issues and create action plans

You are an e-commerce product quality analyst. Here are all 1-3 star reviews from the past 60 days.
Categorize by type (quality/functionality/shipping/usability/expectation mismatch), calculate frequency %, list 3 representative reviews per category, provide short-term + long-term solutions, and prioritize.
[Paste reviews]

Full guide →

9. Account Appeal Letter (Plan of Action) — Professional reinstatement appeal

You are an Amazon account appeal expert. My account was suspended for:
[Paste violation notice]
Write a Plan of Action: Root Cause (acknowledge the issue), Immediate Actions (steps already taken), Preventive Measures (long-term prevention). Professional and sincere tone, specific action items in each section.

Full guide →

10. Multi-Market Compliance Comparison — Generate compliance checklists fast

I want to sell [product type] on Amazon [US/DE/JP].
Generate a compliance comparison table: required certifications per market, packaging & labeling requirements, special category requirements, estimated costs & timelines, common compliance pitfalls.
Note information currency and recommend confirming with certification bodies.

Full guide →

---

Notebook Lab

18 Jupyter notebooks that run directly on Google Colab — zero setup required:

Product Research · Multilingual Listing · Advertising · Negative Reviews · Inventory Reorder · Compliance Checker · Price Tracker · GEO Audit · Brand Audit · Profit Calculator · Patent Search · Data Pipeline · Sales Forecast · Review NLP · Dashboard · ROI Evaluation · Cross-Platform Content · Social Calendar

Case Studies

AI Listing Optimization — 4 hours → 45 minutes per SKU

AI PPC Optimization — ACOS 35% → 18%

Review-Driven Product Development — 4.6★ vs. competitor's 4.2★

All case studies →

---

Community

ecommerce-ai-skills is an open-source project under the AAAI China Chapter, dedicated to the practical application of AI in cross-border e-commerce.

• Star this repo to stay updated
• Submit an issue to report problems or suggest improvements
• Submit a PR to contribute prompts, notebooks, or case studies

Contributing

We especially welcome:

1. Prompt templates — battle-tested prompts that work in real business scenarios (note which AI tools you tested with)
2. Notebooks — hands-on tutorials that run on Google Colab free tier
3. Case studies — how you solved an e-commerce problem with AI, and the results
4. Tool reviews — pros and cons of AI tools you've actually used
5. Fixes — broken links, outdated content

See CONTRIBUTING.md for details.

---

CC0 1.0 — free to use, no attribution required · Disclaimer · Privacy · Security · An AAAI China Chapter Initiative