How we built OpenTraid as a one-file OpenClaw commerce skill

OpenClaw is an open-source personal AI assistant that lives where you already chat — Telegram, WhatsApp, Slack, Discord — and learns new abilities by reading skill files. A skill is just a Markdown document that tells the agent how and when to call an external tool. No plugin runtime, no SDK, no build step. Drop the file in, and the agent knows something new.

That model is a gift for a commerce API, and a constraint worth respecting. The gift: distribution is a single file a user can install in seconds. The constraint: everything the agent needs to shop well has to be expressible in plain language the model can follow reliably. Here is how we approached it.

One file, four capabilities

The OpenTraid SKILL.md teaches an OpenClaw agent four things, each mapped to a single API call:

• Search — "find me running shoes under $120, at least 20% off" maps to POST /v1/search with natural language.
• Compare — "compare prices for this across shops" runs a multi-seller comparison, sorted.
• Verify — "check the price before I buy" calls POST /v1/verify for a real-time price and stock check at the source shop.
• Alert — "watch this jacket and tell me when it drops below $80" creates a price alert via POST /v1/alerts that fires a webhook when the condition matches.

The design goal was that a user never learns a command syntax. They talk to their agent the way they would talk to a friend who happens to be very good at finding things, and the skill quietly translates that into the right call.

Writing instructions for a model, not a parser

The hardest part of a skill file is not the API reference — it is the behavioral guidance. A good skill tells the agent not just what the endpoints are, but when to reach for them and how to present the result. Ours is explicit about a few things that would otherwise go wrong:

1. Always offer to verify before a purchase. Catalog prices are fresh but not guaranteed; the verify step is what makes a recommendation safe to act on.
2. Prefer showing a few strong matches over a long list. Agents that dump twenty results overwhelm a chat interface. Three good options with a clear best pick reads far better in a message.
3. Surface the freshness and the shop. "Verified 3 minutes ago, ships free to the US" builds trust that a bare price does not.

$ openclaw install opentraid

  installed integrations/opentraid/SKILL.md
  set OPENTRAID_API_KEY to enable live search
  done in 0.4s

You: find me a cashmere sweater under $150 that ships to the US, 20% off
Claw: Found 12 results across 5 shops.
      Best: Everlane Cashmere Crew
      $119.20 (was $168.00) - 29% off
      Verified 3 min ago - Free US shipping

Media matters more than you think

OpenClaw has a real media pipeline: it can send product thumbnails as actual image attachments in chat, not just links. For shopping that is the difference between a wall of text and something that feels like scrolling a curated feed. Our search response includes image URLs precisely so the agent can attach them, and we score product image quality as part of deciding which shops make the cut.

Why one file is the right unit

We could have built a heavier integration. We chose not to, because the friction of installation is where most agent capabilities die. A skill a user can add during a single conversation — no account juggling, no config file archaeology — is a skill they actually keep. The whole OpenTraid onboarding is: join the waitlist, get an API key, install one file, set one environment variable. Thirty seconds, and the agent can shop.

The same API that powers the OpenClaw skill is open to any agent framework. But OpenClaw is where we started, because its skill model proves a thesis we believe in: the best way to give an agent a new ability is to hand it a short, honest description of a good tool and get out of the way.