Contributing to Claude Code Plugins

Contributing to Claude Code Plugins

Thank you for your interest in contributing! This marketplace thrives on community contributions. Whether you're submitting a plugin, improving documentation, or reporting bugs, your help makes this resource better for everyone.

Ways to Contribute

• Submit new plugins - Share your creations with the community
• Improve existing plugins - Bug fixes, enhancements, documentation
• Write documentation - Help others understand plugins
• Report bugs - Help us identify and fix issues
• Suggest features - Ideas for improving the marketplace
• Review pull requests - Help maintain quality standards

Submitting a Plugin

Before You Start

Make sure your plugin:

• Solves a real problem or provides clear value
• Is well-documented with examples
• Has been tested thoroughly
• Follows security best practices
• Doesn't duplicate existing plugins (unless significantly different)

Plugin Requirements

Your plugin MUST have:

1. Valid .claude-plugin/plugin.json

   • All required fields filled in
   • Valid JSON syntax (test with jq)
   • Accurate version number (semantic versioning)

2. Comprehensive README.md

   • What the plugin does
   • Installation instructions
   • Usage examples with code blocks
   • Requirements (dependencies, tools needed)
   • Files explanation
   • License information

3. LICENSE file

   • MIT or Apache-2.0 recommended
   • Must be compatible with marketplace license

4. Working functionality

   • Tested locally before submission
   • All commands work as documented
   • Hooks trigger correctly
   • Agents activate appropriately

5. Security compliance

   • No hardcoded secrets, API keys, or credentials
   • Use environment variables for sensitive data
   • Scripts validate inputs
   • No destructive operations without confirmation

6. Proper permissions

   • All shell scripts are executable: chmod +x script.sh
   • Appropriate file permissions

Submission Process

1. Fork the Repository

# Fork on GitHub, then clone your fork
git clone https://github.com/YOUR-USERNAME/claude-code-plugins.git
cd claude-code-plugins

2. Create Your Plugin

# Option A: Use a template
cp -r templates/command-plugin plugins/community/my-plugin

# Option B: Start from scratch
mkdir -p plugins/community/my-plugin/.claude-plugin
mkdir -p plugins/community/my-plugin/commands  # or agents, hooks, scripts

3. Develop Your Plugin

• Create .claude-plugin/plugin.json with accurate metadata
• Add your commands, agents, hooks, or MCP servers
• Write comprehensive README.md
• Add LICENSE file
• Make scripts executable

4. Test Locally

# Create test marketplace
mkdir -p ~/test-marketplace/.claude-plugin

# Create marketplace.json
cat > ~/test-marketplace/.claude-plugin/marketplace.json << 'EOF'
{
  "name": "test",
  "owner": {"name": "Test"},
  "plugins": [{
    "name": "my-plugin",
    "source": "/absolute/path/to/plugins/community/my-plugin"
  }]
}
EOF

# Add to Claude Code
/plugin marketplace add ~/test-marketplace

# Install and test
/plugin install my-plugin@test

# Test all functionality!

5. Update Marketplace Catalog

Edit .claude-plugin/marketplace.extended.json and add your plugin:

{
  "name": "my-plugin",
  "source": "./plugins/community/my-plugin",
  "description": "Clear, concise description of what it does",
  "version": "1.0.0",
  "category": "productivity",
  "keywords": ["relevant", "searchable", "keywords"],
  "author": {
    "name": "Your Name",
    "email": "[email protected]",
    "url": "https://github.com/yourusername"
  }
}

# Regenerate the CLI-facing marketplace catalog
pnpm run sync-marketplace  # or: npm run sync-marketplace

6. Create Pull Request

# Create feature branch
git checkout -b add-my-plugin

# Add your changes
git add plugins/community/my-plugin/
git add .claude-plugin/marketplace.extended.json .claude-plugin/marketplace.json

# Commit with clear message
git commit -m "Add my-plugin: Brief description of what it does"

# Push to your fork
git push origin add-my-plugin

Then open a pull request on GitHub using our template.

Plugin Categories

Choose the most appropriate category:

• productivity - Workflow optimization, automation, efficiency tools
• security - Security analysis, vulnerability scanning, compliance
• testing - Test automation, QA tools, test generation
• deployment - CI/CD, deployment automation, infrastructure
• documentation - Docs generation, API documentation, code comments
• analysis - Code analysis, metrics, quality checking
• integration - External service integrations, API connections
• ai - AI/ML specific tooling, model operations
• example - Educational and tutorial plugins
• other - Doesn't fit above categories (specify in description)

Naming Conventions

Plugin Names:

• Use kebab-case: my-awesome-plugin
• Be descriptive and clear
• Avoid generic names: tool, helper, utils
• Check for existing plugins with similar names

Files:

• Commands: commands/command-name.md
• Agents: agents/agent-name.md
• Scripts: scripts/descriptive-name.sh

Version Numbering

Use Semantic Versioning:

• Major (1.0.0): Breaking changes, incompatible updates
• Minor (1.1.0): New features, backward compatible
• Patch (1.1.1): Bug fixes, backward compatible

Start at 1.0.0 for initial release.

Reporting Bugs

Found a bug? Please report it!

1. Search existing issues - It might already be reported
2. Create a new issue using the bug report template
3. Include details:
   • Plugin name and version
   • Claude Code version (claude --version)
   • Steps to reproduce
   • Expected vs actual behavior
   • Error messages or logs

Improving Documentation

Documentation improvements are always welcome:

• Fix typos or clarify confusing sections
• Add more examples
• Improve formatting
• Translate to other languages (coming soon)

Submit changes via pull request.

Code Review Process

All submissions go through review:

What We Check

• Functionality - Does it work as described?
• Code quality - Is the code clean and well-organized?
• Security - Any security concerns?
• Documentation - Is it well-documented?
• Testing - Has it been tested?
• Style - Does it follow conventions?

Review Timeline

• Initial review: Within 7 days
• Feedback provided: Within 14 days
• Merge after approval: 1-3 days

If Changes Are Requested

• Address feedback in your PR
• Push updates to your branch
• Request re-review when ready

Quality Standards

Code Quality

• Clear and readable - Others should understand your code
• Well-commented - Explain complex logic
• Error handling - Handle edge cases gracefully
• No warnings - Code should run without warnings

Documentation Quality

• Clear installation steps - Anyone should be able to install
• Working examples - Examples should be copy-paste ready
• Accurate information - No outdated or incorrect info
• Proper formatting - Use markdown correctly

Security Standards

• No secrets in code - Use environment variables
• Input validation - Validate all user inputs
• Principle of least privilege - Request minimal permissions
• Dependencies - Keep dependencies minimal and updated

Style Guidelines

Markdown Style

# Headers use sentence case

## Use descriptive headings

**Bold** for emphasis, *italic* for terms

`code` for commands and file names

\`\`\`language
code blocks with language specified
\`\`\`

JSON Style

{
  "useTwoSpaces": true,
  "quotesDouble": true,
  "trailingCommas": false,
  "sortKeys": false
}

Bash Script Style

#!/bin/bash
# Clear comment at top

# Use descriptive variable names
file_path="/path/to/file"

# Check for errors
if [[ ! -f "$file_path" ]]; then
  echo "Error: File not found"
  exit 1
fi

# Use functions for complex logic
function process_file() {
  local file="$1"
  # Processing logic
}

Community Guidelines

Be Respectful

• Treat everyone with respect and kindness
• Welcome newcomers and help them learn
• Provide constructive feedback
• Assume good intentions

Be Collaborative

• Share knowledge and help others
• Give credit where credit is due
• Be open to feedback on your work
• Celebrate others' contributions

Be Professional

• Keep discussions on-topic
• Avoid inflammatory language
• Respect differing opinions
• Follow the code of conduct

Getting Help

Need help contributing?

• ** Discord**: Claude Developers
• ** Discussions**: GitHub Discussions
• ** Email**: [email protected]

Recognition

Contributors are recognized in several ways:

• README credits - All contributors listed in main README
• Plugin authorship - You're credited as author in plugin.json
• Community highlights - Outstanding contributions featured
• Maintainer status - Active contributors may become maintainers

Contributor Spotlight

• @cdnsteve — Added the featured Sugar plugin (autonomous AI development)
  • PR: https://github.com/jeremylongshore/claude-code-plugins/pull/8
  • Repo: https://github.com/cdnsteve/sugar

License

By contributing, you agree that your contributions will be licensed under the MIT License.

Quick Checklist

Before submitting, verify:

• Plugin tested locally and working
• README.md is comprehensive with examples
• LICENSE file included
• plugin.json is valid JSON
• All scripts are executable (chmod +x)
• No hardcoded secrets
• Marketplace.json updated
• Branch is up-to-date with main
• Commit messages are clear
• PR uses the template

Thank you for contributing to Claude Code Plugins!

Your contributions help build a vibrant ecosystem that benefits the entire community.

Submit a Plugin | Report a Bug | Join Discord