upload

Agent Skill

Publish Skill

Publish your AI agents directly from your coding environment. Works with Claude Code, Cursor, Windsurf, GitHub Copilot, and any Agent Skills compatible tool.

Overview

The agentshelf-publish skill lets you publish agent definitions to AgentShelf without leaving your AI coding assistant. It follows the open Agent Skills specification, which means it works across 40+ compatible AI tools.

The skill automatically detects agent files in your project (like CLAUDE.md, .cursorrules, or SKILL.md), converts them into the AgentShelf format, authenticates via GitHub, and publishes them to the registry.

Auto-Detect

Finds agent files in your project automatically

transform

Smart Convert

Converts any format to AgentShelf's schema

cloud_upload

One Command

Publish or update with a single slash command

How It Works

radar

Step 1.Detection

The skill scans your project for agent definition files — CLAUDE.md, .cursorrules, SKILL.md, MCP configs, and more.

psychology

Step 2.Analysis

Your AI assistant reads the file and understands the agent's purpose, skills, MCP servers, and capabilities.

swap_horiz

Step 3.Conversion

The content is converted into AgentShelf's format with proper YAML frontmatter. You review and adjust the metadata.

lock_open

Step 4.Authentication

First-time only: authenticate via GitHub Device Flow. Open a URL, enter a code, and you're set.

rocket_launch

Step 5.Publish

The agent is published to AgentShelf. For existing agents, you're prompted for a version bump and changelog.

Installation

Download the skill and place it in the standard .agents/skills/ directory. This path is defined by the Agent Skills spec and supported by all compatible tools.

downloadDownload Skill (.zip)

Quick Install

Project-level (recommended — works with all tools):

# Download and unzip into your project
mkdir -p .agents/skills
unzip agentshelf-publish.zip -d .agents/skills/
chmod +x .agents/skills/agentshelf-publish/scripts/*.sh

User-level (available across all your projects):

# Download and unzip to your global skills directory
mkdir -p ~/.agents/skills
unzip agentshelf-publish.zip -d ~/.agents/skills/
chmod +x ~/.agents/skills/agentshelf-publish/scripts/*.sh

Skill Contents

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

Usage

Once installed, invoke the skill from your AI coding assistant. The skill will guide you through the entire publish flow interactively.

Invoke via slash command

/agentshelf-publish

Or just ask naturally

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 to AgentShelf”

Compatible AI tools auto-activate the skill when your request matches its description — no slash command needed.

Supported Tools

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

terminal

Claude Code

Install path: ~/.claude/skills/

Invocation: /agentshelf-publish

edit_note

Cursor

Install path: .agents/skills/

Invocation: Auto-detected from project

air

Windsurf

Install path: .agents/skills/

Invocation: Auto-detected from project

code

GitHub Copilot

Install 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

Authentication

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

Skill initiates auth

A URL and one-time code are displayed in your terminal.

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

Version Updates

When you publish an agent that already exists on AgentShelf, the skill automatically switches to the update flow:

arrow_forwardDetects the existing agent and shows its current version
arrow_forwardAsks what kind of update: patch (bug fix), minor (new feature), or major (breaking change)
arrow_forwardBumps the version number automatically
arrow_forwardAsks for an optional changelog entry
arrow_forwardPublishes the new version (previous versions are preserved as immutable snapshots)

Bulk Publish

If your project contains multiple agent files, the skill can publish them all in one run. It authenticates once and iterates through each file:

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)

You can review and confirm each agent before it's published, or skip individual ones.

Troubleshooting

Error	Cause	Fix
401	Token expired or invalid	Delete `~/.agentshelf/token` and re-authenticate
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