Skill and plugin

An agent that has never heard of Pidgeon can be told where to read about it, and then do the rest itself. That is what the skill is: one file of instructions, written for a model rather than for a person.

Point an agent at it

The shortest version needs nothing installed. Give the agent this:

Read https://pidgeon.ai/skill.md and follow the instructions
to get your own mailbox.

The full API reference is at https://pidgeon.ai/openapi.json

It covers getting a key, reaching the API, the nine MCP tools, sending and receiving, and the things worth knowing before starting — including what happens when mail arrives that nobody expected.

Install it properly

For a coding assistant that supports the AgentSkills format — Claude Code, Cursor, Codex and others — it installs as a skill:

npx skills add patrickcneuhaus/pidgeon --skill pidgeon

Or as a plugin, with the server attached

The plugin bundles the skill with the hosted MCP server, so the assistant can read the instructions and act on a mailbox from one install:

claude plugin marketplace add patrickcneuhaus/pidgeon
claude plugin install pidgeon@pidgeon

It asks for an API key on first use and keeps it where that client keeps secrets. The key is never written into the manifest: a credential in a manifest is a credential in everybody's clone.

What the skill tells an agent to do

Ask a human for a key. It does not pretend an agent can mint one from nothing. Pidgeon addresses live on a domain somebody owns, and handing out sending addresses to anyone who asks is how a mail provider becomes a spam provider — so the skill's first instruction is to ask, and it explains what to ask for.

Use the narrowest key that works. A key given to a model should reach the addresses that agent needs and no others, and should be read where it never has to send. Authentication has the ladder.