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](./TESTING.md)

## Adding a Skill to an Existing Plugin

### Option 1: Add to claude-code Plugin

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

```bash
# 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):

```bash
# 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

```bash
# 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

```bash
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

```bash
# 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

```bash
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:
```json
{
  "plugins": [
    {
      "name": "my-plugin",
      "source": "./my-plugin",
      "description": "Brief plugin description"
    }
  ]
}
```

### 6. Test Plugin Installation

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

# Verify skills load
# Try triggering scenarios
```

## Skill Creation Guidelines

### Required: SKILL.md Structure

```yaml
---
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:**
```yaml
# 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:**
```yaml
# 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](./TESTING.md) for:
- Trigger accuracy testing
- Content quality validation
- Token efficiency measurement
- Team collaboration testing

Quick test:
```bash
# 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:

```json
{
  "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

```bash
# 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](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview)
- [Plugin Documentation](https://docs.claude.com/en/docs/claude-code/plugins)
- [claude-skills Plugin](./claude-skills-plugin/README.md)
- [claude-code Plugin](./claude-code/README.md)

---

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