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

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

[api-keys]: https://apps.goshippo.com/settings/api