Source Scout

Source Scout is a sourcing skill for Claude, Codex, and Agent Skills compatible agents. It analyzes shopping links or market trend requests, then finds China-first exact-match suppliers, cheaper alternatives, supplier contact paths, purchase links, keywords, margin estimates, local AI-generated SVG product display images, and sourcing risks. For platform sales trend requests, the default output is a Top-product sourcing and substitute report, not a trend-only summary.

Public Data And Compliance Boundary

Source Scout only uses public, accessible information. This includes public product pages, search pages, category pages, public trend rankings, public images, and public Alibaba search-entry pages.

The skill must not use any method to improperly scrape or obtain data, and it must not bypass login, CAPTCHA, risk-control or anti-bot systems, paywalls, hidden content, private data, or platform access restrictions. If a direct product, supplier, source, trend, or image link is blocked, login-gated, CAPTCHA-gated, paywalled, hidden, private, anti-bot/risk-control gated, blank, or inaccessible, it must be removed as evidence and downgraded to a verified public search-entry URL or marked unavailable/pending.

Recommended Models

• Claude: Opus 4.6/4.7 xhigh or max
• Codex: GPT-5.5 high or xhigh

The skill can run on other capable models, but stronger models are recommended because the workflow includes current web research, product matching judgment, supplier risk review, margin calculation, and report generation.

Recommended Client

For the most stable results, use Source Scout in Codex Desktop or a Claude Code local client workflow. Desktop/local clients usually handle file access, script execution, image downloads, ZIP validation, and HTML report rendering more consistently than a pure web-chat workflow. Claude web Skills upload is still supported, but complex sourcing reports are more reliable in a local client environment.

Repository Contents

• source-scout/: installable Codex skill folder.
• Source-Scout.zip: zip package of the installable skill folder.
• QUICK_START.md: short install and usage notes.
• DETAILED_USAGE.md: workflow details and report expectations.

What It Does

• Analyzes product links from Amazon, eBay, TikTok Shop, Walmart, Target, and similar marketplaces.
• Uses Alibaba.com for sourcing and substitute links by default.
• Prioritizes China suppliers and filters non-China suppliers unless cost is at most 80% of the original selling price.
• Calculates estimated margin as (selling price - supplier unit cost) / supplier unit cost * 100%.
• Always provides substitutes or alternatives even when an exact match is found.
• Verifies direct product, supplier, purchase, and trend links before putting them in the final report, and rejects links that require login, CAPTCHA, risk-control/anti-bot bypass, paywall access, hidden content, or private data access.
• Treats marketplace trend prompts as requests for Top products plus sourcing and substitutes by default.
• Defaults trend reports to 5 categories when the user does not specify categories, and Top 3 products per category when the user does not specify item count.
• Builds fixed-layout HTML/PDF-ready sourcing reports from JSON so page structure stays consistent across models.
• Requires a verified source marketplace product link when publicly available and a local AI-generated SVG display image for every trend Top product.
• Requires separate clickable Alibaba 货源链接 and Alibaba 平替链接 for every final HTML product card. Direct product/supplier links are preferred only when they open useful details without login; if a product-detail URL returns 200 but still shows a login wall or blank detail shell, use a verified Alibaba search-entry URL as the card button and keep the detail URL only as a candidate lead.
• Uses deterministic Alibaba search-entry URLs when Alibaba direct links are missing or unstable. The skill does not use justoneapi, Playwright CLI, browser tools, browser automation, or scraping APIs for candidate discovery.
• Requires verified product/supplier links for primary exact-match source and substitute recommendations. Search keywords are supplemental leads, not replacements for clickable links.
• Uses local AI-generated SVG illustrations for product-card display images by default. Real marketplace, supplier, search-card, stock, near-match, or representative web images are not used as final product-card images unless explicitly requested for a specific run.
• Checks final Chinese JSON/HTML reports for encoding artifacts such as triple-question-mark sequences, Unicode replacement characters, and common Chinese mojibake fragments before delivery.

Fast Install For Claude

1. Download Source-Scout.zip from the latest GitHub Release. If this repository includes Source-Scout.zip at the root, that file can also be used directly.
2. Open Claude.ai.
3. Go to Settings -> Capabilities -> Skills.
4. Upload Source-Scout.zip.
5. Enable the skill.
6. Start with:

Use $source-scout to analyze this Amazon product link and find China-first sources, cheaper alternatives, margins, risks, and an HTML-ready report: <url>

The ZIP must contain the source-scout/ folder at its root:

Source-Scout.zip
└── source-scout/
    ├── SKILL.md
    ├── agents/
    ├── scripts/
    └── references/

Do not upload GitHub's default source-code ZIP unless it has this exact structure. GitHub's default source download usually wraps the files in an extra repository folder, which can prevent Claude from recognizing the skill.

Fast Install For Codex

Clone or download this repository, then copy the installable skill folder into your Codex skills directory.

Windows PowerShell:

Copy-Item -Recurse .\source-scout "$env:USERPROFILE\.codex\skills\source-scout" -Force

macOS/Linux:

mkdir -p ~/.codex/skills
cp -R ./source-scout ~/.codex/skills/source-scout

Start a new Codex session and invoke:

Use $source-scout to analyze TikTok Shop hot products in the US beauty category and find China suppliers.

For sales trend prompts, Source Scout assumes you want the visible Top products, their verified marketplace product links, local AI-generated SVG display images, plus clickable China-first sourcing and substitute paths for each product.

Create The Claude ZIP

From the repository root:

Compress-Archive -Path .\source-scout -DestinationPath .\Source-Scout.zip -Force

Upload Source-Scout.zip as a GitHub Release asset so Claude users can install it without repackaging the repository.

Quality Gates

Before final reports, run link verification and SVG image normalization:

python .\source-scout\scripts\verify_assets.py --input report.json --output verified-assets.json --retries 1 --max-page-images 0
python .\source-scout\scripts\apply_verified_assets.py --report report.json --verified verified-assets.json --output report.json

For HTML/PDF-ready output, render from the fixed JSON template. The renderer fills the packaged HTML shell at source-scout/templates/report-template.html:

python .\source-scout\scripts\render_report.py --input report.json --output report.html
python .\source-scout\scripts\check_text_quality.py report.json report.html

Broken, blocked, login-gated, CAPTCHA-gated, risk-control/anti-bot gated, paywalled, hidden-content, private-data, or 404 URLs should be retried before final output. Treat public_access_safe: true from verify_assets.py as the direct-use gate for page links. If a trend Top product still lacks a verified public source product link, replace it with another verifiable Top candidate or leave the report in draft state. Product-card images should be clearly labeled local AI-generated SVG illustrations; do not use real marketplace/supplier images, near-match web images, or unrelated representative images by default.

If Alibaba product-detail pages are unstable, keep the final card button on a verified Alibaba search-entry URL. Do not escalate to justoneapi, Playwright CLI, browser tools, browser automation, or scraping APIs.

When generating Chinese reports on Windows, avoid sending large Chinese JSON/Python/HTML payloads through PowerShell stdin, pipes, or here-strings. Use UTF-8-safe file writes, then run check_text_quality.py; if it finds encoding artifacts, fix the source JSON or template and re-render instead of patching only the HTML.

Publish This Repository

If this folder is not already a Git repository:

git init
git add .
git commit -m "Initial Source Scout skill release"
git branch -M main
git remote add origin https://github.com/wlpc001/source-scout.git
git push -u origin main

Then create a GitHub Release and upload Source-Scout.zip as the release asset.

Repository Layout

source-scout/
├── README.md
├── QUICK_START.md
├── DETAILED_USAGE.md
├── Source-Scout.zip
└── source-scout/
    ├── SKILL.md
    ├── agents/openai.yaml
    ├── scripts/
    ├── templates/report-template.html
    └── references/

Only the nested source-scout/ folder is the installable skill. The README files are for GitHub users.

Docs

• Quick guide: QUICK_START.md
• Detailed guide: DETAILED_USAGE.md

Safety

This skill uses only public, accessible information and does not bypass login walls, CAPTCHAs, risk-control or anti-bot systems, paywalls, hidden content, private data, or platform access controls. Prices, supplier terms, certifications, and contact details must be verified by inquiry before purchasing.

Compatibility Notes

The skill follows the common Agent Skills shape: a folder named like the skill, a required SKILL.md, YAML frontmatter with name and description, optional references/, and agent metadata.

Useful references:

• Claude custom skills: https://claude.com/docs/skills/how-to
• Agent Skills specification: https://agentskills.io/specification
• OpenAI Skills repository: https://github.com/openai/skills