Skip to content

AGENTS.md

Latest commit

 

History

History
136 lines (99 loc) · 4.74 KB

AGENTS.md

File metadata and controls

136 lines (99 loc) · 4.74 KB

AgentHub — Agent Guidelines

This file is for AI agents (Claude Code, Copilot, etc.) working on this repository. It describes the project, its conventions, and how to perform common tasks correctly.

What is this project?

AgentHub is a community-driven plugin marketplace for Claude Code. It is a catalog only — plugin code lives in contributors' own repositories (or npm packages). This repo maintains a registry of plugin references in .claude-plugin/marketplace.json.

Project structure

agenthub/
├── plugins/                  # One JSON file per plugin (the source of truth)
├── scripts/
│   └── build-marketplace.sh  # Aggregates plugins/*.json into .claude-plugin/marketplace.json
├── .github/
│   ├── workflows/
│   │   ├── build-marketplace.yml   # Rebuilds .claude-plugin/marketplace.json on push to main
│   │   └── validate-plugin.yml     # Validates plugin JSON on PRs
│   └── PULL_REQUEST_TEMPLATE/
│       ├── add-plugin.md
│       ├── update-plugin.md
│       └── remove-plugin.md
├── .claude-plugin/marketplace.json          # AUTO-GENERATED — never edit directly
├── CONTRIBUTING.md           # Contribution guidelines for humans
├── README.md                 # User-facing install & usage docs
└── LICENSE                   # MIT

Critical rules

  1. Never edit .claude-plugin/marketplace.json directly. It is auto-generated by scripts/build-marketplace.sh from the files in plugins/. If you need to change the marketplace output, modify the plugin files or the build script.

  2. One plugin = one file. Each plugin is a standalone JSON file in plugins/ named <plugin-name>.json. The filename must match the name field inside the JSON.

  3. Plugin naming conventions:

    • Kebab-case only: my-cool-plugin, not MyCoolPlugin
    • Be descriptive: react-test-generator, not rtg
    • Never use "claude", "anthropic", or "official" in plugin names

  4. Valid categories: development, testing, devops, security, documentation, productivity, data, design, other

  5. Valid tags (optional): skills, agents, commands, hooks, mcp-servers, lsp-servers, integration

Plugin JSON schema

Every file in plugins/ must follow this structure:

{
  "name": "plugin-name",
  "source": { ... },
  "description": "Brief description",
  "version": "1.0.0",
  "author": {
    "username": "author-username"
  },
  "category": "development",
  "license": "MIT",
  "tags": ["skills", "agents"]
}

The license field is required. Use SPDX identifiers (e.g. MIT, Apache-2.0, MIT OR Apache-2.0).

The tags field is optional. It indicates what components the plugin provides.

Source types

GitHub (most common):

"source": { "source": "github", "repo": "owner/repo" }

Git URL (GitLab, Bitbucket, etc.):

"source": { "source": "url", "url": "https://gitlab.com/owner/repo.git" }

Git subdirectory (monorepos):

"source": { "source": "git-subdir", "url": "https://github.com/owner/repo.git", "path": "packages/plugin" }

npm:

"source": { "source": "npm", "package": "@scope/plugin-name" }

All git-based sources optionally accept "ref" (branch/tag) and "sha" (exact commit).

Common tasks

Adding a plugin

  1. Create plugins/<plugin-name>.json with valid plugin JSON
  2. Ensure the filename matches the name field
  3. Ensure all required fields are present: name, source, description, version
  4. Ensure the category is one of the valid categories listed above
  5. Do not touch .claude-plugin/marketplace.json

Updating a plugin

  1. Edit the existing file in plugins/
  2. Do not rename the file unless the plugin name is changing
  3. Do not touch .claude-plugin/marketplace.json

Removing a plugin

  1. Delete the file from plugins/
  2. Do not touch .claude-plugin/marketplace.json

Testing changes locally

./scripts/build-marketplace.sh

This requires jq to be installed. It reads all plugins/*.json files and writes .claude-plugin/marketplace.json. The output should show how many plugins were built.

Validating a plugin file

Check that the JSON is valid and has required fields:

jq empty plugins/<plugin-name>.json && echo "Valid JSON"
jq -r '.name, .description, .version, .source' plugins/<plugin-name>.json

What not to do

  • Do not add plugin source code to this repo — it belongs in the plugin author's own repo
  • Do not edit .claude-plugin/marketplace.json — it is auto-generated
  • Do not add plugins with duplicate names
  • Do not modify the build script unless changing the marketplace structure itself
  • Do not merge PRs that fail the validate-plugin.yml workflow