Shippo AI
This repo is the one-stop shop for building AI-powered shipping integrations with Shippo.
It contains:
- 8 Agent Skills: Workflow knowledge for AI assistants covering rate shopping, address validation, label purchase (with customs), package tracking, batch shipping, shipping cost analysis, integration best practices, and SDK/API upgrades. Authored once and distributed across multiple AI surfaces.
- Claude Code Plugin (
providers/claude/plugin/): Install via --plugin-dir or the plugin marketplace (/plugin marketplace add goshippo/ai).
- OpenAI Codex Plugin (
providers/codex/plugin/): Install via the Codex plugin marketplace; bundles the skills plus the OAuth MCP server.
- ClawHub Skill (
providers/clawhub/skills/goshippo/): Install via openclaw skills install goshippo.
- Claude apps (claude.ai / Desktop / Cowork): The whole plugin is packaged as a single upload-ready ZIP (
shippo-plugin.zip), attached to every GitHub Release. One upload provisions all the skills.
What is a skill?
A skill is a folder containing a SKILL.md file, YAML frontmatter (at minimum: name and description) plus markdown instructions that tell an AI assistant how to perform a specific task. Skills can also bundle reference docs, scripts, and templates.
rate-shopping/
├── SKILL.md # required: metadata + instructions
└── README.md # optional: human-facing orientation
Agents load skills by progressive disclosure in three stages:
- Discovery: at startup, the agent loads only each skill's
name and description, just enough to know when it might be relevant.
- Activation: when a user prompt matches a skill's description, the agent loads the full
SKILL.md body into context.
- Execution: the agent follows the instructions, optionally loading referenced files (
shippo/references/*.md) as it works.
Agent Skills is an open standard originally developed by Anthropic. The same SKILL.md works in Claude Code, Cursor, OpenAI Codex, GitHub Copilot, VS Code, and 30+ other agents.
In this repo, the 8 skills under skills/ are the canonical source. They're propagated into providers/claude/plugin/skills/ and providers/codex/plugin/skills/ (1:1 mirrors) and providers/clawhub/skills/goshippo/ (consolidated digest) automatically by the sync scripts.
Model Context Protocol (MCP)
Shippo hosts a remote MCP server with per-user OAuth. Each user authorizes once through Shippo, there is no API key to copy. The Claude Code and OpenAI Codex plugins point at this endpoint and trigger the sign-in on first use.
| URL | Transport | Auth |
|---|
https://mcp.shippo.com | Streamable HTTP | Per-user Shippo OAuth |
For per-tool semantics and usage, see the Shippo MCP server docs.
Building on OpenAI? See Using the Shippo MCP from the OpenAI Responses API / Agents SDK for the developer config (no submission required).
Capabilities
The 8 skills in this repo are organized by mode of engagement: what the user is doing, not by product surface. The AI assistant matches the user's intent to one of three modes, then loads the right skill.
Decide, "where do I start?"
| Skill | What it does |
|---|
shippo-best-practices | Decision-router for Shippo integrations, which API to use, test vs. live mode discipline, response handling, critical rules |
Do, "execute this workflow"
| Skill | What it does |
|---|
address-validation | Validate, parse, and standardize US and international addresses |
rate-shopping | Compare rates across USPS, UPS, FedEx, DHL, and 30+ carriers |
label-purchase | Purchase domestic and international shipping labels with customs handling |
tracking | Track packages across carriers with status history, substatus codes, and webhooks |
batch-shipping | Process CSV files of shipments and generate labels in bulk |
shipping-analysis | Analyze costs, optimize package dimensions, compare carriers, review historical spend |
Maintain, "upgrade or migrate"
| Skill | What it does |
|---|
upgrade-shippo | Guide for upgrading SDK versions, MCP server updates, breaking-change migration |
