hub

Agent Skill

AgentShelf Skill

Publish your AI agents to the registry or initiate agents from it — all from your coding environment. Works with Claude Code, Cursor, Windsurf, GitHub Copilot, and any Agent Skills compatible tool.

updateLast updated: April 7, 2026

Overview

The agentshelf skill provides two core capabilities: publish your agent definitions to AgentShelf, and initiate agents from the registry into your project. It follows the open Agent Skills specification, which means it works across 40+ compatible AI tools.

cloud_upload

Publish

Detect agent files, convert to AgentShelf format, and publish to the registry with a single command.

cloud_download

Initiate

Download an agent by ID, install its skills and MCP servers, and set it up ready to use.

Authenticate via GitHub Device Flow. Required for publishing and private agents.

logout

Logout

Remove the cached authentication token to sign out of AgentShelf.

Commands

One skill, one command — handles publish, initiate, login, and logout:

hub

/agentshelfAll-in-one AgentShelf skill

Publish, initiate, login, and logout — one skill handles everything. Detects your intent automatically.

Or just ask naturally — “publish my agent”, “initiate alice/code-reviewer”, “log in to AgentShelf”, “log out of AgentShelf”.

How It Works

alt_route

Step 1.Choose mode

The skill detects whether you want to publish or initiate. Or specify directly with your request.

radar

Step 2.Publish: Detect & Convert

Scans your project for agent files, analyzes their purpose, and converts them into AgentShelf's format with YAML frontmatter.

cloud_upload

Step 3.Publish: Upload

Authenticates via GitHub, then publishes new agents or updates existing ones with version bumps.

cloud_download

Step 4.Initiate: Download & Parse

Downloads the agent by ID (e.g. alice/code-reviewer) and parses its markdown for skills, MCP servers, and dependencies.

build

Step 5.Initiate: Install & Set Up

Installs all referenced skills and MCP servers, shows required API keys and environment variables, then starts the agent.

Installation

Download the skill and install it for your AI coding tool. Each tool has a different skills directory — pick your tool below for the correct path.

downloadDownload Skill (.zip)

Install Guide

Project-level:.claude/skills/

# Project-level (this project only)
mkdir -p .claude/skills
unzip agentshelf.zip -d .claude/skills/
chmod +x .claude/skills/agentshelf/scripts/*.sh

User-level (all projects):~/.claude/skills/

# User-level (all your projects)
mkdir -p ~/.claude/skills
unzip agentshelf.zip -d ~/.claude/skills/
chmod +x ~/.claude/skills/agentshelf/scripts/*.sh

info

Invoke with /agentshelf or ask naturally (e.g. "publish my agent", "log in to AgentShelf").

Skill Contents

agentshelf/
├── SKILL.md              # Publish & Initiate instructions
├── scripts/
│   ├── detect.sh         # Agent file scanner
│   ├── auth.sh           # GitHub Device Flow auth
│   ├── publish.sh        # API upload/update
│   └── initiate.sh       # Agent downloader
├── references/
│   ├── agent-format.md   # Schema reference
│   └── categories.md     # Valid categories
└── assets/
    └── template.md       # Blank agent template

Publish

The publish flow automatically detects agent files in your project, converts them into AgentShelf's format, and uploads them to the registry.

Quick start

/agentshelf

chat

“Publish my agent to AgentShelf”

chat

“Upload this CLAUDE.md to the AgentShelf registry”

chat

“Update my agent on AgentShelf with a new version”

chat

“Publish all agent files in this project”

Version updates

When you publish an agent that already exists, the skill detects the existing version, asks for a patch, minor, or major bump, and publishes the new version with an optional changelog.

Bulk publish

If your project contains multiple agent files, the skill can publish them all in one run:

Published 3/4 agents:
  code-reviewer (v1.0.0) — /agent/alice/code-reviewer
  data-pipeline (v1.0.0) — /agent/alice/data-pipeline
  api-tester (v1.2.0, updated) — /agent/alice/api-tester
Skipped: 1 (email-helper — user skipped)

Initiate

The initiate flow downloads an agent from the registry and sets it up in your project — installing all referenced skills, MCP servers, and dependencies automatically.

Quick start

/agentshelf

> Initiate alice/code-reviewer

chat

“Initiate alice/code-reviewer”

chat

“Download and set up the agent bob/seo-optimizer”

chat

“Install the agent marketing-pro/cold-email-writer”

What gets installed

extension

Skills

All referenced skills are downloaded from AgentShelf, npm, or GitHub and installed to .agents/skills/.

dns

MCP Servers

MCP server configurations are merged into your .mcp.json with the correct commands and arguments.

key

API Keys & Config

All required environment variables and API keys are identified and presented to you with instructions on where to get them.

package_2

Dependencies

npm packages and CLI tools referenced by the agent are installed or flagged for manual setup.

info

Public agents can be initiated without authentication. For private or shared agents, ask to log in first (the skill handles authentication automatically).

Authentication

The skill uses GitHub Device Flow for authentication — the same approach used by the GitHub CLI. No API keys to manage.

Ask to log in

Say “log in to AgentShelf” or run /agentshelf. A URL and one-time code are displayed.

Authorize in browser

Open the URL, enter the code, and approve the GitHub OAuth prompt.

Token is cached

Saved securely at ~/.agentshelf/token — you won't need to auth again until you ask to log out.

visibility

Public agents can be downloaded and initiated without authentication. Login is only required for publishing and accessing private or shared agents.

Supported Tools

This skill follows the Agent Skills specification and works with any compatible AI coding tool, including:

terminal

Claude Code

Project path: .claude/skills/

Global path: ~/.claude/skills/

Invocation: /agentshelf

edit_note

Cursor

Project path: .agents/skills/

Global path: ~/.agents/skills/

Invocation: Auto-detected from project

air

Windsurf

Project path: .agents/skills/

Global path: ~/.agents/skills/

Invocation: Auto-detected from project

code

GitHub Copilot

Project path: .agents/skills/

Global path: ~/.agents/skills/

Invocation: Auto-detected from project

Plus 40+ other Agent Skills-compatible tools. If your tool supports the .agents/skills/ directory, it will work.

Supported Agent Files

File	Type
CLAUDE.md	Claude Code project instructions
.cursorrules	Cursor AI rules
SKILL.md	Agent Skills format
.github/copilot-instructions.md	GitHub Copilot instructions
.windsurfrules	Windsurf AI rules
*.agent.md	Generic agent definitions
.mcp.json	MCP server configuration
system-prompt.md	System prompt file

Troubleshooting

Error	Cause	Fix
401	Token expired or invalid	Ask to log out, then log in again via `/agentshelf`
404	Agent not found or private without auth	Verify the agent ID; if private, ask to log in first
409	Agent ID or version conflict	Change the ID, or bump the version number
400	Validation error in frontmatter	Check field constraints in the documentation
No files found	No agent files detected in project	Point the skill to your agent file manually, or create one using the web upload