mai
AI shopping matchmaking agent for OpenClaw and Hermes. Use when merchants want to publish products, manage stock, answer buyer questions, and handle order requests; or when buyers want to discover merchants and products, compare prices, discuss with sellers, read reviews, and create trackable orders. Supports local-first transaction tracking and registry-backed PSP custody records.
What this skill does
# Mai ## Overview Mai helps buyers and merchants complete shopping matchmaking through an AI agent. It keeps deterministic marketplace state in `scripts/mai.py` while the host model handles natural language, negotiation, summaries, and risk explanations. Mai can run local-only or registry-backed. Use local-only for one agent's private catalog. Use registry-backed discovery when buyers and merchants are on different machines or agent profiles. ## Operating Principles - Be neutral between buyer and merchant. Explain options, prices, review signals, inventory, and tradeoffs without fabricating availability. - Treat payments as external or PSP-backed. Mai never directly holds funds. Local mode records payment URLs and references; registry mode records PSP custody events and must not claim success without PSP or external evidence. - Confirm before irreversible steps. Ask for buyer confirmation before creating an order and merchant confirmation before reserving stock. - Preserve negotiation context. Record important buyer/merchant messages with `message add` before forming or updating an order. - Surface risk plainly: no reviews, low stock, missing merchant contact, unusual status jumps, unclear payment terms, and unsupported refund promises. - Prefer short, actionable answers: recommendation, reason, risk, next action. ## Quick Start Use the CLI helper for deterministic state: ```bash python3 scripts/mai.py merchant create --id seller-a --name "West Lake Tea" --city Hangzhou --contact "wechat:westlake" --tags "tea,gift" python3 scripts/mai.py product add --merchant seller-a --sku tea-a --title "Longjing Gift Box" --price 88 --stock 5 --category tea --tags "longjing,gift" python3 scripts/mai.py search products --query "longjing tea" --format json python3 scripts/mai.py compare --skus tea-a,tea-b --format json python3 scripts/mai.py order create --buyer alice --merchant seller-a --sku tea-a --quantity 2 --offer-price 86 ``` Default data path: `~/.local/share/mai/mai.json`. Use `--data /path/to/mai.json` for a project-local or test database. ## Installation Install the published OpenClaw pair: ```bash clawhub --workdir ~/.openclaw/workspace --dir skills install mai openclaw plugins install clawhub:mai-plugin ``` `mai` is the skill. `mai-plugin` is an optional lightweight OpenClaw native bridge for tools and `/mai` command support. Local checkout install: ```bash cd /Users/jianghaidong/coding/mai bash scripts/install.sh --both ``` Install only one ecosystem: ```bash bash scripts/install.sh --openclaw bash scripts/install.sh --hermes ``` The installer creates symlinks: - OpenClaw: `~/.openclaw/workspace/skills/mai` - Hermes: `~/.hermes/skills/commerce/mai` After installation, restart the host agent if it does not refresh skills automatically. Hermes can preload Mai with `hermes -s mai`. ## Registry Discovery Run a registry marketplace: ```bash python3 scripts/mai_registry.py issue-key --data ./mai-registry.json --token admin-token --role admin --subject ops-admin python3 scripts/mai_registry.py issue-key --data ./mai-registry.json --token seller-token --role merchant --subject seller-a --merchant-id seller-a python3 scripts/mai_registry.py issue-key --data ./mai-registry.json --token buyer-token --role buyer --subject alice --buyer-id alice python3 scripts/mai_registry.py serve --data ./mai-registry.json --host 127.0.0.1 --port 8765 --rate-limit-per-minute 60 ``` Merchant agents publish local supply: ```bash python3 scripts/mai.py --data ./seller.json registry push --url http://127.0.0.1:8765 --api-key seller-token ``` Buyer agents discover supply and create demand: ```bash python3 scripts/mai.py --data ./buyer.json registry search-products --url http://127.0.0.1:8765 --query "longjing tea" --format json python3 scripts/mai.py --data ./buyer.json registry message --url http://127.0.0.1:8765 --api-key buyer-token --buyer alice --merchant seller-a --sku tea-a --text "Can this ship today?" python3 scripts/mai.py --data ./buyer.json registry order --url http://127.0.0.1:8765 --api-key buyer-token --buyer alice --merchant seller-a --sku tea-a --quantity 2 --offer-price 86 python3 scripts/mai.py --data ./buyer.json registry payment-hold --url http://127.0.0.1:8765 --api-key buyer-token --buyer alice --order ORD-0001 ``` Merchant agents pull buyer messages and draft orders: ```bash python3 scripts/mai.py --data ./seller.json registry pull --url http://127.0.0.1:8765 --api-key seller-token --merchant seller-a ``` Read `references/registry-api.md` before changing registry integrations. ## Public Marketplace Controls - Require API keys for merchant push/pull, buyer messages/orders/payment holds, moderation, and payment release/refund. - Store only salted API key hashes in the registry file. - Allow public search, but rate-limit every request by API key or client IP. - Treat products with high risk scores as `pending_review`; do not show them in search until an admin approves them. - Use `registry payment-hold` only as PSP-backed custody tracking. The bundled `demo` provider is not real money movement. - Require an admin key for `registry payment-release` and `registry payment-refund`. - Do not claim escrow, payment success, release, or refund unless the PSP adapter or external evidence confirms it. ## Merchant Workflow 1. Create or identify the merchant profile: `python3 scripts/mai.py merchant create --id ID --name NAME --city CITY --contact CONTACT --tags "A,B"` 2. Publish products: `python3 scripts/mai.py product add --merchant ID --sku SKU --title TITLE --price N --stock N` 3. Adjust stock after physical changes: `python3 scripts/mai.py product stock --sku SKU --merchant ID --adjust N --reason "restock or correction"` 4. Record important buyer questions and seller replies: `python3 scripts/mai.py message add --buyer BUYER --merchant ID --sku SKU --sender merchant --text "..."` 5. Quote and confirm orders only when inventory and terms are clear: `python3 scripts/mai.py order quote ...` `python3 scripts/mai.py order update --order ORD-0001 --status confirmed --actor merchant` ## Buyer Workflow 1. Discover merchants: `python3 scripts/mai.py search merchants --query "tea hangzhou" --format json` 2. Search products: `python3 scripts/mai.py search products --query "longjing gift" --max-price 100 --format json` 3. Compare shortlisted SKUs: `python3 scripts/mai.py compare --skus sku-a,sku-b --format json` 4. Inspect reviews: `python3 scripts/mai.py review list --merchant ID --format json` 5. Record discussion before ordering: `python3 scripts/mai.py message add --buyer BUYER --merchant ID --sku SKU --text "..."` 6. Create a draft order after buyer confirmation: `python3 scripts/mai.py order create --buyer BUYER --merchant ID --sku SKU --quantity N` ## Transaction Model Mai tracks transactions without custody: `draft -> quoted -> confirmed -> payment_pending -> paid_external -> fulfilled -> completed` Disputes can move through: `disputed -> resolved/refunded/cancelled` Stock is reserved when an order becomes `confirmed`. Local-only payments are recorded as `payment_url` and `payment_reference`. Registry payments are PSP custody records; the agent must say the bundled `demo` provider is not real escrow or money movement. Read `references/transaction-model.md` when handling non-happy-path order, refund, dispute, or payment questions. Read `references/data-schema.md` when integrating Mai with a future hosted marketplace or sync service. ## Output Expectations For product discovery, answer with: - best match and why - price and merchant comparison - availability and shipping notes - review/trust signals - risks or missing facts - one next action For merchant operations, answer with: - action completed or blocked - changed product/order/inventory identifier - current stock or status - next operational step For order updates, answer with: - previous status and new status - whether stock was reser
Related in AI Agents
skill-development
IncludedComprehensive meta-skill for creating, managing, validating, auditing, and distributing Claude Code skills and slash commands (unified in v2.1.3+). Provides skill templates, creation workflows, validation patterns, audit checklists, naming conventions, YAML frontmatter guidance, progressive disclosure examples, and best practices lookup. Use when creating new skills, validating existing skills, auditing skill quality, understanding skill architecture, needing skill templates, learning about YAML frontmatter requirements, progressive disclosure patterns, tool restrictions (allowed-tools), skill composition, skill naming conventions, troubleshooting skill activation issues, creating custom slash commands, configuring command frontmatter, using command arguments ($ARGUMENTS, $1, $2), bash execution in commands, file references in commands, command namespacing, plugin commands, MCP slash commands, Skill tool configuration, or deciding between skills vs slash commands. Delegates to docs-management skill for official documentation.
reprompter
IncludedTransform messy prompts into well-structured, effective prompts — single or multi-agent. Use when: "reprompt", "reprompt this", "clean up this prompt", "structure my prompt", rough text needing XML tags and best practices, "reprompter teams", "repromptception", "run with quality", "smart run", "smart agents", multi-agent tasks, audits, parallel work, anything going to agent teams. Don't use when: simple Q&A, pure chat, immediate execution-only tasks. See "Don't Use When" section for details. Outputs: Structured XML/Markdown prompt, quality score (before/after), optional team brief + per-agent sub-prompts, agent team output files. Success criteria: Single mode quality score ≥ 7/10; Repromptception per-agent prompt quality score 8+/10; all required sections present, actionable and specific.
adaptive-compaction
IncludedAdaptive add-on policy and recovery layer that decides WHEN to compact, prune, snapshot, or fork -- replacing fixed-percent auto-compaction across Claude Code, Codex, and MCP-capable hosts. Trigger on auto-compact timing or damage: "when should I compact", "is it safe to compact now or start a fresh session", "auto-compact fires too early/mid-task", "switching to an unrelated task but the window still has space", "context rot", "answers get worse the longer the session runs", "the agent forgot the plan or my decisions after it summarized", "add a layer on top that manages context without changing the agent", raising autoCompactWindow to give the policy room, or installing/tuning a cross-tool compaction policy or PreCompact hook -- even when "compaction" is never said but the problem is context-window pressure or post-summarization memory loss. Do NOT use to summarize a conversation, build RAG, write a summarization prompt (decides WHEN not HOW), or answer max-context-length trivia.
agent-skill-creator
IncludedCreate cross-platform agent skills from workflow descriptions. Activates when users ask to create an agent, automate a repetitive workflow, create a custom skill, or need advanced agent creation. Triggers on phrases like create agent for, automate workflow, create skill for, every day I have to, daily I need to, turn process into agent, need to automate, create a cross-platform skill, validate this skill, export this skill, migrate this skill. Supports single skills, multi-agent suites, transcript processing, template-based creation, interactive configuration, cross-platform export, and spec validation.
llm-wiki
IncludedUse when building or maintaining a persistent personal knowledge base (second brain) in Obsidian where an LLM incrementally ingests sources, updates entity/concept pages, maintains cross-references, and keeps a synthesis current. Triggers include "second brain", "Obsidian wiki", "personal knowledge management", "ingest this paper/article/book", "build a research wiki", "compound knowledge", "Memex", or whenever the user wants knowledge to accumulate across sessions instead of being re-derived by RAG on every query.
skill-master
IncludedAgent Skills authoring, evaluation, and optimization. Create, edit, validate, benchmark, and improve skills following the agentskills.io specification. Use when designing SKILL.md files, structuring skill folders (references, scripts, assets), ingesting external documentation into skills, running trigger evals, benchmarking skill quality, optimizing descriptions, or performing blind A/B comparisons. Keywords: agentskills.io, SKILL.md, skill authoring, eval, benchmark, trigger optimization.