# Contributing a source-site skill

You figured out how to navigate a vendor's CAD-download flow — maybe a site
chip-fetcher didn't cover, maybe a new way past a block (the day DigiKey blocked
pup, someone chatted with its assistant and found a path; that knowledge belongs
here). Here's how to get it into the pack so everyone's AI benefits.

## Write the skill

Copy `sites/snapeda/SKILL.md` as a template and fill in the five sections (Reach,
Gate, Download flow, Catch, When it breaks). Keep it to **one site per skill** and
give it real trigger words (the vendor name, "blocked", "captcha", the file types)
so the AI auto-surfaces it at the right moment.

## Two ways to land it — the owner picks per contribution

The pack supports two contribution shapes. Which one is allowed for a given skill
is the **maintainer's call**, made deliberately, trading freshness against trust:

### A. Pull request INTO the pack (vetted — the default)

Open a PR adding `sites/<vendor>/SKILL.md` to this repo. The maintainer reads the
navigation steps, sanity-checks them, and merges. The skill now lives in the
chip-fetcher repo and ships with the pack.

- **Pro:** every step is reviewed before it reaches anyone's AI — the safe default.
- **Con:** updates require another PR; the maintainer is in the loop each time.
- **Use when:** the contributor is new/unknown, or the skill does anything
  sensitive (credential handling, evading a block, executing fetched content).

### B. Linked external skill (trusted — opt-in)

Publish your skill as its **own wiki repo** (you own it, you `adompkg publish`
updates whenever you like). Then PR a one-line **link** into this pack's manifest
instead of the skill body. The pack references your repo; your repo stays yours.

- **Pro:** you keep ownership and can fix your site's flow the hour it changes,
  no maintainer round-trip — exactly what a fast-moving vendor site needs.
- **Con:** the pack now trusts a repo it doesn't control; a later edit isn't
  re-reviewed. So this is **trusted-contributor only**.
- **Use when:** the maintainer knows the contributor and is comfortable letting
  their repo update live.

> The link itself still arrives by PR, so the maintainer always makes the
> conscious decision to trust a given external repo — but once linked, that repo
> self-updates. Default to (A); grant (B) to people you trust. Revoking is just
> dropping the link.

## Security & vetting

Site skills tell an AI to drive a real browser on the user's machine, sometimes
past anti-bot defenses. Treat every contribution as code review:

- No skill should exfiltrate credentials or paste them anywhere but the vendor's
  own login. Creds come from `chip-fetcher creds`, never inline.
- "Getting past a block" means *navigating the site as a human would* (right
  profile, human pacing, the path their own assistant suggested) — **not**
  defeating security controls or solving CAPTCHAs programmatically.
- A linked external skill (path B) inherits the trust you grant its repo. When in
  doubt, require path A.

## Status (for Colby / the wiki)

Path A (PR into the pack) works on the wiki today — it's a normal pull request.
Path B (a pack sub-skill that *links* an externally-owned wiki repo, which then
self-updates) is the piece that needs platform support: a manifest link type the
pack resolves at install time, plus a way for the maintainer to mark a given link
trusted. Tracked in the chip-fetcher Colby feedback.