XMTP agent skills

A collection of skills and examples for building XMTP agents using the @xmtp/agent-sdk.

Skills follow the Agent Skills format.

Skills

Installation

npx skills add xmtplabs/xmtp-agent-examples

Skills are structured best practices and patterns for building XMTP agents. Each skill contains a SKILL.md with guidelines and individual rule files with code examples.

Skill	Description	Use when
building-agents	Core SDK setup, events, middleware	Creating new agents, handling messages
handling-commands	Validators, filters, type guards	Implementing commands, validating input
creating-inline-actions	Interactive buttons (XIP-67)	Creating menus, confirmations, selections
handling-attachments	Encrypted file handling	Sending/receiving files and images
handling-transactions	USDC transfers, wallet calls	Token transfers, transaction requests
managing-groups	Group management, permissions	Creating groups, managing members
sending-reactions	Emoji reactions, thinking indicator	Reacting to messages, showing state
resolving-domains	ENS, Farcaster resolution	Resolving mentions, fetching profiles

Examples

Runnable example agents that demonstrate specific capabilities:

Example	Description
xmtp-gm	Simple agent that replies "gm"
xmtp-gpt	GPT-powered responses
xmtp-gated-group	Group gating with passphrase
xmtp-domain-resolver	ENS and Farcaster resolution
xmtp-transactions	USDC transactions
xmtp-smart-wallet	Smart wallet usage
xmtp-attachments	File attachments with Pinata
xmtp-generalstore	Shopping cart with inline actions
xmtp-thinking-reaction	Thinking emoji pattern
xmtp-queue-dual-client	Dual client architecture
xmtp-welcome-message	Welcome messages with buttons

Visit miniapps to explore the latest agents and mini-apps.

Quick start

Run an example

# Clone the repo
git clone https://github.com/xmtplabs/xmtp-agent-examples.git
cd xmtp-agent-examples

# Install packages
yarn

# Generate random XMTP keys
yarn gen:keys

# Run an example
cd examples/xmtp-gm
yarn dev

Environment variables

Create a .env file with:

XMTP_WALLET_KEY=      # Private key for the wallet
XMTP_DB_ENCRYPTION_KEY= # Encryption key for local database
XMTP_ENV=dev          # local, dev, or production

Generate keys

yarn gen:keys

Warning: Running yarn gen:keys will append keys to your existing .env file.

Development

Vibe coding

See the skills directory for AI-assisted development patterns.

Prompt: Create an agent that multiplies numbers by 2

Debug mode

XMTP_FORCE_DEBUG=true
XMTP_FORCE_DEBUG_LEVEL=debug # debug, info, warn, error

Talk to your agent

Test using xmtp.chat, the official playground for agents.

CLI debugging

yarn debug
yarn debug --agent 0x81bddb3d7cd9ccdfaeb117ce19fd77c1433b907d

Local XMTP network

# Start local network
./dev/up

# Update .env
XMTP_ENV=local

# Stop
./dev/down

Revoke installations

yarn revoke <inbox-id> <installations-to-exclude>

Deploy

See Deploy your own agent for production deployment guides.

Community examples

Example	Description
xmtp-gaia	Gaia AI integration
xmtp-groq	Groq AI integration

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT