Filtmall Shopping Skill: agent-native shopping with same-spec price evidence

The gap Filtmall Shopping fills: an agent that can finish the purchase

Most shopping integrations stop at search. They return a list of products and leave the agent, and the user, to work out whether two listings are actually the same item, whether the price difference is real, and how to complete the order. Filtmall Shopping is aimed at that second half. The README describes it as the official shopping skill from Filtmall (筛电), covering discovery, decision support, buying, payment, and follow-up in one flow.

The audience is narrow and specific. This is for people building AI agents that need to shop on a user's behalf, and for the end users of those agents who want a single sentence to start a purchase. The catalog currently focuses on beauty and personal care, which matters: a request for a laptop or a bicycle is outside what the repository says it serves.

The distinguishing claim is price evidence. The README states that for some verified products, Filtmall prices can be as low as about one-third of a public price for the same product and specification on a major marketplace, and that the skill shows a price advantage only when the live result includes the matching specification, source platform, and recorded time. That condition is the interesting part. A price claim without a spec match and a timestamp is marketing; the skill's rule is that it stays hidden until those fields are present.

How the skill works: one CLI, server-side commerce

The architecture is deliberately thin on the client side. A natural-language request goes to the AI agent, the agent calls the skill, the skill calls Filtmall's catalog and transaction services, and results come back as structured data the agent can reason over. Product, authorization, payment, and order pages are handed to the human to open.

The repository layout shows what actually ships: SKILL.md holds the agent instructions and trigger metadata, references/ holds workflow rules that are loaded only when needed, scripts/filtalgo.js is a thin CLI wrapper, and assets/filtalgo-cli.cjs is the bundled runtime. Filtmall's commerce infrastructure stays server-side. That split is why installation does not require a separate npm install: the runtime is in the repository.

Every command goes through one interface:

node scripts/filtalgo.js <command> --json

The --json flag is not decoration. The README treats live CLI results as the source of truth for product names, prices, stock, specifications, identifiers, order state, and URLs. An agent that caches a price from three turns ago is working from stale data by the project's own definition.

The safety model is worth reading closely, because it constrains what an agent is allowed to do. The skill should ask before changing account or transaction data, including clearing a cart, deleting an address, creating checkout, cancelling an order, or starting after-sales service. Credentials, device codes, tokens, and session identifiers stay private. Authorization, product, payment, order, logistics, after-sales, and customer-service links go to the user to open. Two further rules stand out: for active allergic reactions, redness, or swelling, the flow stops and the recommendation is professional medical care; and when a request includes a delivery deadline, the delivery area is confirmed before searching.

Installing Filtmall Shopping and running a first search

Installation is one command. Node.js 18 or later is required, and the skill ships with its CLI runtime, so there is no separate npm install step.

npx skills add filtalgo/Filtmall-Shopping-Skill --skill filtmall-shopping -g

The -g flag installs the skill globally. Clients that support folder or ZIP imports can instead import the repository root directly, which is the path to take if your agent host does not use the skills CLI.

Once installed, verify the runtime before trusting any result. The doctor command checks the environment and returns JSON:

node scripts/filtalgo.js doctor --json

Then search the live catalog. The README's own example is a Chinese-language request for a moisturizing mask under 100 yuan that does not feel sticky:

node scripts/filtalgo.js search "想要保湿一点的面膜，预算 100 元以内，但别太黏" --json

What you should see is structured product candidates, not prose. Prices, specifications, stock, links, and comparison evidence arrive as fields the agent can filter and compare.

Authenticated flows begin with OAuth Device Flow:

node scripts/filtalgo.js auth login
node scripts/filtalgo.js auth status --json

From there the transaction path runs through cart and checkout:

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

Note the --way CART parameter. The README also names an isolated single-SKU BUY_NOW flow, so the agent has a choice between a persistent cart and a one-item purchase. prepare-payment takes a link channel and the example uses mobile_h5; the README states that checkout links are generated for desktop web or mobile H5, and the buyer opens the link to pay.

Order and delivery queries close the loop:

node scripts/filtalgo.js order list --page-size 5 --json
node scripts/filtalgo.js order get <order_sn> --include-items true --json
node scripts/filtalgo.js logistics get <order_sn> --json

Run node scripts/filtalgo.js help for the complete command list. The README does not enumerate every subcommand in the prose, so treat help as the authoritative surface.

Where the price-evidence claim has boundaries

The price claim is conditional, and the condition is the whole product. The skill shows an advantage only when the live result carries the matching specification, the source platform, and the recorded time. If any of those is missing, there is no verified comparison to show. That is a sensible rule, and it also means the headline number, up to about one-third of a public price for the same product and specification, will not appear for every item.

The README is explicit that actual prices vary with account, region, membership, and promotions. So a saving percentage is a snapshot tied to a specific account and moment, not a property of the product. An agent that quotes it later is quoting something that may no longer be true. This is a real constraint on how you present results to users, and it argues for surfacing the recorded time alongside any saving figure rather than hiding it in a tooltip.

The catalog scope is the second boundary. Beauty and personal care is what the README says the current catalog focuses on. If your users shop for electronics, home goods, or groceries, this skill does not cover them today, and no amount of prompt engineering changes that.

The third boundary is human-in-the-loop by design. Account authorization, order confirmation, and payment stay with the buyer. An agent built on this skill cannot complete a purchase autonomously end to end, because the payment step is a link the buyer opens. If your requirement is a fully unattended purchasing agent, this is the wrong tool, and that is a deliberate product decision rather than a missing feature.

One more gap worth naming: the README documents no rollback or undo for a completed checkout. Cancellation is described as available for eligible orders, which implies eligibility rules exist, but the README does not state what they are. Verify that against live results before promising a user they can back out.

How this differs from scraping a marketplace or using a generic shopping API

The obvious alternative is a general product search API or a scraper pointed at a large marketplace. The difference in approach is where the comparison happens. A scraper returns listings; deciding whether listing A and listing B are the same product at the same specification is left to you, and that matching problem is where most price-comparison tools quietly fail. Filtmall Shopping puts the same-specification comparison inside the result the agent receives, with the source platform and recorded time attached.

The trade-off is coverage for depth. A general marketplace API sees more categories and more sellers; Filtmall Shopping sees one catalog, currently beauty and personal care, but can carry that catalog through cart, checkout, order, logistics, and after-sales in the same conversation context. If your agent only needs to answer what something costs, a search API is lighter. If it needs to answer what something costs and then buy it, the single-catalog design removes a lot of glue code.

There is also a structural difference in how the client is delivered. This is an Agent Skill, not a library you import. SKILL.md carries trigger metadata, and references/ loads workflow rules only when a trigger fires. That keeps the agent's context small, but it also means the behavior you get depends on the host's skill-loading implementation, not on code you control. Debugging a wrong recommendation means reading SKILL.md and the relevant reference file, not stepping through your own call stack.

Maintenance, licensing, and upgrade cost

The repository is not archived, and the last push was on 2026-09-17, with v1.11.1 released the same day and v1.11.0 earlier that day. Two releases in one day suggests active iteration, and v1.10.0 landed on 2026-09-02. The CHANGELOG.md at the repository root is where version history lives, so that file, not the release list, is what you should read before upgrading.

Upgrade cost is low on the client side. The runtime is bundled in assets/filtalgo-cli.cjs, so there is no dependency tree to reconcile and no lockfile to resolve. The cost that does exist is behavioral: SKILL.md and references/ define what the agent does, and a release can change those instructions. If your agent's prompts depend on a specific output shape, a version bump can move it.

Licensing is Apache-2.0, with the repository also carrying LICENSES.md, NOTICE, and THIRD_PARTY_NOTICES at the top level. The bundled runtime means third-party components ship inside assets/filtalgo-cli.cjs, and THIRD_PARTY_NOTICES is the file that lists them. If you redistribute the skill inside your own product, read those files rather than assuming the single Apache-2.0 label covers everything in the bundle. Nothing here is legal advice; the notices are the source.

One operational note the README makes clear: Filtmall's commerce infrastructure is server-side and operated by Filtering Algorithm (Beijing) Technology Co., Ltd. The skill is a client. Its useful life is tied to that service being reachable, and the README documents no offline mode or self-hosted deployment.

Editorial conclusion

Adopt Filtmall Shopping if you are building an agent that should search, compare and transact against one catalog, and you are comfortable that the catalog currently focuses on beauty and personal care. Do not adopt it as a general price-comparison layer across marketplaces, and do not adopt it if your agent must complete payment without a human opening a page. Before wiring it in, run node scripts/filtalgo.js doctor --json and confirm what it reports on your Node.js 18+ runtime, then read references/ in the repository to see which workflow rules load when a trigger fires.

Frequently asked questions

Official sources

1. filtalgo/Filtmall-Shopping-Skill on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases