Courier agent skills

Courier Skills is structured guidance AI coding agents follow when building notifications. Install it once. Your agent gets channel-specific delivery rules, reliability patterns, and code examples for the whole Courier platform. Works with Cursor, Claude Code, Codex, Windsurf, Cline, and any tool that supports agent skills.

Installation

Any assistant (recommended)
Claude Code (plugin)
Manual clone

npx skills add trycourier/courier-skills

The plugin self-updates and ships the Courier docs MCP server, so the agent can look things up with no extra setup:

/plugin marketplace add trycourier/courier-skills
/plugin install courier@courier-skills

Run /plugin update courier@courier-skills to pick up changes.

For any tool that reads a skills directory, clone courier-skills on GitHub and copy the skill into your assistant’s skills folder:

git clone https://github.com/trycourier/courier-skills.git /tmp/courier-skills
cp -R /tmp/courier-skills/skills/courier ~/.cursor/skills/   # or ~/.claude/skills/

Agents discover the skill from the name and description frontmatter in SKILL.md. There is exactly one, named courier, and nothing else to configure.

What your agent learns

Category	Coverage
7 Channels	Email, SMS, push, in-app inbox, Slack, Microsoft Teams, WhatsApp. Each with deliverability rules, provider notes, and code examples
5 Transactional Types	Authentication (OTP, password reset), orders, billing, appointments, account notifications. Timing requirements, security rules, and templates
6 Growth Types	Onboarding, adoption, engagement, re-engagement, referral, campaigns. Which Courier primitive each one needs, so frequency capping and digest scheduling are not rebuilt in your own code
20 Cross-Cutting Guides	Multi-channel routing, preferences, reliability, batching, throttling, scheduling, journeys, templates, brands, tenants, audiences, bulk, providers, webhooks, CLI and MCP usage, and reusable patterns

How it works

Agents read a routing file (SKILL.md) first. It points them at only the 1-2 files relevant to the task. Each resource file has the same structure:

Quick Reference at the top with hard rules, common mistakes, and copy-paste templates
Detailed guidance with explanations, examples, and edge cases
Related links to other files

So agents read only what they need, not the entire skill.

Example: agent building an OTP flow

Agent reads SKILL.md, finds the routing table
Routing table says: OTP/2FA -> read transactional.md + sms.md
Agent reads both files and gets: SMS first with email as the fallback, routing.method: "single" so one code never goes out twice, an idempotency key, and a suggested cap of five OTP requests an hour
Agent generates code that follows every constraint

Check that it worked

Skills load silently, so the quickest confirmation is to ask for something the skill has an opinion about:

Add a one-time passcode flow to this project.

With the skill loaded, the agent reaches for SMS first with email as the fallback, routes on a single channel rather than sending to every one, and adds an idempotency key. If it fans the code out to every channel at once, or invents an endpoint, the skill is not being read. If nothing changes, check that the skill landed in the directory your tool actually reads, then start a new session. Most agents pick skills up at session start.

Code examples

The skill generates the send in every language Courier ships an SDK for. A transactional send always carries an idempotency key, so a retry after a network failure returns the original result instead of sending twice:

const { requestId } = await client.send.message({
  message: {
    to: { user_id: 'user_123' },
    template: 'nt_01kx4h2jdafq8bk9aftxak4b40',
    data: { order_id: 'ORD-9042' },
  },
  'Idempotency-Key': 'order-confirmation-ORD-9042',
});

response = client.send.message(
    message={
        "to": {"user_id": "user_123"},
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "data": {"order_id": "ORD-9042"},
    },
    idempotency_key="order-confirmation-ORD-9042",
)

curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-confirmation-ORD-9042" \
  -d '{
    "message": {
      "to": { "user_id": "user_123" },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "data": { "order_id": "ORD-9042" }
    }
  }'

response = courier.send_.message(
  message: {
    to: { user_id: "user_123" },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    data: { order_id: "ORD-9042" }
  },
  idempotency_key: "order-confirmation-ORD-9042"
)

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Data: map[string]any{
			"order_id": "ORD-9042",
		},
	},
	IdempotencyKey: courier.String("order-confirmation-ORD-9042"),
})

SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(JsonValue.from(java.util.Map.of("user_id", "user_123")))
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .data(JsonValue.from(java.util.Map.of("order_id", "ORD-9042")))
        .build())
    .idempotencyKey("order-confirmation-ORD-9042")
    .build();
client.send().message(params);

$response = $client->send->message(
  message: [
    'to' => ['user_id' => 'user_123'],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'data' => ['order_id' => 'ORD-9042'],
  ],
  idempotencyKey: 'order-confirmation-ORD-9042',
);

SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Data = new Dictionary<string, JsonElement>()
        {
            { "order_id", JsonSerializer.SerializeToElement("ORD-9042") },
        },
    },
    IdempotencyKey = "order-confirmation-ORD-9042",
};

await client.Send.Message(parameters);

courier send message \
  --api-key "$COURIER_API_KEY" \
  --idempotency-key "order-confirmation-ORD-9042" \
  --message '{"to":{"user_id":"user_123"},"template":"nt_01kx4h2jdafq8bk9aftxak4b40","data":{"order_id":"ORD-9042"}}'

With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to user_123 with order ORD-9042.

Universal rules

The skill enforces these constraints across all generated code:

Never send promotional content in transactional notifications
Never batch or delay OTP, password reset, or security alerts
Never batch, delay, or fan out a code that is meant to reach one device
Always use idempotency keys for transactional sends
Always express quiet hours as a native delivery window rather than queueing in your own code
Always use method: "single" unless the notification warrants all channels

Get started

Tools

Courier agent skills

Installation

What your agent learns

How it works

Example: agent building an OTP flow

Check that it worked

Code examples

Universal rules

​Installation

​What your agent learns

​How it works

​Example: agent building an OTP flow

​Check that it worked

​Code examples

​Universal rules

Installation

What your agent learns

How it works

Example: agent building an OTP flow

Check that it worked

Code examples

Universal rules