# Handling Attachments

> File attachment handling for XMTP agents. Use when sending or receiving images, files, or any encrypted remote attachments. Triggers on file upload, image sending, or remote attachment handling.

- Skill: `kbarbel640-del/handling-attachments` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add kbarbel640-del/handling-attachments`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kbarbel640-del/handling-attachments/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: kbarbel640-del (https://skillmd.com/u/kbarbel640-del)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/kbarbel640-del/handling-attachments

---


# XMTP attachments

Handle file attachments using encrypted remote attachments. Files are encrypted locally, uploaded to your storage provider, and sent as a remote attachment message.

## When to apply

Reference these guidelines when:
- Sending files or images from an agent
- Receiving and downloading attachments
- Implementing custom upload storage
- Working with encrypted file transfers

## Rule categories by priority

| Priority | Category | Impact | Prefix |
|----------|----------|--------|--------|
| 1 | Send | CRITICAL | `send-` |
| 2 | Receive | CRITICAL | `receive-` |
| 3 | Upload | HIGH | `upload-` |

## Quick reference

### Send (CRITICAL)
- `send-remote-attachment` - Send encrypted file attachments

### Receive (CRITICAL)
- `receive-attachment` - Download and decrypt attachments

### Upload (HIGH)
- `upload-callback` - Implement custom upload storage (Pinata, S3, etc.)

## Quick start

```typescript
import { type AttachmentUploadCallback } from "@xmtp/agent-sdk/util";

// Send an attachment
const file = new File(["Hello, World!"], "hello.txt", { type: "text/plain" });
await ctx.conversation.sendRemoteAttachment(file, uploadCallback);

// Receive an attachment
agent.on("attachment", async (ctx) => {
  const attachment = await downloadRemoteAttachment(ctx.message.content, agent);
  console.log(`Received: ${attachment.filename}`);
});
```

## How to use

Read individual rule files for detailed explanations:

```
rules/send-remote-attachment.md
rules/receive-attachment.md
rules/upload-callback.md
```