Promotion Engine

Retail promotion calculator and discount lookup for digital employees. Computes final prices after applying discounts, bundles, thresholds, and membership ti...

Security Scan

The skill mostly matches its stated purpose (a promotions calculator) and has no network/install footprint, but the SKILL.md claims broader promotion handling than the included script implements and the runtime allows reading any JSON file path (potentially exposing unrelated data), so you should review and restrict inputs before use.

Purpose & Capability

Name/description = retail promotion calculator. The included script implements core threshold and percent discounts and membership discounts, which is coherent with the purpose. However SKILL.md advertises support for bundles, gifts, member_price, and more complex rules; the script does not implement bundle/gift/member_price parsing or bundle-specific logic. This is a functional mismatch (over-promised features).

Instruction Scope

SKILL.md instructs the agent to use scripts/calculate_promotion.py and a knowledge_base.json containing promotions[] and membership{}. The script reads an arbitrary --kb path (Path(args.kb).read_text()) and will JSON-load whatever file is passed. There is no guidance or enforcement limiting which file may be supplied; if the agent is given a path outside the intended KB, the script will read that file (if readable). This increases the risk of exposing or operating on unrelated sensitive JSON data. No network calls or external endpoints are present.

Install Mechanism

No install spec (instruction-only with a bundled script). Nothing is downloaded or written by an installer. The script itself is a local file and is executed directly; low installation risk.

Credentials

No required environment variables, no credentials, and no config paths declared. The script only needs a path to a JSON knowledge base and an items JSON payload — these are proportionate to the stated functionality. However, because the KB path is unrestricted, the opportunity to read arbitrary JSON files should be considered.

Persistence & Privilege

Skill is not always-enabled and does not request elevated/persistent privileges. It does not modify other skills or system configuration. Autonomous invocation is allowed by default (normal), but this combined with the unconstrained KB path is why caution is warranted.

What to consider before installing

What to consider before installing or using: - Functionality mismatch: the SKILL.md promises bundle/gift/member_price handling but the script only implements threshold and percentage discounts (and membership rate). If you need bundle/gift logic, ask the author to provide tests or implement those rules. - KB file access: the script reads whatever JSON file path you pass via --kb. Make sure the agent is only given a sanitized knowledge_base.json (no secrets, tokens, or unrelated sensitive data) and consider running the skill in a sandboxed environment. - Review/QA: inspect promo examples and test edge cases (bundles, BOGO, excluded items, stackability) with sample KBs before trusting customer-facing outputs. - Missing references: SKILL.md references references/promo-rules-guide.md which is not included; ask the publisher for that document if you need the authoritative rule parsing spec. - If you plan to allow autonomous agent runs, restrict the agent’s ability to choose arbitrary file paths or validate the --kb argument to prevent accidental data exposure.

Overview

This skill looks up active promotions and calculates final prices. It always shows its work (calculation steps) so customers trust the answer.

Depends on: promotions[] in knowledge base + membership{} config.

---

Query Types

Query	Example	Action
"What promotions are active?"	"现在有什么活动？"	List all active promos
"How much will I pay?"	"买两件怎么算？"	Calculate total
"Is this on sale?"	"这款打折吗？"	Check promo applicability
"How do I get the best deal?"	"怎么买最划算？"	Optimize purchase strategy
"Can I stack promos?"	"会员折扣和满减可以一起用吗？"	Check stackability

---

Calculation Steps

Always show calculation steps. Customers distrust "magic numbers."

Step 1: Identify applicable promotions

For each item in the cart/query:

1. Check promotions[] for active promos (not expired)
2. Filter by applicable_to scope (does this product qualify?)
3. Check excluded list (is this product excluded?)
4. Check membership tier for additional discounts

Step 2: Apply promotion rules

Use scripts/calculate_promotion.py for accurate computation.

Promotion types:

Type	Rule format	Example
threshold	满X减Y	满300减50
discount	X折 or X% off	8折, 20% off
bundle	买X件享Y价	买2件第2件半价
gift	满X赠品	满200赠小样
member_price	会员专属价	VIP价¥199

Step 3: Handle stacking

Check stackable field on each promotion.

• stackable: true → can combine with others
• stackable: false → use highest-value single promo
• When in doubt: use the rule that benefits the customer more

Step 4: Present result

Show original price → applicable promos → final price → total savings.

---

Answer Format

Single item query

这款连衣裙 原价：¥399
✨ 夏日大促：满300减50
会员折扣：9折（VIP专享）

最终价格：¥309（节省¥90）

Cart calculation

您的购物清单：
  白色连衣裙 ×1   ¥399
  条纹衬衫   ×1   ¥259
  小计：¥658

✨ 满300减50 → -¥50
✨ 满600再减80 → -¥80（两件合计超过600！）

最终合计：¥528（节省¥130 🎉）

No active promotions

目前[产品/全场]暂无特别优惠活动。
当前售价：¥[price]

---

Edge Cases

Conflicting promos: Always apply the rule that benefits the customer most. State which was applied.

Expired promo mentioned by customer: "这个活动已于[date]结束了，目前[有/没有]新的优惠。"

Promo not in KB but customer claims it exists: "我目前没有查到这个活动的信息，建议向店员确认一下，以免信息有误。"

Membership tier unknown: "您的会员等级我暂时查不到，建议核实后，会员专属折扣会自动应用。"

---

Script

Use scripts/calculate_promotion.py for accurate numeric calculation. Reference: promo-rules-guide.md — detailed rule parsing.