filtalgo/Filtmall-Shopping-Skill

Filtmall Shopping Skill – Agent‑native ecommerce

What it is

• A Node.js‑based skill that lets AI agents (e.g., OpenAI‑compatible agents) browse, compare, and purchase real‑world products from the Filtmall marketplace.
• Designed for “agent‑native” use: the skill returns structured data (price, specs, stock, timestamps) that an LLM can reason over and keep the conversation context across discovery, checkout, and after‑sales.

Key capabilities

Stage	What the skill does
Discover	Turns a natural‑language request (e.g., “moisturizing facial mask under ¥100”) into live product candidates from Filtmall’s catalog.
Decide	Provides side‑by‑side comparison of price, specifications, stock, and a same‑specification price from a public marketplace, showing the saving percentage.
Buy	Adds items to a persistent cart or runs a single‑SKU BUY_NOW flow via CLI commands.
Pay	Generates a buyer‑facing checkout link (desktop web or mobile H5) that the user opens to complete payment.
Follow‑up	Lets the agent query orders, track logistics, manage addresses, cancel eligible orders, and start after‑sales workflows.

How it works

• The agent calls a single CLI entry point (node scripts/filtalgo.js <command> --json).
• The CLI talks to Filtmall’s back‑end services (catalog, cart, checkout, order, logistics) and returns JSON results.
• The skill package includes the CLI runtime, agent‑side instruction files (SKILL.md, agents/openai.yaml), and metadata for the skills.sh marketplace.

Installation

# One‑line install via the skills.sh ecosystem
npx skills add filtalgo/Filtmall-Shopping-Skill --skill filtmall-shopping -g

• Requires Node.js 18+.
• No separate npm install needed because the repository bundles the CLI runtime.

Typical agent prompts

• Discovery: “I need a moisturizing facial mask under ¥100 that does not feel sticky.”
• Decision: “Compare the first and third products and explain which one fits sensitive skin better.”
• Transaction: “Did my payment go through?” / “Where is my latest order?”

Safety & user control

• The skill never performs a payment or account change without an explicit user request.
• All credentials, device codes, and tokens are kept private.
• Agents must present URLs (checkout, order details, after‑sales) for the user to open in a browser.
• For health‑related complaints (e.g., allergic reaction) the skill stops the flow and advises professional care.

Developer quick‑start

# Check the runtime and search the live catalog
node scripts/filtalgo.js doctor --json
node scripts/filtalgo.js search "想要保湿一点的面膜，预算 100 元以内，但别太黏" --json

# OAuth device flow for authenticated actions
node scripts/filtalgo.js auth login
node scripts/filtalgo.js auth status --json

# Cart & checkout example
node scripts/filtalgo.js cart add-item --way CART --sku-id <sku_id> --quantity 1 --json
node scripts/filtalgo.js checkout create --way CART --json
node scripts/filtalgo.js checkout prepare-payment <checkout_session_id> --link-channel mobile_h5 --json

# Order & logistics queries
node scripts/filtalgo.js order list --page-size 5 --json
node scripts/filtalgo.js logistics get <order_sn> --json

Tech stack

• Runtime: Node.js 18+ (bundled CLI runtime in assets/filtalgo-cli.cjs).
• Interface: Command‑line wrapper (scripts/filtalgo.js) exposing JSON‑encoded commands.
• Agent integration: Metadata files (SKILL.md, agents/openai.yaml) make the skill discoverable by platforms that support the skills.sh format.

Repository layout

SKILL.md                # Agent instructions & trigger metadata
references/            # Optional workflow rule files
scripts/filtalgo.js    # Thin CLI wrapper (entry point)
assets/filtalgo-cli.cjs# Bundled CLI runtime
agents/openai.yaml     # OpenAI‑compatible skill description
skills.sh.json         # skills.sh marketplace metadata
CHANGELOG.md           # Release notes
README.*               # Documentation (EN & CN)

Who might use it

• Developers building AI‑assistant products that need to let users shop for beauty/personal‑care items without leaving the conversation.
• Enterprises integrating a Chinese‑market ecommerce catalog into their LLM‑driven chatbots.
• Researchers exploring end‑to‑end agent workflows that include live commerce.

Limitations

• Catalog is currently focused on beauty and personal‑care products; broader categories are not yet covered.
• Payment and account actions still require the user to open a browser link; the skill does not handle credentials directly.
• Price advantage claims depend on live data from Filtmall and may vary by region, membership level, and promotions.

---

Bottom line: The Filtmall Shopping Skill is a concrete, production‑ready component that enables AI agents to perform a full ecommerce flow—product discovery, comparison, checkout, and post‑purchase support—using live data from the Filtmall platform, all wrapped in a simple Node.js CLI that agents can invoke via JSON commands.