Skip to content
Back to search

cross-border-ecommerce-skills

58 个跨境电商 · DTC 品牌出海 AI 技能库:Amazon 运营、SEO/GEO、广告归因、财务、联盟、红人、线下零售、VOC、众筹。事实均标来源与日期,内置证据闸——数据不足时说「数据不足」,而不是编一个数字。| 58 skills for cross-border e-commerce & DTC: sourced, dated, with evidence gates. EN/中文. Works with Claude Code & Antigravity.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/noique--cross-border-ecommerce-skills/badge.svg)](/listings/noique--cross-border-ecommerce-skills)

HTML

<a href="/listings/noique--cross-border-ecommerce-skills"><img src="/api/listings/noique--cross-border-ecommerce-skills/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**Claude Code (recommended):**

git clone https://github.com/noique/cross-border-ecommerce-skills.git

# Single-file skills → ~/.claude/commands/
cp cross-border-ecommerce-skills/brand-strategy/*.md ~/.claude/commands/
cp cross-border-ecommerce-skills/amazon/*.md ~/.claude/commands/
cp cross-border-ecommerce-skills/finance/*.md ~/.claude/commands/

# Multi-file skill packages → ~/.claude/skills/ (one directory per skill)
cp -r cross-border-ecommerce-skills/outbound-prospecting/google-whatsapp-prospecting ~/.claude/skills/
cp -r cross-border-ecommerce-skills/outbound-prospecting/linkedin-prospecting ~/.claude/skills/
cp -r cross-border-ecommerce-skills/outbound-prospecting/media-press-discovery ~/.claude/skills/
cp -r cross-border-ecommerce-skills/voc-tools/reddit-voc ~/.claude/skills/
cp -r cross-border-ecommerce-skills/brand-strategy/serp-content-teardown ~/.claude/skills/
cp -r cross-border-ecommerce-skills/tools/backlink-kol-extractor ~/.claude/skills/

**Google Antigravity / OpenClaw / Any AI IDE:** Copy `.md` files (single-file skills) or whole directories (multi-file packages) into your skill directory.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 618 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Cross-Border E-Commerce AI Skills
  2. **58 AI-powered skill templates for cross-border e-commerce — from brand strategy to Amazon operations to DTC growth to finance & capital ops to affiliate-program building to EU channel entry to overseas-buyer prospecting + earned-media press discovery + Reddit pre-purchase VOC.**
  3. Compatible with Claude Code (`~/.claude/commands/`), Google Antigravity (`SKILL.md`), and any AI IDE with skill/prompt support.
  4. [中文说明](#中文说明) | [English](#english)
  5. ---
  6. ## English
  7. ### What is this?
  8. A collection of **58 AI agent skills** (structured prompt templates) that automate the entire cross-border e-commerce workflow — brand strategy, market research, product selection, listing optimization, advertising, DTC site operations, **finance & capital management**, **affiliate-program building**, **EU channel & market entry**, social media, influencer marketing, **overseas-buyer outbound prospecting**, **earned-media press discovery**, and **Reddit pre-purchase VOC**.
  9. Two formats:
  10. - **Single-file skills** (53) — one `.md` file each, drop into your AI IDE's skill directory.
  11. - **Multi-file skill packages** (5, under `brand-strategy/`, `outbound-prospecting/`, and `voc-tools/`) — `SKILL.md` + `references/` + `templates/` (incl. Python scripts and CSV trackers). Point your AI IDE at the package directory.
  12. Plus **7 standalone tools** under `tools/` (Python utilities used by skills, also runnable independently): `backlink-kol-extractor`, `trustpilot`, `linktree-expander`, `contact-extractor`, `api-pacer`, `fetchlib`, `browser-fetch`.
  13. ### Skill Map (58 skills across 13 chains)
  14. ```
  15. ┌─────────────────────────────────────┐
  16. │ Brand Strategy Chain (10) │
  17. │ │
  18. Market Scan ──► Track Hypothesis ──► Deep Validation ──► Strategy Plan
  19. │ │
  20. │ Annual Plan ◄── Budget Ops │
  21. │ ▼
  22. │ IMC Framework ──► Knowledge Base
  23. │ │
  24. │ A/B Compare Chart Visualize GTM Launch
  25. │ │
  26. ▼ ▼
  27. ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
  28. │ Amazon Chain (14) │ │ DTC Site (5) │ │ Social & KOL (5) │
  29. │ │ │ │ │ │
  30. │ Selection │ │ SEO Diagnostic │ │ TikTok Growth │
  31. │ Shortlist │ │ SEO Playbook │ │ YouTube Ops │
  32. │ Market Research │ │ SEM Ads │ │ Content Calendar │
  33. │ IP Risk │ │ Conversion UX │ │ Influencer Mktg │
  34. │ Supplier │ └──────────────────┘ │ User Lifecycle │
  35. │ Keywords │ └──────────────────┘
  36. │ Listing Copy │ ┌──────────────────┐ ┌──────────────────┐
  37. │ Main Image │ │ Offline (1) │ │ VOC Tools (3) │
  38. │ A+ Content │ │ │ │ │
  39. │ Compliance │ │ US Retail │ │ Reddit VOC (NEW) │
  40. │ Pre-Launch │ └──────────────────┘ │ Trustpilot Quick │
  41. │ Ad Architecture │ │ Trustpilot Deep │
  42. │ Weekly Ad Review │ └──────────────────┘
  43. │ Ad Diagnosis │
  44. └──────────────────┘
  45. ┌──────────────────────────────────────────────────────────────┐
  46. │ Finance & Capital (8) — NEW │
  47. │ Unit-Economics · FX/Payout · Tax-Nexus · Cashflow │
  48. │ Pricing · Reconciliation · Entity-Structure · Capital-Stack │
  49. └──────────────────────────────────────────────────────────────┘
  50. ┌──────────────────────────────────────────────────────────────┐
  51. │ Affiliate & Partnership (2) — NEW │
  52. │ Readiness-Audit (affiliate's-POV mirror of CRO) · │
  53. │ Program-Ops (AI: DB → score → outreach → activate → report) │
  54. └──────────────────────────────────────────────────────────────┘
  55. ┌──────────────────────────────────────────────────────────────┐
  56. │ Channel & Market Entry (2) — NEW │
  57. │ EU-Channel-Entry (SSPV · RCS · growth flywheel) · │
  58. │ Price-System & Channel-Conflict Guard │
  59. └──────────────────────────────────────────────────────────────┘
  60. ```
  61. ---
  62. ### Brand Strategy Chain (11 skills)
  63. **4-Round Analysis Pipeline + Planning + Execution + Tools**
  64. | Skill | What it does |
  65. |-------|-------------|
  66. | [brand-market-scan](brand-strategy/brand-market-scan.md) | Round 1: Market panoramic scan — 4-layer user insight, VOC matrix, competitive landscape, Semrush auto-scan |
  67. | [brand-track-hypothesis](brand-strategy/brand-track-hypothesis.md) | Round 2: Track hypothesis generation — 3-5 market tracks, DTNICE classification, GTM flywheel |
  68. | [brand-deep-validation](brand-strategy/brand-deep-validation.md) | Round 3: Deep hypothesis validation — 5D framework, SEO traffic model, benchmark cases, Zone 4 |
  69. | [brand-strategy-plan](brand-strategy/brand-strategy-plan.md) | Round 4: Brand strategy & execution — 7-element positioning, 4 pillars, pricing, narrative, roadmap |
  70. | [brand-imc-framework](brand-strategy/brand-imc-framework.md) | IMC integrated marketing — Audience/User dual-path, 6-stage funnel, channel mix, execution calendar |
  71. | [brand-event-marketing](brand-strategy/brand-event-marketing.md) | Moment/event marketing — 4 event types, calendar + trend-jacking SOPs, ambush-marketing legal gate |
  72. | [crowdfunding-launch](brand-strategy/crowdfunding-launch.md) | Kickstarter/Indiegogo launch — FTC delivery gate, verified fee stack, 4-phase SOP, post-campaign DTC flywheel |
  73. | [attribution-measurement](brand-strategy/attribution-measurement.md) | Measurement stack — MMM + incrementality + attribution triangulation, geo-test design, Meridian vs Robyn |
  74. | [brand-annual-plan](brand-strategy/brand-annual-plan.md) | Annual planning — BSC scorecard, 52-week calendar, quarterly OKRs, resource allocation |
  75. | [brand-budget-ops](brand-strategy/brand-budget-ops.md) | Budget planning & control — 10-category budget model, monthly tracking, ROI by channel |
  76. | [brand-knowledge-base](brand-strategy/brand-knowledge-base.md) | Obsidian knowledge base — batch-creates 30-50 interlinked .md files from all rounds |
  77. | [brand-ab-compare](brand-strategy/brand-ab-compare.md) | 8-dimension A/B quality comparison between two brand strategy report sets |
  78. | [brand-chart-visualize](brand-strategy/brand-chart-visualize.md) | Auto-generate charts (radar, bar, waterfall, scatter, etc.) via AntV API for all reports |
  79. | [report-pdf-export](brand-strategy/report-pdf-export.md) | Convert any finished report Markdown into a house-styled PDF (A4 landscape, dark-blue headers, zebra rows, page numbers). The most-reused skill in the repo — **37 other skills chain into it** for their final deliverable |
  80. ### Amazon Operations Chain (14 skills) — UPGRADED v3.14 (2026 algorithm & policy refresh)
  81. | Phase | Skill | What it does |
  82. |-------|-------|-------------|
  83. | Selection | [amazon-product-selection](amazon/amazon-product-selection.md) | Score and rank Top 30 potential products |
  84. | Selection | [amazon-product-shortlist](amazon/amazon-product-shortlist.md) | Feasibility screening, GTM flywheel check, Go-List |
  85. | Research | [amazon-market-research](amazon/amazon-market-research.md) | Full market research: VOC matrix, competitor teardown, SWOT |
  86. | Research | [amazon-ip-risk-assessment](amazon/amazon-ip-risk-assessment.md) | Patent + trademark risk, design comparison, risk rating |
  87. | Research | [amazon-supplier-decision](amazon/amazon-supplier-decision.md) | Supplier evaluation, cost breakdown, red flag detection |
  88. | Listing | [amazon-keyword-research](amazon/amazon-keyword-research.md) | Keyword library: 3-tier CPC, COSMO + Alexa-for-Shopping AI-search SEO |
  89. | Listing | [amazon-listing-copywriter](amazon/amazon-listing-copywriter.md) | Title + Item Highlights (3 candidate versions each), bullet points, A+ description, Search Terms |
  90. | Listing | [amazon-main-image-prompt](amazon/amazon-main-image-prompt.md) | Main + secondary image design briefs and AI prompts |
  91. | Listing | [amazon-aplus-image-prompt](amazon/amazon-aplus-image-prompt.md) | A+ Content module layout, Brand Story, image prompts |
  92. | Launch | [amazon-compliance-review](amazon/amazon-compliance-review.md) | 3-dimension audit: platform rules, legal/IP, AI-agent readiness |
  93. | Launch | [amazon-pre-launch-review](amazon/amazon-pre-launch-review.md) | Final pre-launch checklist across all SKILL outputs |
  94. | Ads | [amazon-ad-architecture](amazon/amazon-ad-architecture.md) | PPC structure: SP/SB/SD + Prompts ads, AMC, placement/bid strategy |
  95. | Ads | [amazon-weekly-ad-review](amazon/amazon-weekly-ad-review.md) | Weekly ad review: ACoS/TACoS, Search Terms, action list |
  96. | Ads | [amazon-ad-diagnosis](amazon/amazon-ad-diagnosis.md) | Existing product diagnosis: 4-stage optimization pipeline |
  97. ### DTC Site & Traffic (5 skills)
  98. | Skill | What it does |
  99. |-------|-------------|
  100. | [dsite-seo-diagnostic](brand-strategy/dsite-seo-diagnostic.md) | **NEW** — Entry-orchestrator skill for live-site SEO traffic-drop diagnostics. 7-dimension diagnosis (traffic curve / keyword loss / single-point risk / i18n pollution / backlink quality / content ROI / KPI audit) → algorithm-event alignment → restart roadmap. Chains `xlsx` / `dsite-seo-playbook` / `trustpilot-voc-deep` / `competitors-analysis` / `backlink-kol-extractor` / `report-pdf-export`. Output: deliverable PDF (A4 landscape, hides internal SKILL refs). |
  101. | [dsite-seo-playbook](brand-strategy/dsite-seo-playbook.md) | Full SEO playbook: technical audit, keyword strategy, content plan, Core Web Vitals |
  102. | [dsite-sem-ads](brand-strategy/dsite-sem-ads.md) | SEM & paid ads: 10-platform comparison, AIPL funnel, budget allocation |
  103. | [dsite-conversion-ux](brand-strategy/dsite-conversion-ux.md) — **UPGRADED v3.7** | Live-site **CRO audit / 转化率检测**, rebuilt for **multi-agent concurrency on Claude Code**. **Step 0** fans out 5 parallel recon subagents (PDP / discovery / trust / checkout / competitor) via the `Workflow` tool with `StructuredOutput` schemas → reconPool → parallel **6-module framework** (trust / discovery / product-info / checkout / AOV-LTV / urgency) — retail-analogy CRO × Shopify benchmarks × ICE A/B × AICPL LPO × 35-day welcome flow. v3.7 adds a **technical-health & tracking-integrity check** (console errors / pixel firing / CWV / 404 / mobile-sticky — broken tracking silently invalidates all measurement → highest-priority finding), a mandatory **copy-rewrite table** (current → A/B) + **objection-handling table**, a **quick-win vs high-impact dual-bucket** with wall-clock effort, and A/B **stop-rule discipline**. Honesty preserved — data-credibility statement kept, lift figures stay ⚠️ hypotheses (no fabricated funnel numbers). Uses **browser-class MCP** (Claude in Chrome / Preview) for what static fetch can't see; chains `/dsite-seo-playbook` / `/dsite-sem-ads` / `/report-pdf-export`. |
  104. | [serp-content-teardown](brand-strategy/serp-content-teardown/SKILL.md) — **NEW v3.6** | Multi-file skill: deterministic (no-LLM) SERP/content reverse-engineering from local Semrush xlsx + competitor HTML. Parses serp_urls + broad-match, curl-fetches top competitor articles (html5lib void-tag-safe), computes per-article structure → **8 article archetypes** + opening/closing patterns, then keyword distribution + core keywords, backlink/authority thresholds (Page AS / Ref.Domains / Backlinks) + weak-link winners, AI-Overview (GEO) saturation + schema readiness, on-page SEO. Output: per-topic content blueprint (which archetype / word / H2 / schema / FAQ / keyword / authority / GEO posture). Pairs with `backlink-kol-extractor` (links) + `structured-data-buildout` (schema). |
  105. ### Finance & Capital (8 skills) — NEW v3.8
  106. Operator-facing finance/CFO chain for China→US/EU DTC + Amazon sellers — the actuals / profitability / tax / cash / financing side that the planning-oriented `brand-budget-ops` doesn't cover. Every skill is grounded in real tools + 2026 regulations, carries an explicit **YMYL disclaimer** (planning aid, NOT professional tax/legal/accounting advice — verify with a licensed CPA), and tags every rate/threshold/date as point-in-time. Built and cross-validated from a dual-source research pass (multi-agent web research + an independent deep-research report).
  107. | Skill | What it does |
  108. |-------|-------------|
  109. | [finance-landed-cost-unit-economics](finance/finance-landed-cost-unit-economics.md) | **Anchor** — fully-loaded landed cost → **CM1/CM2/CM3** waterfall → break-even ROAS/ACoS → per-SKU keep/kill/reprice + tariff/return sensitivity. Folds in Amazon 2026 fee changes (inbound placement ↑, Low-Inventory-Level Fee, fuel/inflation surcharge). |
  110. | [finance-fx-payout-optimizer](finance/finance-fx-payout-optimizer.md) | Collection · 结汇 · FX hedging. The "two numbers" (gross revenue vs RMB cash-landed) + FX-drag %, provider benchmark (PingPong/WorldFirst/Airwallex/Payoneer/Wise vs ACCS), natural-hedge plan, and a SAFE / 单证一致 compliance checklist (incl. the 2026-01-01 ≥¥5,000 AML monitoring). |
  111. | [finance-tax-nexus-vat-diagnostic](finance/finance-tax-nexus-vat-diagnostic.md) | Per-jurisdiction registration-obligation map + filing calendar + EPR streams. Covers EU OSS/IOSS, the **€3 fixed customs duty** (Reg (EU) 2026/382 — kept distinct from the not-yet-law ~€2 handling fee), UK £135, US economic nexus, and China 9610/9710/9810 + 出口退税. |
  112. | [finance-cashflow-runway-forecaster](finance/finance-cashflow-runway-forecaster.md) | CCC (DIO/DSO/DPO) + a **13-week** rolling direct-method forecast that models the Amazon DD+7/DDBR reserve correctly + a reorder-point capital trade-off → flags the week cash goes negative. |
  113. | [finance-pricing-margin-guard](finance/finance-pricing-margin-guard.md) | Dynamic price floor/ceiling, break-even ROAS = 1/CM%, FX-sensitivity-per-1%, marketplace price-parity + anti-gouging guardrails — fixes the static-floor trap when 2026 fees rise. |
  114. | [finance-reconciliation-bookkeeping](finance/finance-reconciliation-bookkeeping.md) | Multi-channel gross-to-net reconciliation (Amazon settlement / Shopify-Stripe-PayPal payouts → bank) via the clearing-account-to-zero method, an ecommerce chart of accounts, COGS/inventory valuation. Tools: A2X / Link My Books / Synder / Finlens → QuickBooks / Xero. |
  115. | [finance-entity-structure-advisor](finance/finance-entity-structure-advisor.md) | Entity tier (single HK Ltd → ODI → HK/SG holding → US LLC) with a "you don't need this yet" guardrail, the LRD transfer-pricing model, HK TP-doc exemption, and the 4-gate China profit repatriation. **YMYL-heavy.** |
  116. | [finance-capital-stack-advisor](finance/finance-capital-stack-advisor.md) | Normalizes any RBF/MCA flat-fee quote to a true **effective APR** at real repayment speed (Monte-Carlo), a provider-fit matrix (Wayflyer/Clearco/8fig/Amazon Lending), UCC-1-lien / exclusivity contract traps, and chargeback/VAMP defense. |
  117. ### Social Media & Content (3 skills)
  118. | Skill | What it does |
  119. |-------|-------------|
  120. | [tiktok-growth](brand-strategy/tiktok-growth.md) | TikTok full-funnel growth: content strategy, TikTok Shop, livestream, paid ads |
  121. | [youtube-channel-ops](brand-strategy/youtube-channel-ops.md) | YouTube channel operations: content strategy, SEO, monetization |
  122. | [social-content-calendar](brand-strategy/social-content-calendar.md) | Social media content calendar: multi-platform scheduling, content pillars |
  123. ### VOC & Review Analysis (3 skills) — NEW v3.5 adds pre-purchase VOC
  124. VOC tools split by decision stage. Reddit / Quora capture **pre-purchase** intent (still-deciding users), while Trustpilot / Amazon Review capture **post-purchase** experience (already-bought users). Use them together for full decision-funnel coverage.
  125. | Skill | What it does |
  126. |-------|-------------|
  127. | [reddit-voc](voc-tools/reddit-voc/SKILL.md) — **NEW v3.5** | Multi-file package for **pre-purchase** Reddit VOC mining. 5-step playbook (find subs across 4 dimensions → filter Top + 6 post-flair → 6-axis post teardown → insight-to-action mapping → optional 2D positioning matrix). References: 4-dimension community framework / Reddit slang dictionary (BIFL / YMMV / AITA / DAE / etc.) / 6-class post taxonomy with business-action mapping / 3 real listing+ad rewrite cases / functional-importance × satisfaction matrix. CSV templates for community map, post analysis, insight-action map. Pairs with `/trustpilot-voc-deep` for post-purchase view. |
  128. | [trustpilot-voc-quick](brand-strategy/trustpilot-voc-quick.md) | 5-min WebFetch scan: overall rating, star distribution, recent review summaries. Ideal for brand scanning Step 0 or competitor comparison |
  129. | [trustpilot-voc-deep](brand-strategy/trustpilot-voc-deep.md) | Full pipeline (15-40 min): Selenium scraper with proxy rotation + sentiment analysis + LDA topic modeling + AI-powered deep insights. Uses `tools/trustpilot/` Python toolkit with **AntV visualization** for report-style consistency |
  130. ### KOL & User Operations (2 skills)
  131. | Skill | What it does |
  132. |-------|-------------|
  133. | [influencer-marketing](brand-strategy/influencer-marketing.md) | KOL/influencer marketing: 5-tier pyramid, ROI tracking, contract templates |
  134. | [user-lifecycle-ops](brand-strategy/user-lifecycle-ops.md) | User lifecycle management: 5-stage funnel, retention curves, churn analysis |
  135. ### GTM & Offline (2 skills)
  136. | Skill | What it does |
  137. |-------|-------------|
  138. | [brand-gtm-launch](brand-strategy/brand-gtm-launch.md) | New product GTM launch: 7-step framework, timeline, channel coordination |
  139. | [offline-retail-us](brand-strategy/offline-retail-us.md) | US offline retail: 8-tier channel analysis, readiness assessment, cost model |
  140. ### Affiliate & Partnership (2 skills) — NEW v3.13
  141. Building an affiliate/partnership program from the **affiliate's economics** — audit first (is your product even worth promoting?), then run the AI-automated recruit → score → outreach → activate loop. Complements `influencer-marketing` (content/relationship lens) without overlap: this is the performance/ROI lens.
  142. | Skill | What it does |
  143. |-------|-------------|
  144. | [affiliate-readiness-audit](brand-strategy/affiliate-readiness-audit.md) — **NEW v3.13** | Audits a product/Listing from the **affiliate's wallet POV** — the mirror of `dsite-conversion-ux` (CRO): CRO audits "why users won't buy," this audits "why affiliates won't promote you." Affiliate ROI ledger + EPC + 3-layer arbitrage, 6-dim recruitability scorecard with score bands, admission buckets, 6 silent-rejection red flags, traffic-catch self-check + 30-day fix roadmap. Multi-agent fan-out over the 6 scoring dimensions + competitor-offer benchmark |
  145. | [affiliate-program-ops](brand-strategy/affiliate-program-ops.md) — **NEW v3.13** | AI-automated affiliate operations pipeline: database → find candidates across the **6 affiliate ecosystems** → 100-pt AI scoring with priority bands → standardized contact collection (10 sources) → AI personalized outreach (5-element email, not mass blast) → Partner Resource Hub activation → 4-layer KPI + AI weekly report → 30-day minimum loop. Fan-out per ecosystem type via `Workflow`; reuses `outbound-prospecting` infra + `backlink-kol-extractor` |
  146. ### Channel & Market Entry (2 skills) — NEW v3.13
  147. | Skill | What it does |
  148. |-------|-------------|
  149. | [eu-channel-market-entry](brand-strategy/eu-channel-market-entry.md) — **NEW v3.13** | Channel/distributor-driven Europe market entry for **US-entity brands**: US-vs-EU market logic (growth vs mature-replacement), competitive-positioning quadrant, **SSPV** user-value model (JTBD-based), **RCS** regional-combat model (Region × Channel × Service) across the 5 EU regions, channel development + enablement, price protection, overseas-org 3 stages, the 8-step Europe growth flywheel. Org/tax decisions hand off to `finance-*`. 5-region parallel analysis via `Workflow` |
  150. | [price-system-conflict-guard](brand-strategy/price-system-conflict-guard.md) — **NEW v3.13** | Multi-channel price-system & channel-conflict guard for brands running DTC + Amazon + distribution simultaneously: cross-channel real-price diagnosis (auto-flags conflicts), the 3-layer mechanism (unified price × promo-sync × regional protection), DTC-vs-channel boundary, T-60 promo SOP. Carries a US antitrust (MAP vs RPM / Sherman Act) compliance boundary. Pluggable impl of the flywheel's price-protection step |
  151. ### Outbound Prospecting (3 skills) — v3.4 adds press discovery
  152. End-to-end pipelines for finding overseas B2B decision-makers, KOLs, and journalists, then converting them into ready-to-message lead sheets. Each skill is a multi-file package with `SKILL.md` + scripts + references + templates.
  153. | Skill | What it does |
  154. |-------|-------------|
  155. | [google-whatsapp-prospecting](outbound-prospecting/google-whatsapp-prospecting/SKILL.md) | Google-dork → WhatsApp lead pipeline. 15+ search formulas (mobile-prefix narrowed), 30+ countries with B2B-platform / time-zone / compliance flags, full GDPR-CASL-CCPA-UWG compliance reference, multi-language outreach playbook (EN/ES/PT/FR/AR), SerpAPI batch script + `wa.me` validator. |
  156. | [linkedin-prospecting](outbound-prospecting/linkedin-prospecting/SKILL.md) | Google/Bing/Yandex/Wayback reverse-search of LinkedIn → enrichment via Apollo/Snov/Hunter/Lusha/Wiza → 4-touch outreach (CR → DM → follow-up → channel-switch). 50+ localized role keywords across 8 languages, LinkedIn ToS + quota reference, 12 DM templates across 5 archetypes (incl. voice-note opener), reply-handling matrix. |
  157. | [media-press-discovery](outbound-prospecting/media-press-discovery/SKILL.md) — **NEW v3.4** | Muckrack-anchored journalist DB pipeline. 5 scripts (`discover_journalists` / `find_articles` / `guess_emails` / `score_and_export` / `merge_partitions`) + shared `_fetcher.py` with 4 backends (requests / remote-chrome / apify / html-dir for Cloudflare-protected pages). Multi-machine partition-merge workflow. Outputs ranked `pitch_db.csv` with journalist contacts + last topical coverage. |
  158. Sister skills — same 4-stage shape (Search → Enrich → Outreach → Compliance), different channels. Designed to run in parallel for the same lead set.
  159. ### Tools (standalone utilities)
  160. Standalone Python utilities under `tools/`. Each is a multi-file package with own `SKILL.md` + `scripts/` + `references/` + `templates/`. Used by skills above conditionally; also runnable independently. The three **fetch tools** — `api-pacer`, `fetchlib`, `browser-fetch` — compose into one compliant scraping pipeline (**pace → waterfall → browser L3**); the rest are data/enrichment utilities.
  161. | Tool | What it does | Used by |
  162. |------|-------------|---------|
  163. | [backlink-kol-extractor](tools/backlink-kol-extractor/SKILL.md) | Extract KOL / media / affiliate prospects from Semrush competitor backlink xlsx data — 3-step methodology (domain pattern → cross-competitor validation → social handle extraction) | `influencer-marketing` (Step 2.5), `dsite-seo-playbook` (Step 4.6) — both conditionally activated when Semrush data is provided |
  164. | [trustpilot](tools/trustpilot/) — **rebuilt v3.4** | Selenium-based Trustpilot review scraper with chained-proxy rotation, AI sentiment + topic analysis, multi-language. v3.4 rebuild: modern data-* attribute selectors (replaces 110-line sibling-XPath fallback chain), desktop-UA pin (Trustpilot serves snippet-only DOM to mobile UA), `--cutoff_date` arg, `--skip_ai` mode, redacted hardcoded proxy creds (env-var loading) | `trustpilot-voc-quick`, `trustpilot-voc-deep` |
  165. | [linktree-expander](tools/linktree-expander/SKILL.md) — **NEW v3.4** | Batch-enrich Linktree handles into per-creator profiles via `__NEXT_DATA__` JSON parsing. Extracts IG / TikTok / YouTube / Substack / Twitter / podcast handles + bio + outbound link categorization + handle-match-scored personal_site (with `NON_PERSONAL_HOSTS` blocklist for shorteners / aggregators / docs / scheduling) | KOL discovery pipelines downstream of `backlink-kol-extractor` |
  166. | [contact-extractor](tools/contact-extractor/SKILL.md) — **NEW v3.4** | Multi-source contact email extraction with confidence tiering. Sources: personal_site `/about` `/contact` `/press` paths (mailto/text) + YouTube Data API v3 description + Apple Podcasts RSS owner + email pattern guess (with `--verify` SMTP MX probe / Hunter.io). Outputs ranked `contact_email_1..3` + `confidence` (high / medium / low / none) | KOL outreach prep, post `linktree-expander` or `media-press-discovery` |
  167. | [api-pacer](tools/api-pacer/SKILL.md) — **NEW v3.9** | Polite, adaptive request pacer + AWS-style full-jitter backoff. Paces to the server's own `x-ratelimit-*` headers when present, else a configured RPS budget. Stdlib-only; rate-limit-respecting research use only. Rationale + usage in `SKILL.md`. | `reddit-voc` (wired) + `serp-content-teardown` / `media-press-discovery` / `trustpilot` / `outbound-prospecting` (opt-in) |
  168. | [fetchlib](tools/fetchlib/SKILL.md) — **NEW v3.10** | Compliant fetch **waterfall** — escalates one tier only on a real block: **L1 `curl_cffi`** → **L2 Jina Reader** → L3 browser → L4 managed (paid, opt-in). Control = `api-pacer` + AIMD + circuit breaker + Thompson-sampling backend selector. Honors robots; no barrier-defeat / IP-rotation / PII. Tiers, benchmarks + compliance red line in `SKILL.md`. Depends on `api-pacer`. | `serp-content-teardown` / `media-press-discovery` / `trustpilot` / `outbound-prospecting` / `reddit-voc` (opt-in) |
  169. | [browser-fetch](tools/browser-fetch/SKILL.md) — **NEW v3.12** | Optional shared **browser-render** backend for `fetchlib`'s **L3** (pluggable engine, **default Selenium**). Clears **Trustpilot-class** JS sites but not Cloudflare / DataDome fortresses (those need a residential IP or paid unblocker — full honest-scope benchmark in `SKILL.md`). No CAPTCHA-solving / barrier-defeat / PII; `tools/trustpilot` left untouched. | any JS-render need via `fetchlib` `browser` tier (opt-in) |
  170. See [tools/README.md](tools/README.md) for standalone usage.
  171. ---
  172. ### Key Features
  173. - **58 Skills, 13 Chains** — Complete coverage from brand strategy to daily operations to finance & capital to affiliate-program building to EU channel entry to overseas-buyer outbound to earned-media press discovery to pre-purchase Reddit VOC
  174. - **Affiliate & Channel Systems (2026 decks)** — a 2-skill affiliate chain built from the affiliate's own economics (`affiliate-readiness-audit` mirrors CRO — "why affiliates won't promote you"; `affiliate-program-ops` runs the AI recruit→score→outreach→activate loop), plus a US-entity Europe channel-entry strategy (SSPV / RCS / growth flywheel) and a multi-channel price-conflict guard. Framework skeletons only, each crediting its source deck in a methodology index
  175. - **Finance & YMYL Discipline** — the 8-skill finance chain carries explicit "planning aid, not professional tax/legal/accounting advice — verify with a CPA" disclaimers, point-in-time-stamped 2026 regulations, and ⚠️-flagged estimates (no fabricated numbers)
  176. - **Data Verification Layer** — Every skill includes mandatory verification; estimates are explicitly flagged with ⚠️
  177. - **Chart Visualization** — 21 skills auto-generate charts (radar, bar, waterfall, scatter, funnel, etc.) via AntV API
  178. - **Semrush Integration** — Brand strategy skills auto-scan local Semrush xlsx/PDF data as high-confidence source
  179. - **VOC Matrix** — Mention frequency × satisfaction matrix to identify unmet needs
  180. - **GTM Flywheel** — Market → Product → Marketing → Operations four-wheel evaluation
  181. - **AI Search Ready** — Optimized for Amazon Rufus, COSMO knowledge graph, and GEO
  182. - **Multi-Agent Concurrency (Claude Code-native)** — skills like `dsite-conversion-ux` orchestrate parallel recon + analysis subagents via the `Workflow` tool with `StructuredOutput` schemas, run as background tasks, and use browser-class MCP (Claude in Chrome / Preview) for live-site inspection — fan out the work, keep the conclusions
  183. - **Compliant Scraping Stack (2026-benchmarked)** — a free-first, US-compliant fetch pipeline the skills share: `api-pacer` (pacing + backoff) → `fetchlib` (waterfall: `curl_cffi` → Jina Reader → browser → paid) → `browser-fetch` (browser-render L3). Honors robots + rate limits; no barrier-defeat / IP-rotation / CAPTCHA-solving / PII. Benchmarks, tier mechanics, and the full compliance red line live in each tool's `SKILL.md`
  184. - **Linted, not just written** — every skill carries `name` + `description` frontmatter (the triggering surface), and a `Skill lint` CI gate blocks four regressions this repo actually hit: missing/mismatched frontmatter, the same skill living at two paths (copies drift apart silently), dead relative links, and any advice that would break the scraping red line. Run it locally with `python3 scripts/lint_skills.py`
  185. - **Multi-Platform** — Works on Claude Code, Google Antigravity, OpenClaw, and any AI IDE
  186. ### Installation
  187. **Claude Code (recommended):**
  188. ```bash
  189. git clone https://github.com/noique/cross-border-ecommerce-skills.git
  190. # Single-file skills → ~/.claude/commands/
  191. cp cross-border-ecommerce-skills/brand-strategy/*.md ~/.claude/commands/
  192. cp cross-border-ecommerce-skills/amazon/*.md ~/.claude/commands/
  193. cp cross-border-ecommerce-skills/finance/*.md ~/.claude/commands/
  194. # Multi-file skill packages → ~/.claude/skills/ (one directory per skill)
  195. cp -r cross-border-ecommerce-skills/outbound-prospecting/google-whatsapp-prospecting ~/.claude/skills/
  196. cp -r cross-border-ecommerce-skills/outbound-prospecting/linkedin-prospecting ~/.claude/skills/
  197. cp -r cross-border-ecommerce-skills/outbound-prospecting/media-press-discovery ~/.claude/skills/
  198. cp -r cross-border-ecommerce-skills/voc-tools/reddit-voc ~/.claude/skills/
  199. cp -r cross-border-ecommerce-skills/brand-strategy/serp-content-teardown ~/.claude/skills/
  200. cp -r cross-border-ecommerce-skills/tools/backlink-kol-extractor ~/.claude/skills/
  201. ```
  202. **Google Antigravity / OpenClaw / Any AI IDE:**
  203. Copy `.md` files (single-file skills) or whole directories (multi-file packages) into your skill directory.
  204. ### Model Requirements
  205. **Judge by capability, not by model name.** What these skills actually need is three things — the model list below expires every few months, this bar doesn't:
  206. | Capability | Why these skills need it |
  207. |---|---|
  208. | **Instruction-following across long context** | A single skill runs 10-50KB; the model has to still follow the structure after reading the whole spec |
  209. | **Actually executing multi-step verification** | The library leans hard on self-checks — count the bytes, cite the source, mark `❌未获取` when it's missing. A model that skips verification and jumps to the conclusion turns every honesty guardrail into decoration |
  210. | **Short-delivering honestly instead of filling the gap** | When evidence is thin it has to write "insufficient data, no conclusion" rather than inventing a plausible number to complete the table |
  211. > 🔴 **The second and third are the dividing line.** Following a structure is easy — plenty of mid-size models emit a report that *looks* complete. The hard part is **leaving blank what should be blank**. Test a candidate model by feeding it an input with a key figure missing and seeing whether it flags the gap or invents a number.
  212. ### 🔴 "The skill doesn't run" — check the runtime before the skill
  213. **Maintainer's field observation (not a controlled benchmark):** these skills behave best on **stock Claude Code running against Anthropic's own API/subscription**. Reports of a skill "not working" have mostly traced back to the runtime, not the skill file — Claude Code pointed at a third-party relay or reseller subscription, or a different harness (Codex-style and other agent CLIs) loading the file.
  214. Why the runtime matters more here than for a plain prompt:
  215. | What the skills rely on | What a substituted runtime often breaks |
  216. |---|---|
  217. | The harness **loading `SKILL.md` and honoring its frontmatter** | `SKILL.md` + frontmatter is a Claude Code convention. Another harness may treat the file as plain context — or not load it at all — so the skill silently never activates |
  218. | **Full-fidelity long context** (10-50KB per skill, plus your data) | Relays commonly truncate, compress, or re-chunk context. The verification rules live throughout the file — drop the tail and the honesty gates go with it |
  219. | **A specific model actually serving the request** | Some resellers route "Claude" traffic to a different or quantized model without saying so. You get output shaped like the skill with none of the self-checking behavior |
  220. | **Multi-step self-verification surviving the system prompt** | Harnesses that rewrite or prepend their own system prompt can override the skill's verification instructions |
  221. **Self-diagnose in this order before filing an issue:**
  222. 1. **What's actually serving you?** Confirm the runtime and that requests hit the model you think they do — not a relay in between.
  223. 2. **Did the skill load at all?** Ask the agent to restate the skill's required output sections. If it can't, the file never activated — that's a loading problem, not a skill problem.
  224. 3. **Run the blank test.** Feed an input with a key figure missing. Correct behavior is flagging the gap (`❌未获取` / "insufficient data"). If it invents a number, the honesty scaffolding isn't running, whatever the model claims to be.
  225. If all three pass and it still misbehaves, that's a real skill bug — please open an issue with the transcript.
  226. > This is one maintainer's testing across the setups they had access to, not a benchmark of every provider. Third-party relays vary widely; some may be fine. The point is that **the runtime is the first thing to rule out**, because it accounts for most of the "doesn't work" reports.
  227. **Reference models (verified 2026-08 — will go stale)**
  228. | Tier | Quality | Models at the time |
  229. |------|---------|--------------------|
  230. | Recommended | Full execution, verification works | Claude Opus 5 / Sonnet 5 (and Fable 5), GPT-5.6 Sol / GPT-5.5 family, Gemini 3.1 Pro |
  231. | Usable | Structure OK, may skip verification | DeepSeek V4, Qwen 3.5, GLM-5.2, Llama 4, Claude Haiku 4.5 |
  232. | Not recommended | Sections missing, checks fail | Small models (empirically, under ~30B) |
  233. > ⚠️ **This table goes stale by design** — the previous version sat at April 2026 and was already two Claude generations behind. **Don't copy the names; use the capability bar above to test whatever you have.** Current lineups: [Anthropic](https://platform.claude.com/docs/en/about-claude/models/overview) · [OpenAI](https://platform.openai.com/docs/models) · [Google](https://ai.google.dev/gemini-api/docs/models).
  234. > The Claude row comes from Anthropic's own docs; the rest is public reporting collated 2026-08 — vendors ship on different cadences, so treat each vendor's docs as authoritative.
  235. Key requirements: long context (8K+ input), strong instruction following, Chinese-English bilingual, tool use / web browsing.
  236. ---
  237. ## 中文说明
  238. ### 这是什么?
  239. 一套 **58 个跨境电商 AI 技能模板**,覆盖品牌战略→选品→调研→文案→广告→独立站→**财务资金**→**联盟营销**→**欧洲渠道进入**→社媒→红人→线下渠道→海外开发→媒体公关→**购买前 Reddit VOC** 全流程自动化。
  240. 两种格式:
  241. - **单文件技能(53 个)** — 一个 `.md` 文件,放入 AI IDE 技能目录即可使用
  242. - **多文件技能包(5 个,分布在 `brand-strategy/`、`outbound-prospecting/` 和 `voc-tools/`)** — `SKILL.md` + `references/` + `templates/`(含 Python 脚本和 CSV 跟踪表),将整个目录指向 AI IDE
  243. 外加 **7 个独立工具** 在 `tools/`(Python 工具,被 skill 调用也可独立使用):`backlink-kol-extractor` / `trustpilot` / `linktree-expander` / `contact-extractor` / `api-pacer` / `fetchlib` / `browser-fetch`。
  244. ### 技能矩阵(58 个技能,13 条链路)
  245. | 链路 | 数量 | 技能 |
  246. |------|------|------|
  247. | **品牌战略链** | 11 | 市场扫描 → 赛道假设 → 深度验证 → 品牌战略 → IMC框架 → 年度规划 → 预算管控 → 知识库 → A/B对比 → 图表可视化 → 报告 PDF 导出(全库被复用最多,37 个技能链它出终稿) |
  248. | **Amazon 运营链** | 14 | 选品 → 筛选 → 调研 → IP排查 → 供应商 → 关键词 → 文案 → 主图 → A+ → 合规 → 复查 → 广告架构 → 周报 → 诊断 |
  249. | **独立站流量** | 5 | SEO 全链路诊断(NEW v3.3)→ SEO全链路规划 → SEM广告 → **转化率优化 CRO(UPGRADED v3.7,多 Agent 并发实站检测:第零步 5 子代理并发侦察 + 6 模块 + 技术追踪健康层 + 文案改写/异议表 + 速赢双桶,Claude Code Workflow 编排)** → SERP 内容拆解(NEW v3.6,竞品文章结构 + 关键词 + 反链 + GEO 一起拆) |
  250. | **财务与资金(NEW v3.8)** | 8 | 落地成本与单位经济(CM1/CM2/CM3) → 收款·结汇·FX 对冲 → 税务合规(Nexus/VAT/IOSS/EPR,含 EU €3 关税与 ~€2 处理费之分) → 13 周现金流预测 → 定价·毛利护栏 → 多渠道对账记账 → 跨境架构与利润回流 → 融资真实成本与风控 |
  251. | **社媒与内容** | 3 | TikTok增长 → YouTube运营 → 内容日历 |
  252. | **VOC 评论分析** | 3 | **Reddit VOC(NEW v3.5,购买前用户洞察 / 4 维度找社区 / 6 类帖子分类 / 黑话词典 / 矩阵定位)** → Trustpilot 快速扫描 → Trustpilot 深度分析(爬虫+情感+LDA+AI 归纳) |
  253. | **红人与用户** | 2 | 红人营销 → 用户生命周期 |
  254. | **GTM 执行** | 1 | 新品上市规划 |
  255. | **线下渠道** | 1 | 美国线下零售 |
  256. | **联盟与合作伙伴(NEW v3.13)** | 2 | **联盟可推性审计**(联盟客视角,`dsite-conversion-ux` CRO 的镜像——审"联盟客为什么不推你":ROI 账本 + EPC + 三层套利 + 六维评分 + 沉默拒绝红灯)→ **联盟运营流水线(AI)**(数据库→6 类生态找候选→100 分评分→10 来源采集→AI 个性化建联→素材库激活→4 层 KPI→30 天闭环,多 Agent 并发) |
  257. | **渠道与市场进入(NEW v3.13)** | 2 | **欧洲渠道进入战略**(美国主体进欧盟:美/欧市场逻辑 · 定位象限 · SSPV 用户价值 · RCS 区域作战 · 渠道赋能 · 组织三阶段 · 增长飞轮,5 区并发)→ **价格体系与渠道冲突护栏**(DTC+Amazon+分销:跨渠道真实价诊断 · 统一价×促销同步×区域保护三层 · T-60 促销 SOP · 含 MAP/反垄断边界) |
  258. | **海外开发与媒体公关(NEW v3.2 + v3.4)** | 3 | Google→WhatsApp 反查开发 → Google→LinkedIn 反查开发 → **媒体公关发现(NEW v3.4,Muckrack-anchored journalist DB pipeline,5 脚本 + Cloudflare-aware 4 后端 fetcher + 多机分片)** |
  259. ### 核心特色
  260. - **58 技能 × 13 链路 + 7 独立工具** — 从战略到执行到财务资金到联盟营销到欧洲渠道进入到海外开发到媒体公关到购买前 Reddit VOC 全覆盖
  261. - **联盟与渠道体系(源自 2026 行业分享)** — 从联盟客的经济账反推的 2 技能联盟链(`affiliate-readiness-audit` 是 CRO 的镜像——审"联盟客为什么不推你";`affiliate-program-ops` 跑 AI 招募→评分→建联→激活闭环),外加美国主体的欧洲渠道进入战略(SSPV / RCS / 增长飞轮)与多渠道价格冲突护栏。只抽方法论骨架,每个技能在"参考方法论索引"注明来源分享
  262. - **财务链 YMYL 纪律** — 8 个财务技能均带"规划辅助、非专业税务/法律/会计意见、需找 CPA 核实"免责,2026 法规打时间戳,估算标 ⚠️(不编造数字)
  263. - **数据验证层** — 每个技能内置强制验证,推测数据标 ⚠️
  264. - **图表可视化** — 21 个技能自动生成图表(雷达/柱状/瀑布/散点/漏斗等),调用 AntV API
  265. - **Semrush 集成** — 品牌战略技能自动扫描本地 Semrush 数据
  266. - **VOC 用户洞察** — 提及量×满意度二维分析
  267. - **GTM 飞轮** — 市场→产品→营销→运营四维评估
  268. - **AI 搜索适配** — Amazon Rufus / COSMO / GEO 优化
  269. - **多 Agent 并发(Claude Code 原生)** — `dsite-conversion-ux` 等技能用 `Workflow` 工具编排并发侦察+分析子代理(`StructuredOutput` schema),后台任务运行 + 浏览器类 MCP(Claude in Chrome / Preview)做实站检测——把活儿 fan out,只留结论
  270. - **合规抓取栈(2026 实测)** — 各 skill 共享的免费优先、美国合规取页流水线:`api-pacer`(限速 + 退避)→ `fetchlib`(waterfall:`curl_cffi` → Jina Reader → 浏览器 → 付费)→ `browser-fetch`(浏览器渲染 L3)。默认守 robots + 限速,不破壁 / 不换 IP / 不解 CAPTCHA / 不碰 PII。基准数据、分层机制与完整合规红线见各工具 `SKILL.md`
  271. - **有 lint 兜底,不只是写完** — 每个技能都带 `name` + `description` frontmatter(技能触发面),并有 `Skill lint` CI 门禁拦住本仓踩过的四类回归:frontmatter 缺失/名不符实、同一技能存在于两个路径(副本会静默分叉)、相对链接失效、以及任何违反抓取红线的写法。本地跑:`python3 scripts/lint_skills.py`
  272. - **多平台兼容** — Claude Code / Antigravity / OpenClaw / 任何 AI IDE
  273. ### 安装方式
  274. ```bash
  275. # Claude Code 一键安装
  276. git clone https://github.com/noique/cross-border-ecommerce-skills.git
  277. # 单文件技能 → ~/.claude/commands/
  278. cp cross-border-ecommerce-skills/brand-strategy/*.md ~/.claude/commands/
  279. cp cross-border-ecommerce-skills/amazon/*.md ~/.claude/commands/
  280. cp cross-border-ecommerce-skills/finance/*.md ~/.claude/commands/
  281. # 多文件技能包 → ~/.claude/skills/(每个技能一个目录)
  282. cp -r cross-border-ecommerce-skills/outbound-prospecting/google-whatsapp-prospecting ~/.claude/skills/
  283. cp -r cross-border-ecommerce-skills/outbound-prospecting/linkedin-prospecting ~/.claude/skills/
  284. cp -r cross-border-ecommerce-skills/outbound-prospecting/media-press-discovery ~/.claude/skills/
  285. cp -r cross-border-ecommerce-skills/voc-tools/reddit-voc ~/.claude/skills/
  286. cp -r cross-border-ecommerce-skills/brand-strategy/serp-content-teardown ~/.claude/skills/
  287. cp -r cross-border-ecommerce-skills/tools/backlink-kol-extractor ~/.claude/skills/
  288. ```
  289. ### 模型要求
  290. **先看能力门槛,再看型号。** 这些 skill 对模型的真实要求是三条——型号表每几个月就会过期,能力门槛不会:
  291. | 能力 | 为什么这些 skill 需要它 |
  292. |------|----------------------|
  293. | **长上下文里的指令遵循** | 单个 skill 有 10-50KB,模型要在读完整份规格后仍然照着结构走 |
  294. | **多步验证的执行力** | 本仓大量依赖「先算字节数 / 先查来源 / 缺了就标 ❌未获取」这类自检步骤。模型如果倾向于跳过验证直接给结论,诚信护栏就是摆设 |
  295. | **如实短交而非补齐** | 证据不足时要能写「数据不足,不下结论」,而不是编一个像样的数字把表格填满 |
  296. > 🔴 **第二条和第三条是本仓的分水岭。** 结构照着走很容易,很多中小模型都能生成看起来完整的报告——难的是**该空着的时候空着**。选型时请用这个测:给它一份缺关键数据的输入,看它是标注缺口,还是编一个数字。
  297. ### 🔴 「skill 跑不通」——先排查运行环境,再怀疑 skill
  298. **维护者实测口径(非对照评测):** 这些 skill 在**原版 Claude Code + Anthropic 官方 API/订阅**下表现最好。收到的「跑不通」反馈,绝大多数最后定位到的是**运行环境**而不是 skill 文件本身——要么 Claude Code 接的是第三方中转/转售订阅,要么换了别的 harness(Codex 一类的 agent CLI)在读这个文件。
  299. 为什么这里比普通 prompt 更吃运行环境:
  300. | skill 依赖什么 | 换掉运行环境后常见的断点 |
  301. |---|---|
  302. | harness **真的加载 `SKILL.md` 并认 frontmatter** | `SKILL.md` + frontmatter 是 Claude Code 的约定。别的 harness 可能只当普通上下文、甚至根本不加载——skill **静默地压根没生效** |
  303. | **完整不打折的长上下文**(单个 skill 10-50KB,还要加你的数据) | 中转普遍会截断、压缩或重新分块。而验证规则是**散布在全文**的,尾部一丢,诚信闸就跟着丢了 |
  304. | **真的是那个模型在接请求** | 部分转售会把「Claude」流量路由到别的或量化过的模型且不告知。你会拿到一份**长得像** skill 输出、但完全没有自检行为的东西 |
  305. | **多步自检活过 system prompt** | 会改写或前置自己 system prompt 的 harness,可能直接盖掉 skill 的验证指令 |
  306. **报障前请按这个顺序自查:**
  307. 1. **到底是谁在接你的请求?** 确认运行环境,以及请求真的打到了你以为的那个模型上——中间没有中转。
  308. 2. **skill 到底加载了没?** 让 agent 复述这个 skill 要求输出哪几节。复述不出来 = 文件压根没生效,这是**加载问题不是 skill 问题**。
  309. 3. **跑一次留白测试。** 喂一份缺关键数字的输入。正确行为是标出缺口(`❌未获取` / 「数据不足」)。**如果它编了一个数字,说明诚信脚手架没在跑**——不管它自称是什么模型。
  310. 三条都过了还不对,那才是真 bug,欢迎带上对话记录提 issue。
  311. > 这是单个维护者在自己能接触到的环境里的实测,不是对所有服务商的评测。第三方中转差异很大,有些可能没问题。要点只有一个:**先把运行环境排除掉**,因为「跑不通」的报障大多出在这儿。
  312. **参考型号(2026-08 核实,会过期)**
  313. | 层级 | 效果 | 当时的代表型号 |
  314. |------|------|--------------|
  315. | 推荐 | 完整执行,验证步骤生效 | Claude Opus 5 / Sonnet 5(及 Fable 5)、GPT-5.6 Sol / GPT-5.5 家族、Gemini 3.1 Pro |
  316. | 可用 | 结构完整,可能跳过验证 | DeepSeek V4、Qwen 3.5、GLM-5.2、Llama 4、Claude Haiku 4.5 |
  317. | 不建议 | 章节缺失,检查失效 | 小参数量模型(经验上 30B 以下) |
  318. > ⚠️ **这张表按定义会过期**——上一版停留在 2026-04 就已经落后两代。**别照抄型号,用上面的能力门槛去测你手上的模型。**各家型号请查官方文档:[Anthropic](https://platform.claude.com/docs/en/about-claude/models/overview) · [OpenAI](https://platform.openai.com/docs/models) · [Google](https://ai.google.dev/gemini-api/docs/models)。
  319. > Claude 一栏来自 Anthropic 官方文档;其余为 2026-08 公开资料整理,各家发布节奏不同,以官方为准。
  320. ---
  321. ## Changelog
  322. ### v3.17 (2026-08-01) — three new skills: event marketing, crowdfunding, measurement
  323. Three gaps closed, each found by auditing the library against outside industry material rather than by brainstorming. The recurring lesson: **in all three, the most valuable part was not the framework — it was discovering that the source material's core premise had expired.** Every fact below was verified against primary sources at build time; none was taken on the source's word.
  324. - **New `brand-event-marketing`** — moment-driven marketing: the four event types by the question each answers (brand = who you are / product = what category you own / calendar = who you stand with / trend = where you're headed), a 7-step calendar-moment SOP and a 6-step trend-jacking SOP (four-plane trend read, competitor-axis reset, three value anchors, pyramid content matrix), plus a daily market-radar checklist. **What the source lacked and this adds: the ambush-marketing legal gate.** Newsjacking a big event is a legal act in the US — Olympic marks sit under the Ted Stevens Act with **no consumer-confusion requirement** (the USOPC has pursued "Olympian", "Team USA", even "Going for Gold"); FIFA's 2026 protection rests on the Lanham Act plus venue contracts and municipal clean zones rather than special legislation; and NFL enforcement is why every brand says "The Big Game". No rights, no reference — full stop. Also carries the practitioner's own measurement-honesty rule (PR counts page views not the outlet's monthly visits; creators count plays/likes/shares/comments not follower counts) and a no-hardcoded-event-dates freshness rule. Framework credited to its named speaker in the 参考方法论索引; **the source's own self-reported campaign results were deliberately excluded** — vendor self-reporting does not belong in a skill.
  325. - **New `crowdfunding-launch`** — reward-based launch on Kickstarter / Indiegogo as four jobs at once (production capital, demand validation, launch awareness, distribution path), with a four-phase SOP and the post-campaign DTC flywheel. **Opens with a delivery gate, because a reward campaign is an FTC-enforceable promise**: the Chevalier case (the FTC's first Kickstarter action — $122k raised on a $35k goal, settled with a $111,793.71 judgment) and the iBackPack case ($800k+ across four campaigns on both platforms, nothing shipped) are in the file as the reason the rule is *deliver or refund*. 🔴 **The stale premise caught here: Indiegogo retired Flexible Funding for new campaigns in October 2025** — both platforms are now all-or-nothing, so every "set a low goal and take the money via flexible" playbook (and every pre-2025 case screenshot showing a Flexible Goal) is teaching a route that no longer exists. Verified fee stack: Kickstarter 5% + 3% + $0.20 (small pledges 5% + $0.05, nothing at all if the goal is missed); Indiegogo 5% + ~3% + $0.30, InDemand now **Late Pledge** (5% native / 8% non-native). Includes a suitability gate that will tell a drop-ship or trading team its product is wrong for crowdfunding — **"don't do this" is a designed output.**
  326. - **New `attribution-measurement`** — the measurement stack the library was missing: attribution, incrementality and MMM answer three *different* questions and get calibrated against each other rather than chosen between. Covers why summing independently-reported platform conversions always overcounts, geo-test design that starts from the minimum detectable effect that would actually change a budget decision (an under-powered test is worse than no test), open-source MMM selection between **Google Meridian** (Bayesian, Apache-2.0, now open to everyone, Scenario Planner added February 2026 for no-code budget modelling) and **Meta Robyn** (frequentist/ML, MIT, still maintained), and Bayesian calibration of MMM priors with incrementality results. 🔴 **Two stale premises caught: the cookiepocalypse did not happen** — Google reversed third-party-cookie deprecation in July 2024 and confirmed in April 2025 that Chrome would neither run the choice prompt nor deprecate, so any strategy whose立论 is "cookies are going away, therefore X" needs rewriting from the premise up (while *not* over-correcting: click-level tracking was never complete, which is the actual reason to run incrementality and MMM); **and the rule-based attribution models are retiring on a live timeline** — GA4 dropped first-click / linear / time-decay / position-based in November 2023, and Google Ads retired the same four in 2026 (unselectable for new conversion actions from mid-July, force-migrated to data-driven attribution by September), which means accounts still sitting on them should choose their migration rather than be migrated.
  327. - **Validated against real data, not just linted.** Each skill was dry-run on real cases, and each run found a defect that was then fixed: `brand-event-marketing` had no operational way to grade an event's 势能 (now a table of observable signals — search-trend shape in the *target country*, whether the platform runs an official window, discussion breadth — with "does my category actually connect to this moment" as a **veto, not a bonus**); `crowdfunding-launch` had no way to size a pre-launch email list (now a back-solve from goal ÷ AOV ÷ list-conversion, and 🔴 the repo deliberately ships **no default conversion rate** — that number varies too much by category and list source for a borrowed one to be anything but precise and wrong). `attribution-measurement` was run against a real multi-year DTC dataset (~30k orders, six years, GA4 + GSC + keyword data all connected) and **correctly refused to produce a channel-ROI ranking**: no ad-spend data at all meant two of the three legs could not run, order-source coverage sat at 16-30% every year, and first-touch matched last-touch on all but 6 of 3,964 orders — so the output was "the data cannot answer which channel works" plus the gap list, which is exactly what the honest-shortfall rule exists to produce.
  328. - Total: **58 skills across 13 chains** (+3); standalone tools: 7.
  329. ### v3.16 (2026-08-01) — the honesty-scaffolding sweep: reproducible scoring, honest quotas, evidence gates
  330. Closes the two design questions parked in v3.15, then follows the thread: a gap found in one skill turned out to be a *class* of gap, so all 62 skills were swept for it. The pattern throughout — the repo's honesty scaffolding existed in its vocabulary but was missing at specific spots, and **the spots it was missing were often the highest-consequence ones**. No skills added or removed.
  331. - **Output quotas are now targets, not pass marks ([#16](https://github.com/noique/cross-border-ecommerce-skills/issues/16)).** `brand-market-scan`, `brand-track-hypothesis` and `social-content-calendar` demanded *"≥8 rows + ≥3 user quotes per layer"*, *"≥10 features"*, *"exactly 5 strategic clues, each with ≥3 lines of numeric support"* — and when the data isn't there, a quota rewards filling the shape, which fights the **same file's** data-acquisition ledger and 推测值-labeling rules. Every quota is **kept**, but reframed with an honest shortfall path: state what's missing, why, and what it costs the conclusion; log it in the existing ledger; and — the load-bearing sentence — **an honest shortfall counts as completing the step**. Also separates 必出的章节 from 必出的结论: always emit the section, never force a conclusion the evidence won't carry.
  332. - **New [`docs/scoring-conventions.md`](docs/scoring-conventions.md) — the mechanical half of reproducible scoring ([#15](https://github.com/noique/cross-border-ecommerce-skills/issues/15)).** The repo runs four different scales (/100, 1-5 stars, six dims /30, 100-pt bands); differing scales are fine, but the same input should produce the same ranking twice. Scale-agnostic spec covering anchor-pair normalization with clamping (`log` for heavy-tailed inputs like BSR, reverse anchors for lower-is-better), missing values, tie-breaking, showing the arithmetic per dimension, and not manufacturing precision the inputs don't have. Wired into all four weighted-scoring skills (`amazon-product-selection`, `amazon-product-shortlist`, `affiliate-readiness-audit`, `affiliate-program-ops`).
  333. - The single most important rule: **a missing dimension is dropped and the remaining weights renormalized** — never zero-filled, never averaged — and the output must carry `本分基于 N/M 维`. A 90 from 3 dimensions and a 90 from 5 mean different things, and hiding the count dresses "incomplete data" up as "scores well". Above **40% missing weight**, no total is produced at all.
  334. - **Deliberately not done: universal anchor values.** *"月搜索 >10,000 = 高分"* is not the same claim in pet supplies as in consumer electronics. Existing thresholds are preserved verbatim as calibrate-me defaults that the skill must **print**; inventing universal ones would replace honest vagueness with false precision — the same disease #16 treats, pointed the other way.
  335. - **`amazon-listing-copywriter` — title and Item Highlights now ship as 3 candidate versions ([#21](https://github.com/noique/cross-border-ecommerce-skills/pull/21)).** Three strategy-distinct candidates each (volume-first / long-tail-first / scenario-first) with per-version character counts, closing with one recommended version whose rationale must state what traffic it prioritizes, what it gives up, and the condition under which to switch — a bare *"use version A"* is defined as not completing the step. **All three versions are character-counted and compliance-checked, not only the recommended one:** operators pick a non-recommended version routinely, and that previously meant shipping a string nothing had validated against the ≤75 limit, the same-word ≤2 rule, or the banned-character set.
  336. - **The Item Highlights output section was missing entirely.** The field is named in the skill's frontmatter and four times in its rules — *"migrate long-tail and scenario words into Item Highlights"* — but the report template went straight from title to bullet points. The skill had been telling the model to use a field it never asked it to write, ever since the **2026-07-27** policy created it. Section added and marked non-empty-able, since it is where everything the 75-char title had to drop now lands.
  337. - Both new quotas follow the #16 convention rather than re-opening it: **3 is a target.** The fabrication risk here is not padded table rows but **invented product facts** — a third title needs a third *real* angle, and material / size / certification / audience are precisely what a model reaches for to manufacture one, after which those inventions ship on a live listing. Short-delivering with the reason stated (`实际 2/3 版,原因:无第二人群词`) completes the step, and a `多版本真实性` row was added to the compliance self-check table.
  338. - **Lint gained `/docs/` and a wider negation vocabulary.** `docs/` joins the support-file exemption (it holds conventions, not skills), and the deception check's negation list grew (`严禁` `不得` `避免` `不披露` `等于把`) after it false-positived on lines warning **against** disguising data gaps. Re-tested: genuine `伪装成订单更新` phrasing is still caught.
  339. - **`amazon-ip-risk-assessment` had no rule against inventing a patent number.** Found by sweeping the other 13 Amazon skills for the same defect class. It is the one skill in the chain that emits **legally consequential identifiers** — patent numbers, trademark registration numbers, holders, legal status — that a seller acts on with tooling money; its 数据验证(必做)held four items, all about *telling things apart correctly* (Assignee vs Security Interest vs Licensee, ® vs ™, Active vs Expired), and none about whether the record exists at all. Meanwhile `amazon-keyword-research` forbids inventing a **competitor keyword** and `brand-market-scan` forbids filling in an ASIN from memory. The lowest-stakes outputs in the repo were guarded and the highest-stakes one was not. Added: a top-of-file 🔴 evidence rule, a **search-execution record** (platforms reached, exact queries, date, success flag) that precedes the result tables, ✅/⚠️/❌ retrieval status + source + date columns on both the patent and trademark tables, "no hits" stated as an explicitly valid result, and — the load-bearing gate — **if the search did not execute, the tables are marked ❌未获取 and the overall risk grade is withheld** rather than guessed from category intuition. A fabricated `US D123,456 — Active — held by X` reads exactly like a real one, and the seller has no way to tell.
  340. - **`amazon-ad-diagnosis` flagged compliant bullets as too long.** Its listing-diagnosis table carried `每条 ≤200 字符` as a *健康标准* with 问题信号 *"超长 → 精简"* — an unsourced number that contradicts the official 2024-08-15 policy of **10–255 characters**, which `amazon-compliance-review`, `amazon-listing-copywriter`, `amazon-keyword-research`, `amazon-market-research` and `amazon-pre-launch-review` all carry correctly. The diagnosis would have told sellers to cut copy that was never over the limit. Corrected, with the ~1000-character total kept as a labeled soft budget that is explicitly **not** a diagnostic finding — the same de-mythologizing v3.14 applied everywhere else in the chain.
  341. - Swept and clean across all 14 Amazon skills: section numbering sequential, every `/amazon-*` cross-reference resolves, the 2026-07-27 dual-field policy reached both gates (`compliance-review` and `pre-launch-review` do check Item Highlights — the copywriter gap above was isolated, not systemic), 数据验证(必做)present 14/14, #20's scoring conventions genuinely wired into both scoring skills (anchors printed, `本分基于 N/5 维`, >40% circuit breaker), no fabricated ranking-weight percentages, and image specs consistent at ≥1600×1600.
  342. - **`trustpilot-voc-quick` had no "couldn't fetch" path — and a worked numeric example to copy from.** Its output template specified rating, review count, star distribution, high-frequency words and a trend call, with nothing tying any of them to the fetch actually succeeding; the fallback section listed what to *try* (Google cache, ask the user to paste) but never what **not** to do when all of it fails. Trustpilot throttles hard, so failure is the common path, not the edge case. Worse, the file shipped a fully-worked real example (`4.5/5, 269 reviews, 216/21/4/2/26`) — a model that couldn't fetch had a plausible numeric template sitting in its own prompt. Added a 🔴 data-acquisition rule binding every figure to the fetch, an explicit ❌未获取 output block, partial-retrieval handling (don't back-infer a distribution from an overall rating), failed brands kept as ❌ rows in comparison tables instead of filled in, and the example **rewritten to placeholders** with a warning not to transplant any number from it. The sharp edge: this skill **feeds `brand-market-scan` 第零步**, the very report #16 hardened with *"严禁用记忆或推断补齐…评论原文"* — the consumer was guarded and its producer was not.
  343. - **`media-press-discovery` handed over pattern-guessed emails for real, named journalists with no send gate.** `guess_emails.py` guesses `firstname.lastname@outlet.com` from a name and a domain; the schema even carried an `email_verified` column — but the quick-start ran the guesser **without** the `--verify` flag the script already supports, and nothing anywhere said *don't send to `unverified`*. A wrong guess bounces (degrading your sending domain), reaches **a different real person** at that outlet, or hits a spam trap. Sibling skills already knew this — `linkedin-prospecting` says pattern-guess → verify with NeverBounce/ZeroBounce, and `contact-extractor` ships confidence tiering plus `--verify`. Fixed: `--verify` promoted into both quick-start flows with its real ~60% SMTP-probe accuracy stated, `email_verified` documented as a **hard gate** rather than a note (`smtp_fail` = unproven, not disproven → manual queue, don't drop the journalist), a ban on reconstructing any journalist name / byline / URL / date from memory, and the CAN-SPAM / GDPR identify-yourself line the repo already enforces elsewhere.
  344. - **`reddit-voc`'s Top 5 quotas never got the #16 treatment.** *"核心痛点 Top 5(带原话引用)"* and *"竞品翻车点 Top 5"* are hard quotas in a skill whose entire value is verbatim user language — and Reddit now rate-limits and 403s routinely, so shortfall is normal. The skill's existing *"永远抄用户原话,别自己改写"* guards against **paraphrase**, not against **invention**, and quoting presupposes having something to quote. Added the standard shortfall path (3 real pain points → write 3 and label `实际 3/5` + reason), a ban on fabricating quotes, usernames, permalinks or upvote counts, an outright ❌未获取 report when scraping fails, and the 必出的章节 / 必出的结论 split. Also stopped the ≥2-community cross-check from becoming its own quota: single-community insights get labeled, not padded out with a lookalike.
  345. - Swept and clean across the other 45: `finance/` (8) uses a **different but real** convention — source table + confidence + timestamp + "须核实一手源" + disclaimer, with `finance-tax-nexus-vat-diagnostic` citing Council Reg (EU) 2026/382, HMRC and Wayfair and flagging its own 2026 moving targets · `trustpilot-voc-deep` carries a sample-size + credibility table and runs a real local scraper · `linkedin-prospecting` and `contact-extractor` already gate on verification · `serp-content-teardown` is deterministic by design (no LLM) · `tools/` (7) are deterministic scripts · `report-pdf-export` and `brand-chart-visualize` emit no facts. Structure clean repo-wide: section numbering, cross-references and count claims all check out.
  346. - Total: **55 skills across 13 chains** (unchanged); standalone tools: 7.
  347. ### v3.15 (2026-07-26) — repo hygiene: dedupe, red-line fix, frontmatter, CI
  348. No skills added or removed; this release fixes structural debt found in an external audit, with each claim verified against the tree first.
  349. - **Deleted 14 stale duplicate skills (−2,704 lines).** Every Amazon skill existed *twice* — `amazon/<name>.md` **and** `amazon/<category>/<name>.md` — and **all 14 pairs had diverged**. The root copies are canonical (README links only to them, and they carry two sections the subdirectory copies had lost); the subdirectory copies were referenced nowhere. Left in place, an agent grepping the repo could hit the older, capability-poorer version.
  350. - **Closed a cross-file compliance conflict.** `google-whatsapp-prospecting` advised rotating IPs for high-volume search and rotating numbers past a ban — contradicting the repo-wide scraping red line in `tools/fetchlib` / `tools/browser-fetch` (*no access-barrier defeat, no IP rotation, no CAPTCHA solving*) **and** the skill's own rule to move to the WhatsApp Business API above 50 msgs/day. Both now point at the sanctioned path, with the instruction to cut the query set rather than the compliance.
  351. - **Frontmatter on all 53 remaining skills.** `name` + `description` now present repo-wide, matching the convention the multi-file packages already used. Descriptions were authored from each file's actual contents — what it produces, when to reach for it, bilingual EN/中文 triggers, sibling cross-refs — with explicit disambiguation between near neighbours (`amazon-ad-architecture` vs `-diagnosis` vs `weekly-ad-review`; `trustpilot-voc-quick` vs `-deep`; `dsite-seo-diagnostic` vs `-playbook`). Support files (`references/` `templates/` `scripts/` `examples/`) are deliberately exempt — they are not skills.
  352. - **New `Skill lint` CI gate** (`scripts/lint_skills.py`, stdlib-only) blocking all four regressions above: frontmatter presence + `name`-matches-filename, duplicate skill names across paths, dead relative `.md` links, and scraping-red-line violations (negation-aware, so the red-line statements themselves pass). Each check was negative-tested against a seeded fault.
  353. - **Removed a disguised-consent instruction and two folklore ban thresholds.** `google-whatsapp-prospecting`'s reference doc told readers to send a *"transactional-looking"* opt-in request to obtain consent — deceptive on its own terms, what Meta rejects templates for, and an FTC Act §5 exposure for a US operator; and it stated `3+ blocks → warning / 5+ block + 2+ report → 24h ban` as fact, which Meta does not publish. Both rewritten (identify yourself and ask plainly; enforcement described qualitatively). The lint gained two checks — **deception** and **unpublished-threshold folklore** — because none of the original four would have caught either.
  354. - **Skill count corrected 54 → 55.** No skill was added: `report-pdf-export` had always existed and is chained by **37 other skills**, but it was never listed in the skill map. It now appears in the Brand Strategy chain.
  355. - **Open design questions parked as issues** rather than guessed at: [#15](https://github.com/noique/cross-border-ecommerce-skills/issues/15) making the weighted scoring models reproducible (normalization / missing values / ties) and [#16](https://github.com/noique/cross-border-ecommerce-skills/issues/16) the tension between output quotas and honest "insufficient evidence". Input welcome on both.
  356. - Total: **55 skills across 13 chains** (count corrected, none added); standalone tools: 7.
  357. ### v3.14 (2026-07-12)
  358. - **Amazon Operations Chain (14 skills) — 2026 algorithm & policy refresh.** Every fact was re-verified against first-party sources (Seller Central announcements, Amazon Ads *what's new*, the COSMO SIGMOD 2024 paper, Amazon Q4'25 / Q1'26 earnings) and corrected. No skills added; the flows are unchanged. Highlights:
  359. - **Title char limit rewritten** — hard-coded `200 / 125 / 80` replaced with the **2026-07-27** policy: **≤75 chars** for non-media categories + the new searchable **Item Highlights** field (125 chars). Over-limit titles get AI-rewritten (brand owners get a 14-day Review-Listing-Changes window, others don't); the 2025-01 special-char ban + no-word-repeat rules are kept as still-stacking.
  360. - **Rufus → "Alexa for Shopping"** — renamed across the chain (Rufus brand retired **2026-05-13**, folded into the main search bar; recommendation engine carried over). The mis-stated "300M active users / $120亿" is corrected to Amazon's actual cumulative-users / self-attributed annualized-incremental wording, with a "no seller-side AI attribution → don't cite % lift claims" honesty guardrail.
  361. - **Removed a live TOS-violating tactic** — the "competitor-brand back-end Search Terms" instruction (violates G23501, risks ASIN suppression) is now a prohibited-items check. (SP ad targeting of competitor terms stays — that's compliant.)
  362. - **De-mythologized unverifiable claims** — "bullets: only first 1000 bytes indexed" (no official basis; Amalytix self-test, and in *characters* not bytes) and COSMO "~10% of US search traffic" (a 2024 A/B-test bucket, not coverage) downgraded to labeled third-party / snapshot facts; fabricated ranking-weight percentages ("title first-80-chars = 60% weight") removed.
  363. - **Premium A+** — kept the real (unchanged) eligibility per Amazon's 2026-05 forum-mod confirmation and added the real new **Content Quality Analysis** beta; explicitly flags the "$5M threshold removed / open to all / A+ Quality Score" rumors as false.
  364. - **New 2026 realities added** — SP/SB **Prompts ads** (auto-enrolled, CPC-billed since 2026-03-25), free self-serve **AMC** (since 2025-09, + a 2026-06→12 free-signals window), **FBA** commingling end + mandatory FNSKU (2026-03-31) & paid-prep/labeling sunset (2026-01-01), **variant-review split** (2026-02-12, which shifts every "review-count" threshold), agentic-shopping / AI-agent-readiness checks, a corrected image policy (G1881, no AI-specific ban) and an external-AI / robots.txt reality section.
  365. - **Housekeeping** — corrected tool references (TESS → USPTO Trademark Search; APEX scope), runtime-verify guards for referral / FBA fees, graceful fallback for the AntV chart endpoint, and removed internal build-file names from the design-inspiration notes.
  366. - Total: **54 skills across 13 chains** (unchanged); standalone tools: 7.
  367. ### v3.13 (2026-07-04)
  368. - **New chain — Affiliate & Partnership (2 skills)**, built from three 2026 industry decks (each skill credits its source in a `参考方法论索引` table, per repo convention — framework skeletons only, no slide copy):
  369. - **`affiliate-readiness-audit`** — the **mirror of `dsite-conversion-ux` (CRO)**: audits a product/Listing from the affiliate's wallet POV ("why affiliates won't promote you"). Affiliate ROI ledger + EPC + 3-layer arbitrage, 6-dim recruitability scorecard with score bands, admission buckets, 6 silent-rejection red flags, traffic-catch self-check + 30-day fix roadmap.
  370. - **`affiliate-program-ops`** — AI-automated affiliate operations pipeline: database → find candidates across 6 affiliate ecosystems → 100-pt AI scoring → standardized contact collection (10 sources) → AI personalized outreach (5-element email) → Partner Resource Hub activation → 4-layer KPI + weekly report → 30-day minimum loop. Multi-agent fan-out per ecosystem; reuses `outbound-prospecting`. Complements `influencer-marketing` (content/relationship lens) without overlap.
  371. - **New chain — Channel & Market Entry (2 skills)**:
  372. - **`eu-channel-market-entry`** — channel/distributor-driven Europe entry for **US-entity brands**: US-vs-EU market logic, positioning quadrant, **SSPV** user-value model, **RCS** regional-combat model across the 5 EU regions, channel enablement, overseas-org 3 stages, the 8-step growth flywheel. Org/tax hand off to `finance-*`. Reframed China-seller → US-entity.
  373. - **`price-system-conflict-guard`** — multi-channel price-system & channel-conflict guard (DTC + Amazon + distribution): cross-channel real-price diagnosis, 3-layer mechanism (unified price × promo-sync × regional protection), DTC-vs-channel boundary, T-60 promo SOP, US antitrust (MAP vs RPM) boundary.
  374. - All four are Claude Code multi-agent-ready (`Workflow` fan-out + `StructuredOutput` schemas), US-jurisdiction framing, brand-neutral examples.
  375. - Total: **54 skills across 13 chains**; standalone tools: 7 (unchanged).
  376. ### v3.12 (2026-06-29)
  377. - **New `tools/browser-fetch/`** — an optional shared **browser-render** backend for `fetchlib`'s **L3**, promoting the "real browser + optional proxy" capability (the kind in `tools/trustpilot`) into one reusable module (pluggable engine, **default Selenium**; `register_engine()` for nodriver / camoufox / scrapling). Drop-in: `fetchlib.register_backend("browser", browser_fetch.as_fetchlib_backend(engine="selenium"))`.
  378. - **Benchmark-driven, honest scope**: real testing (Selenium + nodriver, from a datacenter IP) showed a browser clears **Trustpilot-class** sites `curl_cffi` can't render (Selenium got real content), but **no free tool — Selenium, nodriver, curl_cffi, Jina — beat Cloudflare Managed Challenge / DataDome (Muckrack, G2, cf-challenge) from a datacenter IP**. The bottleneck there is **IP reputation + Turnstile, not the browser library** → those need a residential IP (+ maybe Camoufox/Scrapling's Turnstile solver) or a paid unblocker. So Selenium is the proven default; other engines are opt-in "validate on a residential IP first."
  379. - Normalizes a detected challenge page (incl. the Chinese Cloudflare interstitial "请稍候") to `403` so `fetchlib` flags it; `selenium` is a lazy import; self-test is browser-free. Also hardened `fetchlib`'s block-detector with the Chinese + a few more challenge markers.
  380. - **Compliance (US)**: renders JS + optional proxy, but does NOT solve CAPTCHAs, defeat access barriers, use botnet proxies, or handle PII (caller's call under CFAA / hiQ / CCPA-CPRA). `tools/trustpilot`'s working Selenium is left untouched.
  381. - Total: 50 skills across 11 chains; **standalone tools: 7** (was 6).
  382. ### v3.11 (2026-06-29)
  383. - **`fetchlib` batch 2 + `serp-content-teardown` migration** — after a real benchmark of the free tiers against representative targets (Shopify `products.json`, Trustpilot, a Cloudflare JS-challenge, Muckrack, G2, from a datacenter IP):
  384. - **`serp-content-teardown/fetch_competitors.py` now uses `curl_cffi`** (real-browser TLS/JA3, free, local) with a **graceful fallback to plain `curl`** if it isn't installed — non-breaking, same `fetch_manifest.json` / outputs. The skill's "free + local, no paid APIs" red line is preserved (curl_cffi is a free local libcurl, not an API); no headless browser is added (it stays a deterministic offline analyzer).
  385. - **`fetchlib` gains a `ThompsonSelector`** (per-domain Beta-Bernoulli bandit, `Fetcher(learn=True, selector_path=…)`) that learns which tier actually succeeds per site and tries the best first — because the benchmark showed the "best backend" is **site- and IP-dependent, not fixed** (e.g. `curl_cffi` matched plain `curl` and 403'd on Trustpilot/Cloudflare/Muckrack/G2 from a datacenter IP, while free **Jina Reader** cleared Trustpilot; the hard JS-challenge sites need `nodriver` + a residential IP or a paid unblocker). Self-test covers the selector.
  386. - **Honest scope**: `nodriver` (L3) stays a documented `register_backend` plug-in — deferred until tested locally on a residential IP (it won't clear those sites from a datacenter IP either). `tools/trustpilot`'s working Selenium is left untouched per its owner.
  387. - No new skills/tools; counts unchanged (50 skills / 11 chains / 6 tools).
  388. ### v3.10 (2026-06-29)
  389. - **New `tools/fetchlib/`** — a compliant fetch **waterfall** for the scraping skills, built from the 2026 dual-source scraping-stack research (multi-agent web research + a Gemini Deep Research report). Escalates one tier only on a real block (Markov-style state machine): **L1 `curl_cffi`** (TLS/JA3 impersonation, free, no JS) → **L2 Jina Reader** (`r.jina.ai` JS→clean-markdown, free\*) → L3 `nodriver` (batch-2 `register_backend` plug-in) → L4 managed unblocker (paid, opt-in).
  390. - **Control layer**: `api-pacer` (header-adaptive pacing + full-jitter backoff) + **AIMD** (additive-increase / multiplicative-decrease per-domain rate — creep up, cut hard on block) + **circuit breaker** (cool down a target that keeps blocking) + per-fetch JSONL instrumentation.
  391. - **Grounded conclusions**: `curl_cffi` is the free TLS-impersonation workhorse; `cloudscraper` / `FlareSolverr` / `undetected-chromedriver` / `puppeteer-stealth` are dead/declining vs 2026 WAFs and are NOT used; "human-like" delay distributions (Gaussian etc.) are cargo-cult for read-only research — header-driven pacing + full-jitter backoff is what matters.
  392. - **Compliance-first / red line**: honors robots.txt; does NOT defeat access barriers, rotate IPs, forge fingerprints, solve CAPTCHAs, or handle PII (caller's duty); use only KYC/consent-audited proxies if any; legitimate rate-limit-respecting RESEARCH use only, NOT ToS-violating automation. Governing law is **US** (CFAA + state) with the hiQ / Meta-v-Bright-Data public-data safe harbor (public + logged-off + no-barrier-defeat + no-PII); GDPR / CCPA-CPRA apply only when collecting EU / California residents' personal data.
  393. - Stdlib-runnable (`curl_cffi` optional with graceful urllib fallback); **depends on `api-pacer`**. Adoption is opt-in for `serp-content-teardown` / `media-press-discovery` / `trustpilot` / `outbound-prospecting` / `reddit-voc` (their working scrapers unchanged). Batch 2 will add the `nodriver` backend + a Thompson-sampling backend selector.
  394. - Total: 50 skills across 11 chains; **standalone tools: 6** (was 5).
  395. ### v3.9 (2026-06-29)
  396. - **New `tools/api-pacer/`** — a shared, dependency-light **request pacer** (adaptive rate-limiting + AWS-style full-jitter backoff) for the scraping / API skills. Paces to the server's own `x-ratelimit-*` headers when present (else a configured RPS budget); full-jitter (uniform) backoff on 429/503/Retry-After; stdlib-only, `requests` optional.
  397. - **Why it exists** — reads the REAL rate-limit budget instead of guessing a delay from a distribution. A Gaussian/uniform "human-like" sleep is *not* what avoids rate limits/blocks (platforms don't fit-test your delay distribution); the winners are (a) obeying the response-header budget and (b) full-jitter backoff for retries.
  398. - **Adoption** — `reddit-voc` gets an integration note (`voc-tools/reddit-voc/references/rate-limiting.md`: PRAW + pacer, read-only research framing); `serp-content-teardown` / `media-press-discovery` / `trustpilot` / `outbound-prospecting` are documented as **opt-in** drop-ins (their working scrapers are left unchanged).
  399. - **Scope / red line** — legitimate rate-limit-respecting research use only; NOT for ToS-violating automation (vote manipulation, spam, sockpuppets, ban evasion). It does not defeat anti-bot, rotate IPs, or forge fingerprints.
  400. - Total: 50 skills across 11 chains; **standalone tools: 5** (was 4).
  401. ### v3.8 (2026-06-29)
  402. - **New `finance/` chain — 8 skills (Finance & Capital)** for China→US/EU DTC + Amazon sellers: `finance-landed-cost-unit-economics` (CM1/CM2/CM3 + break-even ROAS), `finance-fx-payout-optimizer` (收款/结汇/FX hedging + SAFE checklist), `finance-tax-nexus-vat-diagnostic` (registration-obligation map + EU €3 duty / IOSS / US nexus / EPR), `finance-cashflow-runway-forecaster` (13-week rolling forecast), `finance-pricing-margin-guard`, `finance-reconciliation-bookkeeping` (clearing-account-to-zero), `finance-entity-structure-advisor` (HK/SG/US LLC + repatriation, YMYL), `finance-capital-stack-advisor` (RBF/MCA true-APR + contract traps).
  403. - **Dual-source, cross-validated** — built from a multi-agent web-research pass + an independent deep-research report, then merged. Example correction surfaced by the merge: the EU low-value-parcel change is a **fixed €3 customs duty** (Council Reg (EU) 2026/382, applies 2026-07-01, interim to 2028) — DISTINCT from the not-yet-law ~€2 per-consignment handling fee (UCC reform, only provisionally agreed 2026-03-26).
  404. - **YMYL-first** — every finance skill carries an explicit "operator planning aid, NOT professional tax/legal/accounting/financial advice — verify with a licensed CPA before filing/binding decisions" disclaimer; all rates/thresholds/dates tagged point-in-time; estimates flagged ⚠️ hypotheses; no fabricated seller numbers.
  405. - **Complements `brand-budget-ops`** (forward budgeting) with the actuals / profitability / tax / cash / financing side; cross-links into Amazon ops + DTC chains.
  406. - Total: **50 skills** across **11 chains** (was 42 / 10). Single-file skills: 45 (was 37).
  407. ### v3.7 (2026-06-29)
  408. - **`brand-strategy/dsite-conversion-ux` upgraded** — the CRO skill is rebuilt as a **multi-agent, Claude Code-native live-site audit** (was a single-pass content audit):
  409. - **Multi-agent concurrency execution architecture** — a new section documents running the skill on Claude Code's `Workflow` tool / subagents: **Step 0** fans out 5 parallel recon agents (PDP / discovery / trust / checkout / competitor) with `StructuredOutput` schemas → `reconPool` → parallel **6-module analysis**; background tasks; browser-class MCP (Claude in Chrome / Preview) for what static `WebFetch` can't see (console / pixel firing / sticky / mobile). Concurrency speeds it up and removes blind spots without changing data truth.
  410. - **New Step 0 — live-site reconnaissance** — turns the skill from "wait for user-supplied data" into "actually go look first," pinning page-level facts with verbatim evidence before diagnosis.
  411. - **New §1.6 technical-health & tracking-integrity check** — console errors / GA4-Pixel firing / Core Web Vitals / 404 / mobile-sticky. Broken tracking silently invalidates all downstream A/B + funnel data, so it ranks as a foundation-layer, highest-priority finding (a layer most content-only CRO audits miss).
  412. - **New mandatory deliverables** — a **copy-rewrite table** (current → A/B), an **objection-handling table** (doubt → current handling → gap → fix), and a **quick-win vs high-impact dual-bucket** triage with wall-clock effort estimates.
  413. - **A/B stop-rule discipline** — every test now carries sample-size + ≥7-14 days + 95% significance + a stop rule.
  414. - **Honesty preserved** — keeps the data-credibility statement; lift figures stay ⚠️ hypotheses (no fabricated funnel numbers); adds explicit WebFetch tool-boundary disclosure.
  415. - Skill count unchanged at **42** (upgrade to an existing skill, not a new one).
  416. ### v3.6 (2026-05-26)
  417. - **New `brand-strategy/serp-content-teardown/`** multi-file skill (DTC Site & Traffic chain) — deterministic (no-LLM) SERP/content reverse-engineering from local Semrush xlsx + competitor HTML. 8 scripts (`parse_serp` → `fetch_competitors` → `analyze_structure` → `classify_archetypes` → `keyword_analysis` → `backlink_analysis` → `geo_analysis` → `onpage_analysis`) + `run_all` orchestrator + shared `_config` (YAML topic-clusters / JSON brand-names).
  418. - **Structure teardown**: parses Semrush `serp_urls` → ranked blog/info-article URL pool, fetches the top competitor articles (`curl` + browser UA, `html5lib` to survive Shopify void-tag body-nesting), computes per-article metrics (words, H1/H2/H3, lists, tables, JSON-LD `@type` set, author byline, dates, brand-mentions/1k, authority outlinks), classifies each into **8 article archetypes** (DEFINITION_QA / TUTORIAL_HOWTO / LISTICLE_TIPS / COMPARISON_VS / PILLAR_GUIDE / MYTH_DEBUNK / PRODUCT_MICROGUIDE / NEWS_EDITORIAL) + opening/closing patterns + cross-sample winning bands.
  419. - **SEO/GEO/keyword/backlink layers**: keyword distribution + core keywords + difficulty-cliff (from `broad-match`); backlink/authority thresholds (Page AS / Ref.Domains / Backlinks) + "weak-link winners"; AI-Overview (GEO) saturation per topic + AI-cited domains + schema readiness of cited vs non-cited; on-page SEO (title/meta/H1/canonical/internal-links/SERP-features).
  420. - **Output**: JSON artifacts + a per-topic content-strategy report (which archetype / word / H2 / schema / FAQ / opening-closing to use, which keywords to target, what authority is realistically needed, what GEO posture to take). Worked example under `examples/`: waterproof / stainless-steel jewelry niche (25 competitor articles).
  421. - **Honest scope**: covers the ~20-30% code-side of what wins; content quality + domain age + backlinks are the other ~70-80%. Backlink data is page-level Authority Score, not domain DR. AI-Overview citation capture is sparse. Red line: `curl`-only fetch, no paid APIs, no live AI-citation probing. Pairs with `backlink-kol-extractor` (links) and `structured-data-buildout` (implements the schema this skill measures).
  422. - Total: **42 skills** across 10 chains. Multi-file packages: 5 (was 4).
  423. ### v3.5 (2026-05-19)
  424. - **New `voc-tools/reddit-voc/`** multi-file skill — pre-purchase VOC mining from Reddit (complements post-purchase `trustpilot-voc-*`). Methodology:
  425. - **4-dimension community discovery** — category/brand subs (D1) + lifestyle/demographic subs (D2) + problem/help subs (D3) + values/ideology subs (D4). Single-dimension findings are not credible; cross-dimension validation required.
  426. - **6-class post taxonomy** with business-action mapping — Recommendation / Rant / Question / Comparison / Daily / Top-All-Time. Each class maps to a primary output (Listing copy / differentiation positioning / FAQ + IPQ / vs-matrix / content calendar / brand positioning) and a secondary output.
  427. - **Reddit slang dictionary** — BIFL / YMMV / AITA / DAE / TIL / PSA / etc., grouped by VOC signal type (values / emotion intensity / moral-judgement / product-evaluation / community-platform / category-specific). Reading slang wrong = misreading user emotion and values.
  428. - **3 listing+ad rewrite cases** — "7 pieces to clean" listing rewrite, "earbuds don't fall out" TikTok hook, "never scoop never clean" brand tagline. All sourced from real Reddit high-upvote threads, demonstrating *user-language > marketer-language*.
  429. - **2D positioning matrix** (functional importance × satisfaction) — find the bottom-right "wants but unmet" quadrant. Includes simplified 30-min version and full 2-3-day data-driven version. Compatible with `tools/trustpilot/` `topic_modeling.py` + `sentiment.py` for auto-labeling at scale.
  430. - 3 CSV templates: `community-map.csv` (8-15 subs across dimensions) / `post-analysis.csv` (30-80 post teardowns) / `insight-action-map.csv` (insight → action with P0/P1/P2 priority + owner + status).
  431. - Pairs with: `/trustpilot-voc-deep` (post-purchase), `/amazon-market-research` (post-purchase), `/brand-market-scan` (pre-strategy VOC input), `/amazon-listing-copywriter` (user-language input), `/tiktok-growth` (ad-hook input).
  432. - Total: **41 skills** across 10 chains. Multi-file packages: 4 (was 3).
  433. ### v3.4 (2026-05-06)
  434. - **New `outbound-prospecting/media-press-discovery/`** multi-file skill — Muckrack-anchored journalist DB pipeline. 5 scripts (`discover_journalists` / `find_articles` / `guess_emails` / `score_and_export` / `merge_partitions`) + shared `_fetcher.py` with 4 backends (`requests` / `remote-chrome` / `apify` / `html-dir`) for Cloudflare-protected pages. Multi-machine partition-merge workflow.
  435. - **New `tools/linktree-expander/`** — batch-enrich Linktree handles via `__NEXT_DATA__` JSON parsing. Handle-match scoring for `personal_site` + `NON_PERSONAL_HOSTS` blocklist (30+ shorteners / aggregators / docs / scheduling tools). Verified 44/45 ok on a 45-handle pilot.
  436. - **New `tools/contact-extractor/`** — multi-source email extraction with confidence tiering. Sources: `personal_site` `/about` `/contact` `/press` (mailto / text) + YouTube Data API v3 description + Apple Podcasts RSS owner + email pattern guess. Optional `--verify` SMTP MX probe / Hunter.io. Outputs ranked `contact_email_1..3` + `confidence` (high / medium / low / none).
  437. - **`tools/trustpilot/` rebuilt**: modern data-* attribute selectors (replaces 110-line sibling-XPath fallback chain that broke on Trustpilot's 2026 DOM update), desktop-UA pin (Trustpilot serves snippet-only DOM to mobile UAs — major silent failure mode), `?sort=recency` URL flag (relevance widget served snippet-only DOM for some brands), `--cutoff_date YYYY-MM-DD` arg (efficient time-bounded scrapes), `--skip_ai` mode bypasses broken `generate_report()` signature, redacted hardcoded SOCKS5 proxy creds in `config.py` (now env-var loaded).
  438. - Total: **40 skills** across 10 chains. Tools count: 4 (was 1).
  439. ### v3.3 (2026-04-27)
  440. - **New entry-orchestrator skill** `dsite-seo-diagnostic` (single-file, under `brand-strategy/`) — for live-site SEO traffic-drop diagnostics + restart roadmap.
  441. - **7-dimension diagnostic framework**: traffic curve (algorithm-downgrade signature) / keyword loss structure / single-point-failure risk / multilingual-Markets URL pollution / backlink quality (DS distribution + anchor text pathology) / content ROI (HCU-hit detection) / KPI body audit (process-volume vs outcome).
  442. - **Algorithm-event alignment**: traffic curve auto-aligned with public Google Core / HCU / Spam Update timeline (rolling 24-month window).
  443. - **Restart roadmap**: 4-phase plan (stop-the-bleeding → cleanse → content rebuild → off-site signals) anchored on the `dsite-seo-playbook` 6-step framework.
  444. - **Multi-skill orchestration**: chains `xlsx` → `dsite-seo-playbook` → `trustpilot-voc-deep` / `competitors-analysis` / `backlink-kol-extractor` → `report-pdf-export`. Hides internal SKILL refs in deliverable.
  445. - **Standard PDF deliverable** (A4 landscape, deep-blue header, zebra rows, page-numbered) via `report-pdf-export`.
  446. - **Use cases**: traffic anomaly investigation, pre-vendor-replacement independent diagnostics, annual SEO health check, post-Core-Update impact assessment, post-migration audit, multilingual / Shopify Markets pollution audit.
  447. - Total: **39 skills** across 10 chains.
  448. ### v3.2 (2026-04-26)
  449. - **New Outbound Prospecting chain (2 multi-file skill packages)** under `outbound-prospecting/`:
  450. - `google-whatsapp-prospecting` — Google-dork → WhatsApp lead pipeline. 4-stage workflow (Search → Validate → Enrich → Outreach). 15+ search formula variants, 30+ countries with mobile-prefix narrowing + B2B platforms + time-zone send windows + compliance flags. Full GDPR / CASL / CCPA / UWG §7 / WhatsApp ToS compliance reference. Multi-language outreach playbook (EN/ES/PT/FR/AR). SerpAPI batch script + `wa.me` validator + lead-tracker CSV.
  451. - `linkedin-prospecting` — Google + Bing + Yandex + Wayback reverse-search of LinkedIn. Post-2024 Auth Wall workarounds. 50+ decision-maker role keywords localized into 8 languages with company-size-band gating (CEO targeting only valid for ≤500 employees). Enrichment-tool comparison (Apollo / Snov / Hunter / Lusha / Wiza) with cost + accuracy + legal context. LinkedIn ToS § 8.2 + 2026 quota table + account warm-up protocol. 4-touch outreach (Connection Request → DM → Follow-up → Channel-switch) with 12 DM templates across 5 archetypes (incl. voice-note opener), reply-handling matrix, native templates in PT/ES/FR/DE/AR/JA.
  452. - **New format**: multi-file skill packages (SKILL.md + references/ + templates/ with Python helpers + CSV trackers), in addition to existing single-file `.md` skills.
  453. - Total: **38 skills** across 10 chains.
  454. ### v3.1 (2026-04-14)
  455. - **New VOC chain (2 skills)**: `/trustpilot-voc-quick` (5-min surface scan) and `/trustpilot-voc-deep` (full pipeline with sentiment analysis, LDA topic modeling, and AI-powered insights)
  456. - **New tools directory**: `tools/trustpilot/` with Python toolkit for deep review analysis
  457. - Total: **36 skills** across 9 chains
  458. ### v3.0 (2026-04-13)
  459. - **12 new skills**: annual-plan, budget-ops, gtm-launch, seo-playbook, sem-ads, conversion-ux, tiktok-growth, youtube-ops, influencer-marketing, user-lifecycle-ops, social-content-calendar, offline-retail-us
  460. - **Chart visualization**: 21 skills now auto-generate charts via AntV API (radar, bar, column, pie, waterfall, scatter, line, funnel, sankey)
  461. - **Unified footers**: All 36 skills now include GitHub open source link
  462. - Total: **34 skills** across 8 chains
  463. ### v2.1 (2026-04-12)
  464. - Added `/brand-ab-compare` SKILL
  465. - Semrush local data auto-scan in Step 0
  466. - Data gap reporting, minimum depth constraints
  467. - SEO traffic model validation in Round 3
  468. - Auto knowledge base trigger in IMC
  469. ### v2.0 (2026-04-11)
  470. - Real-time data collection layer added to 3 brand strategy SKILLs
  471. ### v1.0 (2026-04-07)
  472. - Initial release: 6 brand strategy + 14 Amazon skills (20 total)
  473. ---
  474. ## License
  475. Licensed under [CC BY-NC 4.0](https://creativecommons.org/licenses/by-nc/4.0/).
  476. Free to use, share, and adapt with credit.
  477. ## Author
  478. Created by **Alex / 黄子阳** — **WhaleBridge / 远鲸引力**
  479. - **官网 / Website** — [whalebridge.us](https://whalebridge.us)
  480. - **介绍 PPT / Deck** — [ckcm.us](https://ckcm.us)
  481. ### Contact / 联系方式
  482. 有定制化调研需求、品牌咨询、或技能使用问题,扫码加微信:
  483. <img src="wechat-qr.png" alt="WeChat QR Code" width="200">
tools/security-precommit-check/scripts/selftest.sh · Bundled script · 244 lines · 1 finding marked
  1. #!/bin/bash
  2. # selftest.sh — assert every rule in rules/default.txt actually SCANS SOMETHING.
  3. #
  4. # Why this exists: the scanner fails OPEN, and it does so in two ways.
  5. # 1. LOUD — an invalid regex is dropped with a warning (scan.sh already prints it).
  6. # 2. SILENT — a regex that is perfectly VALID but matches nothing. `\|` inside a group
  7. # is a LITERAL pipe in ERE, not alternation, so `(api[_-]?key\|secret[_-]?key)` only
  8. # ever matched the text "api_key|secret_key". The rule sat in the file looking like
  9. # coverage while scanning nothing, with no warning of any kind. That is the failure
  10. # mode this file exists to catch: a rule is only real if it fires on a known positive.
  11. #
  12. # Usage: scripts/selftest.sh # default.txt + THIS repo's per-repo rules
  13. # scripts/selftest.sh RULES_FILE... # also check the given per-repo rule files
  14. #
  15. # 🔴 Per-repo rules (.security-precommit-rules.txt) are checked too, and by default, because
  16. # scan.sh loads them with exactly the same weight as the defaults — a dead rule there is just
  17. # as blind. They are held to a WEAKER standard on purpose: two of these repos are public, and
  18. # a positive control for "known-leaked proxy password" or "founder's real name" would mean
  19. # committing the very string the rule exists to keep out. So per-repo rules get regex validity
  20. # + the dead-alternation lint + the benign negative controls, and get the full positive-control
  21. # check only for those descriptions a companion .security-precommit-samples.txt covers.
  22. #
  23. # Parsing below MIRRORS scan.sh exactly (SEV = first field, DESC = last field, PATTERN =
  24. # everything between). If scan.sh's parser changes, change it here too — a selftest that
  25. # parses differently from the scanner is testing a fiction.
  26. set -uo pipefail
  27. SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
  28. RULES="$SCRIPT_DIR/../rules/default.txt"
  29. SAMPLES="$SCRIPT_DIR/../rules/selftest-samples.txt"
  30. # Same discovery scan.sh does, so selftest sees the same rule set the scanner will.
  31. REPO_ROOT="$(cd "$SCRIPT_DIR" && git rev-parse --show-toplevel 2>/dev/null || true)"
  32. EXTRA_RULES=()
  33. [ -n "$REPO_ROOT" ] && [ -f "$REPO_ROOT/.security-precommit-rules.txt" ] \
  34. && EXTRA_RULES+=("$REPO_ROOT/.security-precommit-rules.txt")
  35. for arg in "$@"; do
  36. [ -f "$arg" ] || { echo "selftest: no such rules file: $arg" >&2; exit 2; }
  37. EXTRA_RULES+=("$arg")
  38. done
  39. for f in "$RULES" "$SAMPLES"; do
  40. [ -f "$f" ] || { echo "selftest: missing $f" >&2; exit 2; }
  41. done
  42. # Samples store repeated bodies as <REP:c:n> so no credential-shaped literal sits in the
  43. # file (GitHub push protection blocks those on sight — see the samples-file header).
  44. # Expansion happens HERE, at match time, so the rules are still tested against the real shape.
  45. rep() { printf "%${2}s" '' | tr ' ' "$1"; }
  46. expand() {
  47. local s="$1" out="" pre rest rest2 c n
  48. while case "$s" in *"<REP:"*) true ;; *) false ;; esac; do
  49. pre="${s%%<REP:*}"; rest="${s#*<REP:}"
  50. c="${rest%%:*}"; rest2="${rest#*:}"; n="${rest2%%>*}"; s="${rest2#*>}"
  51. out="$out$pre$(rep "$c" "$n")"
  52. done
  53. printf '%s%s' "$out" "$s"
  54. }
  55. # bash 3.2 (macOS default) has no associative arrays → parallel arrays, like scan.sh.
  56. S_DESCS=(); S_VALS=()
  57. load_samples() { # replaces the sample table; empty/absent file = no samples
  58. S_DESCS=(); S_VALS=()
  59. [ -f "${1:-}" ] || return 0
  60. local line
  61. while IFS= read -r line || [ -n "$line" ]; do
  62. [ -z "$line" ] && continue
  63. case "$line" in \#*) continue ;; *"|"*) ;; *) continue ;; esac
  64. S_DESCS+=("${line%%|*}")
  65. S_VALS+=("$(expand "${line#*|}")")
  66. done < "$1"
  67. }
  68. load_samples "$SAMPLES"
  69. sample_for() { # echo the sample for a description, empty if none
  70. local want="$1" i
  71. [ ${#S_DESCS[@]} -eq 0 ] && return 1 # set -u: ${!arr[@]} on an empty array aborts
  72. for i in "${!S_DESCS[@]}"; do
  73. [ "${S_DESCS[$i]}" = "$want" ] && { printf '%s' "${S_VALS[$i]}"; return 0; }
  74. done
  75. return 1
  76. }
  77. PASS=0; FAIL=0; SEEN_DESCS=()
  78. fail() { printf ' ✗ %s\n' "$1"; FAIL=$((FAIL+1)); }
  79. pass() { PASS=$((PASS+1)); }
  80. echo "selftest: every rule in rules/default.txt must fire on a known-positive sample"
  81. echo
  82. # ---------- 1. every rule: valid regex + has a sample + matches it ----------
  83. while IFS= read -r line || [ -n "$line" ]; do
  84. [ -z "$line" ] && continue
  85. case "$line" in \#*) continue ;; *"|"*) ;; *) continue ;; esac
  86. sev="${line%%|*}"; rest="${line#*|}"; dsc="${rest##*|}"
  87. if [ "$rest" = "$dsc" ]; then pat="$rest"; dsc=""; else pat="${rest%|*}"; fi
  88. [ -z "$pat" ] && continue
  89. [ "$sev" != "BLOCK" ] && [ "$sev" != "WARN" ] && continue
  90. SEEN_DESCS+=("$dsc")
  91. # (a) regex must be valid — same probe scan.sh uses to drop rules
  92. rx_err=$(printf 'probe' | grep -E -e "$pat" 2>&1 >/dev/null)
  93. if [ -n "$rx_err" ]; then fail "[$sev] $dsc — INVALID REGEX (scan.sh drops it): $pat"; continue; fi
  94. # (b) must have a positive control
  95. if ! smp=$(sample_for "$dsc"); then
  96. fail "[$sev] $dsc — no positive control in $(basename "$SAMPLES") (add one: DESCRIPTION|SAMPLE)"
  97. continue
  98. fi
  99. # (c) the rule must actually match it — this is what catches the silent-dead class
  100. if printf '%s' "$smp" | grep -qE -e "$pat" 2>/dev/null; then pass
  101. else fail "[$sev] $dsc — DEAD: valid regex that does not match its own sample"; fi
  102. done < "$RULES"
  103. # ---------- 2. stale samples (a rule was renamed/removed) ----------
  104. for i in "${!S_DESCS[@]}"; do
  105. found=0
  106. for d in "${SEEN_DESCS[@]}"; do [ "$d" = "${S_DESCS[$i]}" ] && { found=1; break; }; done
  107. [ "$found" -eq 0 ] && fail "sample '${S_DESCS[$i]}' matches no rule — stale, rename or drop it"
  108. done
  109. # ---------- 3. negative controls: benign lines must trip NO block rule ----------
  110. # Guards the other direction: an over-broad rule that blocks ordinary code is a rule people
  111. # will start bypassing with --no-verify, which costs more than it saves.
  112. BENIGN=(
  113. 'const apiKey = process.env.OPENAI_API_KEY;'
  114. 'password = os.environ["DB_PASSWORD"]'
  115. 'https://github.com/noique/theme-to-astro-clone.git'
  116. 'import { spawn } from "node:child_process";'
  117. 'dGhpcyBpcyBqdXN0IGJhc2U2NCBkYXRhIGZvciB0ZXN0aW5nIHB1cnBvc2Vz'
    • Dismissed after review: Contains a long base64-looking blob — not necessarily malicious, but worth inspecting what it decodes to
    • Line 134 on GitHub
  118. 'See the docs for sk- style keys and how to rotate them.'
  119. )
  120. while IFS= read -r line || [ -n "$line" ]; do
  121. [ -z "$line" ] && continue
  122. case "$line" in \#*) continue ;; *"|"*) ;; *) continue ;; esac
  123. sev="${line%%|*}"; [ "$sev" = "BLOCK" ] || continue
  124. rest="${line#*|}"; dsc="${rest##*|}"
  125. if [ "$rest" = "$dsc" ]; then pat="$rest"; else pat="${rest%|*}"; fi
  126. printf 'probe' | grep -E -e "$pat" >/dev/null 2>&1
  127. [ $? -gt 1 ] && continue # invalid regex already reported above
  128. for b in "${BENIGN[@]}"; do
  129. if printf '%s' "$b" | grep -qE -e "$pat" 2>/dev/null; then
  130. fail "[BLOCK] $dsc — FALSE POSITIVE on benign line: $b"
  131. fi
  132. done
  133. done < "$RULES"
  134. # ---------- 4. the vendor-prefix rules must not shadow each other ----------
  135. # Regression for the generic sk- rule: it is deliberately written WITHOUT a negative
  136. # lookahead (ERE has none), relying on `-` being outside [a-zA-Z0-9] to skip sk-ant- /
  137. # sk-proj- keys, which own dedicated rules. If someone "fixes" it to sk-[A-Za-z0-9_-]{40,}
  138. # every Anthropic key would report twice under the wrong name.
  139. GENERIC_SK=$(grep -E '^BLOCK\|sk-\[' "$RULES" | head -1)
  140. if [ -n "$GENERIC_SK" ]; then
  141. rest="${GENERIC_SK#*|}"; gpat="${rest%|*}"
  142. for d in "Anthropic API key" "OpenAI project API key"; do
  143. if smp=$(sample_for "$d"); then
  144. if printf '%s' "$smp" | grep -qE -e "$gpat" 2>/dev/null; then
  145. fail "generic sk- rule also matches the $d sample — it should leave that to the dedicated rule"
  146. else pass; fi
  147. fi
  148. done
  149. fi
  150. # ---------- 5. per-repo rule files (.security-precommit-rules.txt) ----------
  151. # scan.sh gives these the same weight as the defaults, so they get checked too. Weaker
  152. # standard, for the reason in the header: some positive controls cannot exist in a public
  153. # repo. What IS enforced everywhere: valid regex, no dead alternation, no benign false
  154. # positive. Rules with no positive control are counted and reported as UNPROVEN, never
  155. # silently folded into the pass count — an unproven rule is not a passing rule.
  156. UNPROVEN=0
  157. if [ ${#EXTRA_RULES[@]} -gt 0 ]; then
  158. for rf in "${EXTRA_RULES[@]}"; do
  159. echo "per-repo rules: $rf"
  160. load_samples "${rf%.txt}"".samples.txt" # .security-precommit-rules.samples.txt
  161. [ ${#S_DESCS[@]} -eq 0 ] && load_samples "$(dirname "$rf")/.security-precommit-samples.txt"
  162. while IFS= read -r line || [ -n "$line" ]; do
  163. [ -z "$line" ] && continue
  164. case "$line" in \#*) continue ;; *"|"*) ;; *) continue ;; esac
  165. sev="${line%%|*}"; rest="${line#*|}"; dsc="${rest##*|}"
  166. if [ "$rest" = "$dsc" ]; then pat="$rest"; dsc=""; else pat="${rest%|*}"; fi
  167. [ -z "$pat" ] && continue
  168. [ "$sev" != "BLOCK" ] && [ "$sev" != "WARN" ] && continue
  169. # (a) valid regex — scan.sh would drop it loudly
  170. rx_err=$(printf 'probe' | grep -E -e "$pat" 2>&1 >/dev/null)
  171. if [ -n "$rx_err" ]; then fail "[$sev] $dsc — INVALID REGEX (scan.sh drops it): $pat"; continue; fi
  172. # (b) dead alternation — the exact bug that shipped here. `\|` is a LITERAL pipe in
  173. # ERE, so (a\|b) matches only the text "a|b". Valid regex, zero coverage, silent.
  174. # A bare `|` parses fine (SEV is first field, DESC is last); for a genuine literal
  175. # pipe write [|], which is unambiguous.
  176. case "$pat" in
  177. *'\|'*) fail "[$sev] $dsc — DEAD ALTERNATION: \\| is a literal pipe in ERE, so this only matches the text with a pipe in it. Use (a|b), or [|] for a real literal pipe: $pat"
  178. continue ;;
  179. esac
  180. # (c) BLOCK rules must not fire on ordinary code
  181. if [ "$sev" = "BLOCK" ]; then
  182. for b in "${BENIGN[@]}"; do
  183. printf '%s' "$b" | grep -qE -e "$pat" 2>/dev/null \
  184. && fail "[BLOCK] $dsc — FALSE POSITIVE on benign line: $b"
  185. done
  186. fi
  187. # (d) positive control when one exists.
  188. # 🔴 Per-repo descriptions are NOT unique — this file has 9 rules all described
  189. # "Competitor brand name". Keying on the FIRST sample with that description would
  190. # test all 9 against one brand and report the other 8 dead. So the rule passes if
  191. # it fires on ANY sample carrying its description; a genuinely dead rule (typo'd
  192. # pattern) still matches none of them and is still caught.
  193. hit=0; have=0
  194. if [ ${#S_DESCS[@]} -gt 0 ]; then
  195. for si in "${!S_DESCS[@]}"; do
  196. [ "${S_DESCS[$si]}" = "$dsc" ] || continue
  197. have=1
  198. printf '%s' "${S_VALS[$si]}" | grep -qE -e "$pat" 2>/dev/null && { hit=1; break; }
  199. done
  200. fi
  201. if [ "$have" -eq 0 ]; then UNPROVEN=$((UNPROVEN+1))
  202. elif [ "$hit" -eq 1 ]; then pass
  203. else fail "[$sev] $dsc — DEAD: valid regex, matches no sample carrying its description: $pat"; fi
  204. done < "$rf"
  205. done
  206. echo
  207. fi
  208. echo
  209. if [ "$UNPROVEN" -gt 0 ]; then
  210. printf 'selftest: ⚠ %d per-repo rule(s) have no positive control — checked for validity, NOT proven to fire.\n' "$UNPROVEN"
  211. printf ' Add controls in .security-precommit-samples.txt (DESCRIPTION|SAMPLE) for any whose sample is safe to store.\n'
  212. fi
  213. if [ "$FAIL" -gt 0 ]; then
  214. printf 'selftest: %d passed · %d FAILED — a failing rule scans nothing; fix it or the gate is theatre.\n' "$PASS" "$FAIL"
  215. exit 1
  216. fi
  217. printf 'selftest: ✅ %d checks passed — every rule fires on its positive control.\n' "$PASS"
  218. exit 0

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.