# Skill and plugin

> Point an agent at Pidgeon's own instructions so it can sign itself up, get an address and start sending, without a person reading the docs first.

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:

```text
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:

```sh
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:

```sh
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](https://pidgeon.ai/docs/authentication.md) has the ladder.