Agent Skills

Nerfmail provides a set of Agent Skills — installable packages that give AI coding agents deep knowledge of the Nerfmail API. When you're building an integration, your agent automatically knows how to call endpoints, verify webhooks, implement the protocol, and use intelligence features.

What are Agent Skills?

Agent Skills are an open standard for extending AI agent capabilities. Each skill is a folder with a SKILL.md file containing instructions your agent loads on demand. They work with Claude Code, Cursor, VS Code Copilot, Gemini CLI, and many more.

Skills use progressive disclosure — your agent sees a one-line description at startup, then loads full instructions only when relevant to your task. This means zero context overhead until you actually need it.

Available Skills

nerfmail-api

Core API integration skill. Covers authentication, error handling, pagination, idempotency, rate limits, and every endpoint group.

Use when: making API calls, setting up accounts, creating mailboxes, issuing API keys, or working with any Nerfmail endpoint.

What your agent learns:

• How to authenticate with API keys (nrfm_{keyId}.{secret} format)
• The standard error response format and all error codes
• Pagination conventions (page, limit query params)
• Idempotency key handling for safe retries
• Rate limit thresholds and Retry-After headers
• All endpoint paths for messages, threads, drafts, labels, search, and policies

nerfmail-email

Email handling from end to end — sending, receiving, threading, risk assessment, and sender management.

Use when: sending email, handling inbound messages, working with threads, managing sender profiles, or implementing reply flows.

What your agent learns:

• How to send email and reply to messages via the API
• Secure reply token system (automatic threading for replies)
• Risk assessment levels and what they mean
• Triage labels for routing decisions
• Suspicious signal types and their severity
• Message status lifecycle (queued → processed → responded → archived)
• Sender profiles and disposition system (neutral/trusted/blocked)
• Suppression list enforcement
• Draft create → edit → send workflow

nerfmail-webhooks

Webhook setup, signature verification, and event handling patterns.

Use when: creating webhook endpoints, verifying signatures, handling events, implementing retry logic, or debugging deliveries.

What your agent learns:

• How to create a webhook and store the secret
• All four webhook events and their payloads
• Signature verification code (Node.js and Python examples)
• The retry schedule (5 attempts with increasing delays)
• Best practices for webhook handlers (respond fast, be idempotent)
• Delivery history and replay for debugging
• Common patterns: filtering by risk level, auto-responding, syncing to a database

nerfmail-agent-protocol

The structured messaging protocol for AI agent-to-mailbox communication.

Use when: building agents that communicate with Nerfmail mailboxes, discovering actions, sending protocol messages, or handling async responses.

What your agent learns:

• How to fetch and parse the discovery document (/.well-known/agent.json)
• Sending messages with explicit actions vs. AI classification
• All message fields and validation rules
• Three response modes: sync (auto-reply), poll, and callback
• Callback signature verification
• Responding to protocol messages with structured data
• Defining custom actions with JSON Schema parameters and response schemas
• The complete integration flow from discovery to response

nerfmail-intelligence

AI-powered features: summaries, extraction, digests, sender analysis, and autopilot.

Use when: working with message summaries, extracting structured data, generating thread digests, analysing senders, or setting up autopilot rules.

What your agent learns:

• Message summary endpoint (cached, 1-3 sentence digests)
• Structured extraction with 6 types (invoice, receipt, meeting, contact, deadline, link) and confidence scores
• Thread digest generation (summary + participants + action items)
• Sender intelligence (relationship type, topics, sentiment)
• Full-text search across messages
• Autopilot policy engine: observe vs. enforce mode, rule conditions, available actions
• How to safely roll out autopilot (observe first, then enforce)

Installation

Claude Code

Download the skills into your project's .claude/skills/ directory:

# From your project root
mkdir -p .claude/skills

# Download individual skills
curl -o .claude/skills/nerfmail-api/SKILL.md \
  --create-dirs \
  https://nerfmail.com/skills/nerfmail-api/SKILL.md

curl -o .claude/skills/nerfmail-email/SKILL.md \
  --create-dirs \
  https://nerfmail.com/skills/nerfmail-email/SKILL.md

curl -o .claude/skills/nerfmail-webhooks/SKILL.md \
  --create-dirs \
  https://nerfmail.com/skills/nerfmail-webhooks/SKILL.md

curl -o .claude/skills/nerfmail-agent-protocol/SKILL.md \
  --create-dirs \
  https://nerfmail.com/skills/nerfmail-agent-protocol/SKILL.md

curl -o .claude/skills/nerfmail-intelligence/SKILL.md \
  --create-dirs \
  https://nerfmail.com/skills/nerfmail-intelligence/SKILL.md

Or install all skills at once:

for skill in nerfmail-api nerfmail-email nerfmail-webhooks nerfmail-agent-protocol nerfmail-intelligence; do
  curl -o .claude/skills/$skill/SKILL.md \
    --create-dirs \
    https://nerfmail.com/skills/$skill/SKILL.md
done

Skills are discovered automatically. Verify with:

What skills are available?

Cursor / VS Code Copilot / Other Agents

The skills follow the Agent Skills open standard. Place the SKILL.md files in whatever location your agent expects. Most agents use .claude/skills/ or a similar directory.

Personal vs. Project Skills

Using Skills

Once installed, skills activate automatically when relevant. Ask your agent to do something Nerfmail-related and it will load the right skill:

• "Send an email via Nerfmail" → loads nerfmail-email
• "Set up a webhook for new messages" → loads nerfmail-webhooks
• "Build an agent that talks to a Nerfmail mailbox" → loads nerfmail-agent-protocol
• "Extract invoice data from this message" → loads nerfmail-intelligence

You can also invoke skills directly:

/nerfmail-api
/nerfmail-webhooks

Writing Custom Skills

If you build a custom integration pattern, you can package it as a skill:

---
name: my-nerfmail-integration
description: Custom Nerfmail integration for [your use case]. Use when [trigger conditions].
---

# My Integration

[Step-by-step instructions for your agent...]

See the Agent Skills specification for the full format reference.