Getting Started with Agent Shelf: Find, Download, and Use AI Agents

What you'll learn

By the end of this tutorial, you'll know how to:

• Browse and search the Agent Shelf registry
• Download an agent into your AI coding tool
• Use the MCP server for in-tool discovery
• Publish your own agent to the registry

No coding experience is required to use agents. If you can type a prompt, you can use Agent Shelf.

What is Agent Shelf?

Agent Shelf is a free, open registry of AI agents defined as Markdown files. Each agent is a reusable set of instructions that gives your AI coding tool a specialized skill — code review, SEO content writing, DevOps automation, and more.

Agents work across tools. The same agent file works in Claude Code, Cursor, Windsurf, GitHub Copilot, and any tool that supports the Agent Skills specification or Model Context Protocol.

Step 1: Browse the registry

Head to the Agent Shelf homepage and you'll see the full agent library. You can:

• Search by keyword — try "code review" or "marketing"
• Filter by category — 14 categories from Coding to Finance
• Filter by tag — narrow down to specific use cases
• Sort by most downloaded, most liked, newest, or alphabetical

Each agent card shows the agent name, description, category, author, and download/like counts so you can quickly spot popular, well-tested agents.

Step 2: Pick an agent

Click any agent card to see its full detail page. Here you'll find:

• Overview — the agent's full instructions rendered from Markdown
• Raw Markdown — the exact file you'll download
• Versions — every published version with changelogs
• Comments — community feedback and discussion
• Specs sidebar — category, version, license, tags, publish date

Read the overview to understand what the agent does, how it works, and what tools or MCP servers it recommends.

Step 3: Download the agent

You have three ways to get an agent into your project:

Option A: Copy the Markdown

Click Copy Markdown on the agent detail page. Paste the content into a file in your project:

# For Claude Code
.claude/agents/agent-name.md

# For Cursor, Windsurf, Copilot (Agent Skills spec)
.agents/agents/agent-name.md

This is the simplest approach — one file, no installation.

Option B: Download the .md file

Click Download .md to get the Markdown file directly. Move it into your project's agent directory.

Option C: Use the Initiate command (recommended)

If you have the AgentShelf skill installed, run this in your AI coding tool:

/agentshelf Initiate username/agent-name

This is the best option because Initiate does more than copy the file. It reads the agent's Markdown, detects any MCP servers or skills it references, and installs everything automatically. One command sets up the agent, its tools, and its dependencies.

Step 4: Use the agent

Once the agent file is in your project, your AI coding tool picks it up automatically. How you invoke it depends on your tool:

Claude Code — mention the agent's purpose naturally: "Review this pull request" if you have a code review agent. Claude Code reads agents from .claude/agents/ and applies them contextually.

Cursor / Windsurf / Copilot — these tools discover agents from .agents/agents/ via the Agent Skills spec. Reference the agent in your prompt or let the tool match it to your request.

The agent's Markdown body contains all the instructions — the persona, workflow, rules, and output format. Your AI tool reads these and behaves accordingly. You don't need to configure anything beyond placing the file.

Step 5: Set up the MCP server (optional)

The MCP server lets your AI tool search and discover agents from Agent Shelf without leaving your IDE. Instead of browsing the website, you ask your tool directly: "Find me a DevOps agent" or "What's the most popular code review agent?"

Add this to your MCP configuration:

{
  "mcpServers": {
    "agentshelf": {
      "type": "http",
      "url": "https://www.agentshelf.dev/api/mcp"
    }
  }
}

For Claude Code, add this to .mcp.json in your project root or home directory. For other tools, see the MCP Server setup guide.

Once connected, your tool has access to five MCP tools: search_agents, get_agent, download_agent, list_categories, and get_featured.

Step 6: Publish your own agent

Have a useful system prompt or workflow? Turn it into an agent and share it with the community.

Create the Markdown file

An agent is a Markdown file with YAML frontmatter:

---
id: "my-agent"
name: "My Agent"
description: "One sentence describing what this agent does."
version: "1.0.0"
category: "coding"
tags: ["example", "tutorial"]
---

# My Agent

You are an expert at...

## What this agent does

## Your workflow

## Rules

Five frontmatter fields are required: id, name, description, version, and category. The Markdown body is freeform — write whatever instructions your agent needs.

For the full format reference, see the documentation.

Publish via the website

Go to Upload Agent, paste your Markdown or upload the .md file, choose public or private visibility, and submit.

Publish via the skill

If you have the AgentShelf skill installed, just tell your AI tool:

/agentshelf Publish my agent

The skill detects agent files in your project, validates the format, authenticates with GitHub, and publishes to the registry. No browser needed.

Versioning

Every publish creates an immutable version snapshot. Bump the version field in your frontmatter (following semver) before publishing updates. Users can pin to a specific version or always get the latest.

What to do next

• Browse agents — explore the full registry and download agents for your workflow
• Install the skill — set up the AgentShelf skill for publishing and initiating from your tool
• Connect via MCP — add the MCP server for in-tool agent discovery
• Read the docs — see the full agent definition format and API reference
• Learn agent design — read How to Write Effective Agent Definitions for best practices