Documentation

Everything you need to create, publish, and manage AI agent definitions on Agent Shelf.

updateLast updated: April 6, 2026

Overview

Agent Shelf is an open registry where developers publish, discover, and download AI agent definitions. An agent definition is a Markdown file with YAML frontmatter — the frontmatter contains structured metadata (name, description, version, category) while the Markdown body holds freeform instructions, usage guides, and documentation.

When you upload an agent, the registry parses the YAML frontmatter for search, filtering, and display. The Markdown body is rendered on the agent's detail page. Each published version is stored as an immutable snapshot, so users can always access previous versions.

You can publish agents three ways: through the web interface, via the publish skill from your AI coding tool, or through the REST API with a bearer token. All methods require a GitHub account for authentication.

Markdown Format

Agent definitions use standard Markdown with YAML frontmatter delimited by --- at the top of the file. The frontmatter is validated against a strict schema — any extra fields are allowed (for custom extensions) but the required fields must be present.

---
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 matching `[a-z0-9][a-z0-9._-]{1,63}` (e.g. `cold-email-generator`). Your GitHub username is automatically prepended to form the full agent ID (e.g. `yourname/cold-email-generator`).
name	string	Display name (3–80 characters).
description	string	Short summary (10–240 characters). Shown in search results and agent cards.
version	string	Semantic Versioning format (e.g. `1.0.0`). Must be bumped for each new published version. Pre-release suffixes like `1.0.0-beta.1` are supported.
category	string	One of the 14 predefined categories listed below.

Optional Fields

Field	Type	Description
tags	string[]	Up to 20 lowercase tags for discoverability. Each tag must match `[a-z0-9][a-z0-9_-]{0,31}` (e.g. `["python", "email", "b2b"]`).
license	string	SPDX license identifier (e.g. `MIT`, `Apache-2.0`). 2–120 characters.

Additional custom fields (e.g. x-homepage) are allowed in the frontmatter and stored with the agent metadata.

Full Example

Here's a complete agent definition showing frontmatter, persona, workflow, output format, rules, and tool references:

---
id: "code-reviewer"
name: "Code Reviewer"
description: "Reviews pull requests for bugs, security issues, and performance problems. Provides actionable inline feedback with severity levels."
version: "1.0.0"
category: "coding"
tags: ["code-review", "pull-request", "quality", "security"]
license: "MIT"
---

# Code Reviewer

You are an expert code reviewer with deep knowledge of software
engineering best practices, security patterns, and performance
optimization.

## What this agent does

You review code changes (diffs, pull requests, or full files)
and provide structured, actionable feedback. You catch bugs
before they ship, identify security vulnerabilities, and flag
performance regressions.

You focus on what matters — logic errors, edge cases, race
conditions, and architectural concerns that automated tools miss.

## Your review process

1. **Understand context** — Read the PR description and
   surrounding code to understand intent
2. **Check correctness** — Verify logic handles all edge
   cases and error paths
3. **Assess security** — Look for injection vulnerabilities,
   auth bypasses, and data exposure
4. **Evaluate performance** — Identify N+1 queries, memory
   leaks, and algorithmic inefficiency
5. **Provide feedback** — Give specific, line-referenced
   suggestions with code examples

## Review output format

For each issue found, provide:
- **Severity**: Critical / Warning / Suggestion / Nitpick
- **Location**: File and line reference
- **Issue**: Clear description of the problem
- **Fix**: Specific suggestion or code example

## Rules

- Always explain *why* something is a problem, not just
  *what* to change
- Distinguish between must-fix issues and nice-to-have
  suggestions
- Acknowledge good patterns — reviews should be encouraging,
  not just critical
- Consider the project's existing conventions over general
  best practices

## Skills and tools

### MCP Servers

Add to your `.mcp.json` to enhance this agent:

```json
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp"]
    },
    "docfork": {
      "command": "npx",
      "args": ["-y", "docfork"]
    }
  }
}
```

- **Playwright MCP** — Verify UI changes with browser-based
  checks.
- **Docfork MCP** — Reference docs for 9,000+ libraries.

### Agent Skills

Install into `.claude/skills/` (Claude Code) or
`.agents/skills/` (Cursor, Windsurf):

- **webapp-testing** — End-to-end web testing.

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 — or push an updated Markdown file via the publish skill or API. The version number must be higher than the current version. Each version is stored as an immutable snapshot with an optional changelog message.

Publishing

There are three ways to publish agents to Agent Shelf. All require a GitHub account.

cloud_upload

Web Upload

Sign in with GitHub, go to Upload Agent, and paste or upload your Markdown file. The registry validates the frontmatter, extracts metadata, and publishes the agent immediately.

terminal

Publish Skill

The publish skill lets you publish agents directly from your AI coding tool. It detects agent files in your project (CLAUDE.md, .cursorrules, SKILL.md, etc.), converts them to the Agent Shelf format, authenticates via GitHub Device Flow, and publishes — all without leaving your editor. Works with Claude Code, Cursor, Windsurf, GitHub Copilot, and 40+ compatible tools.

api

REST API

Use the API to create and update agents programmatically. Authenticate with a bearer token obtained via the Device Flow, then send the Markdown content as a POST or PUT request. See the API Reference below.

Sharing & Access Control

By default, only the agent owner can edit or unpublish an agent. You can grant access to other GitHub users from the agent's detail page using the sharing panel.

Permission	Can View	Can Publish New Version	Can Unpublish / Delete
Owner	Yes	Yes	Yes
Edit	Yes	Yes	No
View	Yes	No	No

Unpublished agents are only visible to the owner and users with explicit view or edit access. Published agents are visible to everyone.

MCP Server

Agent Shelf exposes a Model Context Protocol (MCP) server that lets AI tools search, browse, and download agents directly. Two deployment modes are available:

Remote (hosted)

Connect to https://www.agentshelf.dev/api/mcp using streamable HTTP transport. No installation required.

Local (stdio)

Download and run the standalone MCP server package locally via stdio transport. Useful for offline or air-gapped environments.

Both modes expose the same 5 tools: search_agents, get_agent, list_categories, get_featured, and download_agent. See the MCP Server page for full setup instructions.

API Reference

All API endpoints are under https://www.agentshelf.dev/api/. Public endpoints require no authentication. Write endpoints require either a session cookie (web) or a Bearer token (CLI/API).

Authentication

To get an API token, use the GitHub Device Flow:

# 1. Initiate device flow
curl -X POST https://www.agentshelf.dev/api/auth/device

# Response: { "verification_uri", "user_code", "device_code", "interval" }
# 2. Open the verification_uri and enter the user_code

# 3. Poll for token
curl -X POST https://www.agentshelf.dev/api/auth/device/token \
  -H "Content-Type: application/json" \
  -d '{"device_code": "<device_code>"}'

# Response: { "token": "as_..." }

Include the token in subsequent requests: Authorization: Bearer as_...

Endpoints

Method	Path	Auth	Description
GET	/api/agents	None	List agents. Supports `search`, `category`, `tag`, `sort`, `dir`, `limit`, `skip` params.
POST	/api/agents	Bearer / Session	Create a new agent. Send Markdown content in the request body.
GET	/api/agents/:user/:name	None	Get full agent details including versions and access level.
PUT	/api/agents/:user/:name	Bearer / Session	Publish a new version. Rejects duplicate version numbers.
PATCH	/api/agents/:user/:name	Session (owner)	Toggle published/unpublished status.
DELETE	/api/agents/:user/:name	Session (owner)	Delete an agent and all its comments.
GET	/api/agents/:user/:name/download	None	Download raw Markdown content. Increments download counter.