# Releasing Agentfiles

> Contributes an agent to the letta-ai/agent-file directory. Use when setting up a new agent (.af file) for publication, including directory creation, avatar processing, file placement, and structure verification. Triggers on requests to release, publish, or contribute an agent file. Use when this capability is needed.

- Skill: `tomevault-io/releasing-agentfiles` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/releasing-agentfiles`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/releasing-agentfiles/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/releasing-agentfiles

---


# Releasing Agent Files

Publish a contributed agent to the `letta-ai/agent-file` repository.

## Required Inputs

Before starting, confirm the user has:

1. **An exported `.af` file** — the agent file to publish
2. **An avatar image** — any common format (PNG, JPG, WebP); does not need to be square
3. **Owner ID** — GitHub handle with `@` prefix (e.g. `@letta-ai`, `@cpfiffer`)
4. **Agent key** — lowercase, hyphen-separated, URL-safe name (e.g. `loop`, `lettabot-builder`)

## Workflow

### 1. Create the agent directory

```
agents/@{owner}/{agent-key}/
```

### 2. Copy and rename the `.af` file

Place it as `{agent-key}.af` in the agent directory. The filename must match the agent key exactly.

### 3. Process the avatar image

Run the bundled script to pad the image to square and convert to webp:

```bash
.skills/releasing-agentfiles/scripts/process-avatar.sh <input-image> agents/@{owner}/{agent-key}/{agent-key}.webp
```

The script:
- Detects dimensions and pads the shorter side using the top-left pixel as background color
- Skips padding if already square
- Converts to webp (quality 90)
- Requires ImageMagick (`brew install imagemagick`)

If the image has a non-uniform background or the top-left pixel isn't representative, manually specify a background color with ImageMagick instead:

```bash
magick input.png -gravity center -background "#1a1a2e" -extent 500x500 -quality 90 output.webp
```

### 4. Add a README (optional but recommended)

Create `README.md` in the agent directory. Good content includes:
- What the agent does
- What makes it special
- How it was trained
- Example interactions
- Tools or integrations it uses

Ask the agent to write its own README if convenient.

### 5. Verify the structure

The final directory must match this layout exactly:

```
agents/@{owner}/{agent-key}/
├── {agent-key}.af        # Required
├── {agent-key}.webp      # Required, square
└── README.md             # Optional
```

Check:
- [ ] Filenames match the agent key exactly
- [ ] `.webp` is square (verify with `sips -g pixelHeight -g pixelWidth` or `magick identify`)
- [ ] `.af` is valid JSON
- [ ] No sensitive data (API keys, personal info) in the `.af` file — see `agents/CONTRIBUTING.md` for sanitization guidance

### 6. Clean up

Remove any working files from the repo root (exported `.af` files, source images, temp files). Only the files inside `agents/@{owner}/{agent-key}/` should remain.

### 7. Commit

```bash
git add agents/@{owner}/{agent-key}/
git commit -m "feat: add @{owner}/{agent-key}"
```

## Reference

For full contribution guidelines including privacy review, sanitization, and PR process, see `agents/CONTRIBUTING.md`.

---
> Source: [letta-ai/agent-file](https://github.com/letta-ai/agent-file) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-22 -->