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:

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

Source: letta-ai/agent-file — distributed by TomeVault.