Documentation

Learn how to create and publish agent definitions to the registry.

Overview

An agent definition is a Markdown file with YAML frontmatter. The frontmatter contains structured metadata (name, description, version, etc.) while the Markdown body holds freeform documentation — instructions, usage guides, examples, or any other content that helps users understand what your agent does.

When you upload an agent, the registry parses the YAML frontmatter to extract metadata for search, filtering, and display. The Markdown body is rendered as-is on the agent's detail page.

Markdown Format

Agent definitions use standard Markdown with YAML frontmatter delimited by --- at the top of the file.

---
id: "my-agent-slug"
name: "My Agent Name"
description: "A short description of what this agent does."
version: "1.0.0"
category: "coding"
tags: ["python", "automation"]
license: "MIT"
---

# My Agent Name

Your freeform documentation goes here.
Write instructions, examples, or anything
that helps users understand your agent.

Required Fields

Field	Type	Description
id	string	Lowercase slug (e.g. `cold-email-generator`). Your GitHub username is automatically prepended to form the full ID.
name	string	Display name (3-80 characters).
description	string	Short summary (10-240 characters). Shown in search results and cards.
version	string	SemVer format (e.g. `1.0.0`). Must be bumped for each new published version.
category	string	One of the predefined categories listed below.

Optional Fields

Field	Type	Description
tags	string[]	Up to 20 lowercase tags for discoverability (e.g. `["python", "email"]`).
license	string	SPDX license identifier (e.g. `MIT`,`Apache-2.0`).

Full Example

---
id: "cold-email-generator"
name: "Cold Email Generator"
description: "Writes personalised B2B cold emails with a clear CTA."
version: "1.0.0"
category: "marketing"
tags: ["email", "copywriting", "b2b"]
license: "MIT"
---

# Cold Email Generator

## What this agent does

This agent creates personalised cold outreach emails based on
a target audience and offer description.

## How to use

Provide the agent with details about your target audience,
your product or service, and the desired tone. The agent will
generate a tailored cold email with a compelling subject line
and clear call-to-action.

## Best practices

- Be specific about your target audience
- Include key differentiators of your product
- Specify the desired tone (professional, casual, etc.)

Versioning

Agent versions follow Semantic Versioning (SemVer):

MAJOR

Breaking changes to the agent's behavior or interface.

MINOR

New capabilities added in a backwards-compatible way.

PATCH

Bug fixes or minor improvements.

To publish a new version, go to your agent's detail page and use the "Publish New Version" button. The version number in the updated markdown must be higher than the current version. Each version is stored as an immutable snapshot with an optional changelog.