awesome-claude-plugins: Instructions file for Claude Code

GitHub Copilot Instructions for Awesome Claude Plugins

This repository is a curated marketplace for Claude plugins, following the Claude Plugin Marketplace specification.

Repository Purpose

This is a plugin marketplace that provides a centralized location to discover and share Claude plugins. The repository contains:

• A marketplace metadata file (marketplace.json)
• Plugin definitions in the plugins/ directory
• A plugin template for creating new plugins
• Validation scripts and CI/CD workflows

Plugin Structure

All plugins must follow this exact directory structure:

plugins/your-plugin-name/
├── .claude-plugin/         # Plugin configuration directory (required)
│   └── plugin.json         # Plugin metadata in JSON format (required)
├── hooks/                  # Lifecycle hooks directory (required)
├── agents/                 # Agent definitions directory (required)
└── commands/               # Custom commands directory (required)

Plugin Metadata Schema

The .claude-plugin/plugin.json file must contain these required fields:

{
  "name": "plugin-name",
  "version": "1.0.0",
  "description": "Clear description of what the plugin does",
  "author": {
    "name": "Author Name",
    "email": "[email protected]"
  }
}

Naming Conventions

Plugin Names

• Use lowercase letters only
• Separate words with hyphens (kebab-case)
• Be descriptive but concise
• Avoid special characters
• Examples: weather-forecast, code-formatter, task-manager

Directory Names

• Plugin directory name must match the name field in plugin.json
• Example: If name is "example-calculator", directory must be plugins/example-calculator/

Validation Requirements

Before Any Changes

Always run the validation script before making changes:

./validate-plugins.sh

Plugin Validation Checks

The validation script checks for:

• Valid JSON syntax in plugin.json
• Presence of all required fields (name, version, description, author)
• Semantic versioning format (X.Y.Z)
• Directory name matching plugin name
• Presence of required subdirectories (hooks/, agents/, commands/)