claude-plugins/CONTRIBUTING.md

Contributing to Claude Skills Marketplace

Thank you for contributing! This guide helps you add plugins, skills, and improvements to the marketplace.

Types of Contributions

1. Add skills to existing plugins - Extend claude-code or claude-skills
2. Create new plugins - Package related skills together
3. Improve existing skills - Refine content, fix bugs, add examples
4. Update documentation - Improve guides and READMEs

Before You Start

1. Use the claude-skills plugin - Get guidance on skill creation
2. Review existing plugins - Check claude-code and claude-skills-plugin
3. Test thoroughly - See TESTING.md

Adding a Skill to an Existing Plugin

Option 1: Add to claude-code Plugin

Add Claude Code-specific skills (features, tools, workflows):

# 1. Create skill directory
cd claude-code/skills
mkdir my-claude-code-skill

# 2. Create SKILL.md
cat > my-claude-code-skill/SKILL.md << 'EOF'
---
name: My Claude Code Feature
description: [Specific description with trigger scenarios]
---

# Content here
EOF

# 3. Update plugin README
vim claude-code/README.md
# Add your skill to the "What's Included" section

Best for:

• Claude Code features (like our existing 5 skills)
• Development workflows
• Tool integrations

Option 2: Add to claude-skills Plugin

Add skill-creation guidance (templates, patterns, best practices):

# 1. Create skill directory
cd claude-skills-plugin/skills
mkdir my-skill-pattern

# 2. Create SKILL.md
# Follow claude-skills format (see existing skill)

# 3. Update plugin README

Best for:

• New skill templates
• Skill-creation patterns
• Meta-guidance on skills

Creating a New Plugin

For a collection of related skills that don't fit existing plugins:

1. Create Plugin Structure

# Create plugin directory
mkdir my-plugin

# Create required directories
mkdir -p my-plugin/.claude-plugin
mkdir -p my-plugin/skills

# Optional: commands, agents, hooks
mkdir -p my-plugin/commands
mkdir -p my-plugin/agents
mkdir -p my-plugin/hooks

2. Create plugin.json

cat > my-plugin/.claude-plugin/plugin.json << 'EOF'
{
  "name": "my-plugin",
  "description": "Clear description of plugin purpose",
  "version": "1.0.0",
  "author": {
    "name": "Your Name",
    "email": "you@example.com"
  },
  "keywords": [
    "keyword1",
    "keyword2"
  ]
}
EOF

Required fields:

• name - Lowercase, kebab-case identifier
• description - Clear, concise purpose
• version - Semantic versioning (1.0.0)
• author.name - Creator name

Optional fields:

• author.email - Contact email
• author.url - Website or profile
• repository - Git repository info
• license - License identifier
• keywords - Search/discovery terms

3. Add Skills to Plugin

# Create skill directory
mkdir my-plugin/skills/my-skill

# Create SKILL.md with frontmatter
cat > my-plugin/skills/my-skill/SKILL.md << 'EOF'
---
name: Skill Name
description: [Specific description]
---

# Skill content
EOF

4. Create Plugin README

cat > my-plugin/README.md << 'EOF'
# My Plugin

Brief description.

## What's Included

List of skills/features

## Installation

```bash
/plugin install my-plugin@claude-skills

Usage

Examples of how to use

[More sections...] EOF

### 5. Update Marketplace Manifest

```bash
# Edit .claude-plugin/marketplace.json
vim .claude-plugin/marketplace.json

Add your plugin:

{
  "plugins": [
    {
      "name": "my-plugin",
      "source": "./my-plugin",
      "description": "Brief plugin description"
    }
  ]
}

6. Test Plugin Installation

# Test local installation
/plugin install /path/to/Skills/my-plugin@local

# Verify skills load
# Try triggering scenarios

Skill Creation Guidelines

Required: SKILL.md Structure

---
name: Skill Name (max 64 chars)
description: Specific description with triggers (max 1024 chars)
---

# Skill Name

## When to Use This Skill

Use this skill when:
- [Primary scenario]
- [Secondary scenario]

Do NOT use this skill for:
- [Confusion case]

## Quick Start

[Minimal example]

## Core Workflows

[Step-by-step guides]

## Examples

[Concrete examples]

Writing Effective Descriptions

Template:

[Action] [domain/task] [with/for] [capabilities].
Use when [trigger scenario].
[Optional: PROACTIVELY/MUST BE USED if needed]

Good Examples:

# Specific, clear triggers
description: Create and structure Claude Code plugins with commands, agents, skills, hooks, and MCP servers. Use when building plugins for Claude Code, setting up plugin structure, or configuring plugin manifests.

# Domain-specific
description: Optimize and troubleshoot Claude Code memory files (CLAUDE.md) for efficiency, token management, and team collaboration. Use when memory isn't loading, context is bloated, or organizing memory hierarchy.

Bad Examples:

# Too vague
description: Helps with development

# No triggers
description: Python tools and utilities

Progressive Disclosure

Layer 1: Metadata (100 tokens)

• Skill name and description in frontmatter
• Triggers skill selection

Layer 2: SKILL.md (2000-5000 tokens)

• Core workflows and common examples
• Loaded when skill activates

Layer 3: Additional Files (on-demand)

• Detailed docs in separate .md files
• Scripts, templates, references
• Loaded only when needed

Content Best Practices

DO:

• Be specific, not vague
• Use bullet points, not paragraphs
• Include concrete, working examples
• Provide step-by-step workflows
• Add troubleshooting sections
• Test trigger scenarios

DON'T:

• Include sensitive data (API keys, credentials)
• Use generic advice ("write good code")
• Create novel-length content
• Duplicate information
• Skip testing

Quality Checklist

Before submitting:

Metadata

• Name ≤ 64 characters
• Description ≤ 1024 characters
• Description includes specific triggers
• YAML frontmatter is valid

Content

• "When to Use This Skill" section present
• At least one concrete example
• Examples are runnable/testable
• File references are accurate
• No sensitive data hardcoded

Testing

• Skill triggers on target scenarios
• Doesn't trigger on unrelated scenarios
• Examples work as documented
• No conflicts with existing skills

Documentation

• Plugin README updated
• Marketplace manifest updated (if new plugin)
• Clear installation instructions
• Usage examples provided

Testing Your Contribution

See TESTING.md for:

• Trigger accuracy testing
• Content quality validation
• Token efficiency measurement
• Team collaboration testing

Quick test:

# 1. Install locally
/plugin install /path/to/your-plugin@local

# 2. Test trigger scenarios
# Ask questions that should trigger the skill

# 3. Test exclusion scenarios
# Ask questions that should NOT trigger

# 4. Verify quality
# Review Claude's responses for accuracy

Submission Process

For Small Changes (Skills to Existing Plugins)

1. Create skill in appropriate plugin
2. Update plugin README
3. Test locally
4. Submit PR with:
   • Skill files
   • Updated README
   • Test results

For New Plugins

1. Create complete plugin structure
2. Update marketplace.json
3. Create plugin README
4. Test installation and usage
5. Submit PR with:
   • Full plugin directory
   • Updated marketplace.json
   • Documentation
   • Test results

Common Patterns

Plugin Organization

my-plugin/
├── .claude-plugin/
│   └── plugin.json
├── skills/                  # Related skills grouped together
│   ├── skill-1/
│   ├── skill-2/
│   └── skill-3/
├── commands/                # Optional: slash commands
├── agents/                  # Optional: subagent configs
├── hooks/                   # Optional: automation hooks
└── README.md

Skill Naming Conventions

For Claude Code features:

• claude-code-[feature] (e.g., claude-code-plugins)

For domain-specific:

• [domain]-[purpose] (e.g., python-testing, api-documentation)

For meta/general:

• [category]-[action] (e.g., skill-creator, code-reviewer)

Version Bumping

Follow semantic versioning:

{
  "version": "1.2.3"
}

• Major (1.x.x): Breaking changes
• Minor (x.2.x): New features, backward compatible
• Patch (x.x.3): Bug fixes

Update version in plugin.json when:

• Adding new skills → Minor
• Changing skill structure → Major
• Fixing bugs → Patch

Example: Adding a Skill

Scenario: Add "claude-code-mcp" skill

# 1. Navigate to plugin
cd claude-code/skills

# 2. Create skill
mkdir claude-code-mcp

# 3. Create SKILL.md
cat > claude-code-mcp/SKILL.md << 'EOF'
---
name: Claude Code MCP Servers
description: Configure and troubleshoot Model Context Protocol servers for Claude Code. Use when setting up MCP servers, debugging connections, or integrating external tools.
---

# Claude Code MCP Server Management

## When to Use This Skill
[Content here...]
EOF

# 4. Update plugin README
vim ../README.md
# Add claude-code-mcp to "What's Included"

# 5. Bump version in plugin.json
vim ../.claude-plugin/plugin.json
# Change: "version": "1.0.0" → "1.1.0"

# 6. Test
/plugin install /path/to/Skills/claude-code@local
# Test trigger scenarios

# 7. Submit PR

Security Considerations

Never Include

• API keys, tokens, or credentials
• Personal identifying information
• Proprietary code without permission
• Hardcoded paths to user-specific locations
• Malicious scripts or commands

Always Review

• External dependencies (trusted sources only)
• File system access patterns
• Network requests
• Bash commands in examples

Getting Help

• Skill creation guidance - Use claude-skills plugin
• Plugin structure questions - Use claude-code-plugins skill
• Testing help - See TESTING.md
• Questions - Open an issue

Resources

• Agent Skills Documentation
• Plugin Documentation
• claude-skills Plugin
• claude-code Plugin

---

Thank you for contributing! Your skills help the entire Claude community work more effectively.