{
  "markdown": "# Shippo AI\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) [![Validate](https://github.com/goshippo/ai/actions/workflows/validate.yml/badge.svg)](https://github.com/goshippo/ai/actions/workflows/validate.yml) [![Latest release](https://img.shields.io/github/v/release/goshippo/ai)](https://github.com/goshippo/ai/releases)\n\nThis repo is the one-stop shop for building AI-powered shipping integrations with Shippo.\n\nIt contains:\n\n* **9 Agent Skills**: Workflow knowledge for AI assistants covering rate shopping, address validation, label purchase (with customs), package tracking, batch shipping, shipping cost analysis, support-ticket drafting, integration best practices, and SDK/API upgrades. Authored once and distributed across multiple AI surfaces.\n* **Claude Code Plugin** ([`providers/claude/plugin/`](/providers/claude/plugin)): Install via `--plugin-dir` or the plugin marketplace (`/plugin marketplace add goshippo/ai`).\n* **OpenAI Codex Plugin** ([`providers/codex/plugin/`](/providers/codex/plugin)): Install via the Codex plugin marketplace; bundles the skills plus the OAuth MCP server.\n* **ClawHub Skill** ([`providers/clawhub/skills/shippo/`](/providers/clawhub/skills/shippo)): Install via `openclaw skills install @shippo/shippo`.\n* **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.\n* **Knowledge Pack (ChatGPT and other chat assistants)** ([`providers/knowledge-pack/shippo-knowledge-pack.md`](/providers/knowledge-pack/shippo-knowledge-pack.md)): A single consolidated markdown for assistants that do **not** load `SKILL.md` folders. A user drops it into a chat, a Custom GPT's Knowledge, or a Project as context. It provides the shipping knowledge; live actions still use the hosted MCP connector.\n\n## What is a skill?\n\nA skill is a folder containing a [`SKILL.md`](https://agentskills.io/specification) 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.\n\n```\nrate-shopping/\n├── SKILL.md           # required: metadata + instructions\n└── README.md          # optional: human-facing orientation\n```\n\nAgents load skills by **progressive disclosure** in three stages:\n\n1. **Discovery**: at startup, the agent loads only each skill's `name` and `description`, just enough to know when it might be relevant.\n2. **Activation**: when a user prompt matches a skill's description, the agent loads the full `SKILL.md` body into context.\n3. **Execution**: the agent follows the instructions, optionally loading referenced files (`shippo/references/*.md`) as it works.\n\n[Agent Skills](https://agentskills.io) 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.\n\nIn this repo, the 9 skills under `skills/` are the **canonical source**. They're propagated into `providers/claude/plugin/skills/` and `providers/codex/plugin/skills/` (1:1 mirrors), `providers/clawhub/skills/shippo/` (consolidated digest), and `providers/knowledge-pack/shippo-knowledge-pack.md` (a single upload-ready knowledge pack for ChatGPT and other non-skill-loading assistants) automatically by the sync scripts.\n\n## Model Context Protocol (MCP)\n\nShippo 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.\n\n| URL | Transport | Auth |\n|---|---|---|\n| `https://mcp.shippo.com` | Streamable HTTP | Per-user Shippo OAuth |\n\nFor per-tool semantics and usage, see the [Shippo MCP server docs](https://docs.goshippo.com/docs/Guides_general/MCPServer).\n\nBuilding on OpenAI? See [Using the Shippo MCP from the OpenAI Responses API / Agents SDK](docs/openai-responses-mcp.md) for the developer config (no submission required).\n\n## Capabilities\n\nThe 9 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.\n\n### Decide, \"where do I start?\"\n\n| Skill | What it does |\n|---|---|\n| `shippo-best-practices` | Decision-router for Shippo integrations, which API to use, test vs. live mode discipline, response handling, critical rules |\n\n### Do, \"execute this workflow\"\n\n| Skill | What it does |\n|---|---|\n| `address-validation` | Validate, parse, and standardize US and international addresses |\n| `rate-shopping` | Compare rates across USPS, UPS, FedEx, DHL, and 30+ carriers |\n| `label-purchase` | Purchase domestic and international shipping labels with customs handling |\n| `tracking` | Track packages across carriers with status history, substatus codes, and webhooks |\n| `batch-shipping` | Process CSV files of shipments and generate labels in bulk |\n| `shipping-analysis` | Analyze costs, optimize package dimensions, compare carriers, review historical spend |\n| `shippo-support-ticket` | Build an auto-classified, routing-tagged support ticket (human + JSON) for a single shipment or label; read-only, for Shippo support agents |\n\n### Maintain, \"upgrade or migrate\"\n\n| Skill | What it does |\n|---|---|\n| `upgrade-shippo` | Guide for upgrading SDK versions, MCP server updates, breaking-change migration |\n\nA user who already knows the workflow they need (\"buy a label\", \"track this package\") jumps straight to a Do skill. A user starting fresh (\"I'm building a checkout flow with shipping, where do I start?\") hits the Decide skill, which routes them to the right Do skill. Maintenance gets its own skill so production-readiness questions don't compete with workflow content.\n\nThe 9 skills lean on **11 shared reference docs** under `skills/shippo/references/` (carriers, customs, CSV format, error reference, etc.). Skills load references on demand, the AI doesn't pull all 11 into context, just the ones a given workflow needs.\n\n## Install\n\n### Claude Code\n\n```bash\ngit clone https://github.com/goshippo/ai.git\nclaude --plugin-dir ./ai/providers/claude/plugin\n```\n\nOr install from the plugin marketplace:\n\n```bash\n/plugin marketplace add goshippo/ai\n/plugin install shippo@shippo\n```\n\nOn first use, run `/mcp`, select the Shippo server, and sign in to authorize the MCP over OAuth (no API key to copy).\n\nSkills are namespaced under `/shippo:`: invoke directly with `/shippo:rate-shopping`, `/shippo:label-purchase`, `/shippo:tracking`, etc., or just describe what you're doing in natural language.\n\n### OpenAI Codex\n\nCodex installs the Shippo plugin (skills + OAuth MCP) from this repo's plugin marketplace:\n\n```bash\ncodex plugin marketplace add goshippo/ai\ncodex plugin add shippo@shippo   # install the \"shippo\" plugin\ncodex mcp login shippo           # authorize the remote MCP over OAuth\n```\n\nSee [`providers/codex/plugin/`](/providers/codex/plugin) for details. (To pull just the skill content without the plugin, Codex's `skill-installer` can also install a single `providers/codex/plugin/skills/<name>` directory.)\n\n### ClawHub\n\n```bash\nopenclaw skills install @shippo/shippo\n```\n\n(Published as `@shippo/shippo` on the [ClawHub registry](https://clawhub.ai/shippo/shippo).)\n\n### Claude apps (claude.ai / Desktop / Cowork)\n\nThe Claude apps load the plugin as a single ZIP. `shippo-plugin.zip` (the whole plugin: manifest, OAuth MCP config, and all skills) is attached to every [GitHub Release](https://github.com/goshippo/ai/releases). Download it and add it via the app's Plugins UI. A Team/Enterprise admin can provision it org-wide in one step: Organization settings → Plugins → upload `shippo-plugin.zip` → set \"Installed by default\" (or assign to a group), and all skills become available to members. (Code execution must be enabled in Organization settings.)\n\nTo build the ZIP locally: `npm run build:app-plugin` (output in `dist/app-plugin/`).\n\n### Shippo account\n\nYou'll need a [Shippo account][api-keys]. Getting rates and validating addresses incur no charge; purchasing a label uses Shippo's discounted carrier rates and charges your account. The Claude Code and Codex plugins authorize per-user via OAuth on first use, so there's no API key to copy.\n\n## How it works\n\nThis plugin bundles two things, with a deliberate division of labor between them:\n\n- **Skills** (this repo): Cross-tool **workflow narrative**: routing decisions (checkout vs single label vs batch), UX gates (\"ask before purchasing a live-mode label\"), CSV ingestion, validation sequencing, test/live mode discipline, response-handling rules. Loaded on activation when the user's request matches a skill's description.\n- **MCP server** ([docs](https://docs.goshippo.com/docs/Guides_general/MCPServer)): Per-tool **semantics**: tool name, parameters, return shape, single-call constraints. Each tool description is terse, one verb phrase, one tool. Workflow guidance is intentionally NOT duplicated here.\n\nThe skills teach the assistant *how* to ship across multiple API calls. The MCP server gives the assistant the *per-call* truth about each tool. The two surfaces are disjoint by design, same precedent Stripe uses (terse `mcp.stripe.com` tool descriptions, rich [`stripe/agents`](https://github.com/stripe/agents) skills): so raw MCP users get accurate per-tool semantics and skill-installed users additionally get the workflow narrative, without contradiction.\n\n## Repo layout\n\n- `skills/`: canonical skill content (9 skills + 11 shared references). **Edit here; everything else flows from here.**\n- `providers/claude/plugin/`: Claude Code plugin distribution. 1:1 mirror of canonical via `scripts/sync.js`.\n- `providers/codex/plugin/`: OpenAI Codex plugin. `skills/` is a 1:1 mirror of canonical via `scripts/sync.js`; `.codex-plugin/plugin.json` + `.mcp.json` (hand-authored) carry the manifest and the OAuth MCP wiring. Cataloged from `.agents/plugins/marketplace.json` at the repo root.\n- `providers/clawhub/skills/shippo/`: ClawHub bundle distribution. The `SKILL.md` is auto-generated from `SKILL.md.template` (hand-curated framing) + canonical skill bodies via `scripts/compose-clawhub-digest.js`. References are auto-synced via `scripts/build-clawhub-bundle.js`.\n- `dist/app-plugin/`: the single `shippo-plugin.zip` for the Claude apps, built from `providers/claude/plugin/` by `scripts/build-app-plugin.js` (not committed; produced on demand and on release).\n- `scripts/`: sync, compose, and build helpers.\n\n## Authoring\n\n```bash\n# 1. Edit canonical content\nvim skills/<skill-name>/SKILL.md\n# (or skills/shippo/references/<name>.md, or providers/clawhub/skills/shippo/SKILL.md.template\n#  if you're changing ClawHub-only framing)\n\n# 2. Sync + verify (one command)\nnpm test\n\n# 3. Commit canonical edits AND synced output together\ngit add -A && git commit -m \"...\"\n```\n\n`npm test` runs all the sync steps (Claude Code + Codex mirrors, ClawHub digest compose, ClawHub references sync) and verifies the result is internally consistent. CI runs the same command. No `npm install` needed, the repo has no third-party dependencies, just scripts.\n\n### Preview your edit\n\n- **Claude Code:** run `claude --plugin-dir ./providers/claude/plugin` from the repo root to launch Claude Code with the local plugin loaded. Edits to `skills/<name>/SKILL.md` are reflected immediately. Skills are namespaced under `/shippo:` (e.g., `/shippo:rate-shopping`).\n- **ClawHub digest:** after `npm test` runs, the rendered output lives at `providers/clawhub/skills/shippo/SKILL.md`: read it directly to see what ClawHub-installed users will get. There's no local-server preview today.\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for the full authoring discipline, including the version-bump rules and the cross-reference phrasing rule for skill content.\n\n## License\n\n[MIT](LICENSE)\n\n[api-keys]: https://apps.goshippo.com/settings/api\n",
  "bytes": 12052,
  "sha": "841f574f895b3d0548288b9808ab7e3b2de781da7877aad2d7255c7fddb09820",
  "repo_slug": "goshippo/ai",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_com_shippo_shippo_mcp_af608f30/readme"
}