Shippo

Shippo AI

This repo is the one-stop shop for building AI-powered shipping integrations with Shippo.

It contains:

• 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.
• 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/shippo/): Install via openclaw skills install @shippo/shippo.
• 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.
• Knowledge Pack (ChatGPT and other chat assistants) (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.

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:

1. Discovery: at startup, the agent loads only each skill's name and description, just enough to know when it might be relevant.
2. Activation: when a user prompt matches a skill's description, the agent loads the full SKILL.md body into context.
3. 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 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.

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.

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 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.

Decide, "where do I start?"

Do, "execute this workflow"

Maintain, "upgrade or migrate"

A 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.

The 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.

Install

Claude Code

git clone https://github.com/goshippo/ai.git

claude --plugin-dir ./ai/providers/claude/plugin

Or install from the plugin marketplace:

/plugin marketplace add goshippo/ai

/plugin install shippo@shippo

On first use, run /mcp, select the Shippo server, and sign in to authorize the MCP over OAuth (no API key to copy).

Skills 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.

OpenAI Codex

Codex installs the Shippo plugin (skills + OAuth MCP) from this repo's plugin marketplace:

codex plugin marketplace add goshippo/ai

codex plugin add shippo@shippo # install the "shippo" plugin codex mcp login shippo # authorize the remote MCP over OAuth

See 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/ directory.)

ClawHub

openclaw skills install @shippo/shippo

(Published as @shippo/shippo on the ClawHub registry.)

Claude apps (claude.ai / Desktop / Cowork)

The 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. 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.)

To build the ZIP locally: npm run build:app-plugin (output in dist/app-plugin/).

Shippo account

You'll need a Shippo account. 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.

How it works

This plugin bundles two things, with a deliberate division of labor between them:

• 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.
• MCP server (docs): 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.

The 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 skills): so raw MCP users get accurate per-tool semantics and skill-installed users additionally get the workflow narrative, without contradiction.

Repo layout

• skills/: canonical skill content (9 skills + 11 shared references). Edit here; everything else flows from here.
• providers/claude/plugin/: Claude Code plugin distribution. 1:1 mirror of canonical via scripts/sync.js.
• 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.
• 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.
• 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).
• scripts/: sync, compose, and build helpers.

Authoring

# 1. Edit canonical content

vim skills/ /SKILL.md

(or skills/shippo/references/ .md, or providers/clawhub/skills/shippo/SKILL.md.template

if you're changing ClawHub-only framing)

2. Sync + verify (one command)

npm test

3. Commit canonical edits AND synced output together

git add -A && git commit -m "..."

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.

Preview your edit

• 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/ /SKILL.md are reflected immediately. Skills are namespaced under /shippo: (e.g., /shippo:rate-shopping).
• 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.

See CONTRIBUTING.md for the full authoring discipline, including the version-bump rules and the cross-reference phrasing rule for skill content.

License

MIT