Releasing Agent Files

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

Required Inputs

Before starting, confirm the user has:

An exported .af file — the agent file to publish
An avatar image — any common format (PNG, JPG, WebP); does not need to be square
Owner ID — GitHub handle with @ prefix (e.g. @letta-ai, @cpfiffer)
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:

.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:

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

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.

releasing-agentfiles