rate-shopping — Claude Code skill: what it does, how to install
rate-shopping compares multi-carrier shipping rates via the Shippo API, filters services by delivery speed, and finds the best value option.
MIT 1 installs ★ 3 updated 2026-10-09
npx skills add goshippo/ai --skill rate-shopping -a claude-codeWhat rate-shopping does
This skill guides coding assistants to prepare shipment details and query the Shippo API using CreateShipment or CreateLiveRate. Parcel dimensions and weights must be supplied strictly as string values (such as "10" instead of integers), preventing payload formatting errors. The model presents carrier rates in a clean table displaying carrier names, service tiers, prices, and transit days.
API responses do not label the best deal automatically. The assistant sorts the rates array directly to spot the cheapest quote, shortest transit window, and practical trade-offs. Duplicate options from multiple linked carrier accounts are filtered to show only the best rate per service. For international shipments, the logic checks for customs declarations and mandatory recipient phone numbers.
Retrieved rates expire strictly after 7 days. Attempting to purchase a shipping label past that window requires initiating a new shipment to get valid pricing.
What it helps with
- compare shipping rates across carriers for a single package
- filter carrier quotes by delivery window or overnight priority
- calculate cart checkout shipping via
CreateLiveRate - convert shipment quotes to a specific ISO currency code
Example prompts for the agent
- Find the cheapest shipping option for a
"12"x"8"x"6"box weighing"4"lbs from Seattle to Boston. - Show overnight and 2-day delivery options for this destination address.
- Get checkout shipping rates in EUR for these line items using
CreateLiveRate.
How to install rate-shopping
1Skills CLI (Vercel)
npx skills add goshippo/ai --skill rate-shopping -a claude-code2Manually: put the files in place
~/.claude/skills/rate-shopping/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/rate-shopping/
1Skills CLI (Vercel)
npx skills add goshippo/ai --skill rate-shopping -a codex2Manually: put the files in place
.agents/skills/rate-shopping/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add goshippo/ai --skill rate-shopping -a cursor2Manually: put the files in place
.cursor/skills/rate-shopping/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install goshippo/ai skills/rate-shopping2Manually: put the files in place
.github/skills/rate-shopping/SKILL.md1Skills CLI (Vercel)
npx skills add goshippo/ai --skill rate-shopping -a gemini-cli2Platform CLI
gemini skills install https://github.com/goshippo/ai --path skills/rate-shoppingManually: put the files in place
.devin/skills/rate-shopping/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add goshippo/ai --skill rate-shopping -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about rate-shopping
How to install rate-shopping in Claude Code?
Run npx skills add goshippo/ai --skill rate-shopping -a claude-code in your terminal.
What does the rate-shopping skill do?
It teaches AI assistants how to query the Shippo API, validate addresses, and compare multi-carrier freight options based on price and transit time.
Why must dimensions and weights be formatted as strings?
The Shippo API rate endpoint expects dimension and weight properties wrapped in quotes, such as "10", rather than raw numbers.
Source text
SKILL.md · MIT
--- name: rate-shopping description: Compare multi-carrier shipping rates, find cheapest/fastest options, and get shipping recommendations via the Shippo API --- # Rate Shopping and Comparison ## Get Rates for a Shipment 1. Collect: origin address, destination address, parcel (length, width, height, distance_unit, weight, mass_unit). All dimension and weight values must be **strings** (e.g., `"10"` not `10`). 2. Optionally validate both addresses with `ValidateAddress` (see Address Validation). 3. Call `CreateShipment` with `address_from`, `address_to` (as inline address objects using v1 field names -- `street1`, `city`, `state`, `zip`, `country` -- not object IDs), and `parcels`. 4. The response `rates` array contains available options. Present a table: carrier, service level, price, estimated days. 5. Note: the same carrier may return duplicate rates from multiple carrier accounts. Present the best rate per carrier/service combination. 6. Each rate carries an `object_id`. To buy a label, pass the chosen rate's `object_id` to the purchase flow (see Label Purchase); you do not re-send the address or parcel. --- ## Rate Expiration Rates expire after 7 days. If a user tries to purchase a rate that was retrieved more than 7 days ago, create a new shipment to get fresh rates. --- ## Filter by Speed Map user requests: "overnight" = estimated_days 1, "2-day" = estimated_days <= 2, "within N days" = estimated_days <= N. Filter the rates array accordingly. If nothing matches, show the fastest available option. --- ## International Rates Some carriers may return international rates without a customs declaration, but others will not. If no rates are returned, try attaching a customs declaration to the shipment. Some carriers also require a phone number on the destination address for international rate retrieval. Inform the user that customs will be required at label purchase time regardless. See `shippo/references/customs-guide.md` for customs details. --- ## Checkout Rates (Line Items) Call `CreateLiveRate` instead of `CreateShipment`. Accepts `address_from`, `address_to`, and `line_items` (each with title, quantity, total_price, currency, weight, weight_unit). --- ## Rates in a Specific Currency Call `ListShipmentRatesByCurrencyCode` with the preferred ISO currency code (USD, EUR, GBP, CAD, etc.). --- ## Recommendation Identify the cheapest (lowest `amount`), fastest (lowest `estimated_days`), and best-value options from the rates array. These are not API fields -- compute them by sorting the rates array yourself. State the trade-off: "Option A is $X cheaper but takes Y more days than Option B." --- ## Troubleshooting: No Rates - Verify both addresses passed validation (most common cause). - Confirm parcel dimensions are reasonable (not zero, not exceeding carrier limits). - Shippo provides managed carrier accounts by default for major carriers. If no rates are returned, the issue is more likely address validation, unsupported route, or parcel dimensions -- not missing carrier accounts. You can verify with `ListCarrierAccounts` if needed. - Rates expire after 7 days. If stale, create a new shipment to get fresh rates. --- ## Quick Reference **Get rates:** (optional) `ValidateAddress` (x2) -> `CreateShipment` (with inline addresses) -> read `rates` array
© goshippo · MIT · goshippo/ai