Thank you for your interest in contributing to Build with Claude! This guide will help you create high-quality plugins, agents, commands, hooks, and skills that integrate seamlessly with Claude Code.

• Before You Start
• Project Structure
• Contributing Agents
• Contributing Commands
• Contributing Hooks
• Contributing Skills
• Contributing Plugins
• File Naming Conventions
• Validation & Testing
• Submitting a Pull Request
• Code of Conduct

1. Read the documentation:

   • Claude Code Documentation
   • Subagents
   • Slash Commands
   • Hooks
   • Plugin Marketplaces

2. Check existing contributions: Ensure your idea doesn't overlap significantly with existing components

3. One purpose per contribution: Each component should have a single, clear responsibility

plugins/
├── agents-<category>/
│   ├── .claude-plugin/plugin.json
│   └── agents/*.md                    # Agent markdown files
├── commands-<category>/
│   ├── .claude-plugin/plugin.json
│   └── commands/*.md                  # Command markdown files
├── hooks-<category>/
│   ├── .claude-plugin/plugin.json
│   └── hooks/*.md                     # Hook markdown files
├── all-skills/
│   └── skills/<skill-name>/SKILL.md   # Skill directories
├── all-agents/                        # Bundle: all agents
├── all-commands/                      # Bundle: all commands
└── all-hooks/                         # Bundle: all hooks

Agents are specialized AI experts that Claude Code invokes automatically or on request.

Place agents in: plugins/agents-<category>/agents/<agent-name>.md

---
name: agent-name
description: Clear description of when this agent should be invoked
category: category-name
tools: Read, Write, Bash  # Optional - omit for all tools
---

You are a [role/expertise description].

When invoked:
1. [First action - analyze/understand requirements]
2. [Second action - identify patterns/structure]
3. [Third action - plan approach]
4. [Fourth action - begin implementation]

Process:
- [Key principle or methodology]
- [Best practice to follow]
- [Important consideration]

Provide:
- [Specific deliverable with format]
- [Tests or validation]
- [Documentation or examples]

• name: Must match filename (without .md), lowercase with hyphens
• description: Clear trigger conditions, under 500 characters
• category: Must be one of the valid categories above
• tools: Optional - comma-separated list to restrict tools
• Opening statement: Must start with "You are a..."

Commands are slash commands that users invoke directly.

Place commands in: plugins/commands-<category>/commands/<command-name>.md

---
description: Brief explanation of what the command does (10-200 chars)
category: category-name
argument-hint: <optional-args>  # Optional
allowed-tools: tool1, tool2    # Optional
model: opus|sonnet|haiku       # Optional
---

# Command implementation

Detailed instructions for how the command should work...

Hooks are event-driven automations that run on specific events.

Place hooks in: plugins/hooks-<category>/hooks/<hook-name>.md

---
name: hook-name
description: What this hook does
category: category-name
event: Stop|PreToolUse|PostToolUse
matcher: "*"  # or specific tool name
language: bash
version: 1.0.0
---

# hook-name

Description of the hook's purpose.

## Event Configuration

- **Event Type**: `Stop`
- **Tool Matcher**: `*`
- **Category**: category-name

## Environment Variables

- `VARIABLE_NAME` - Description

## Requirements

List any requirements...

### Script

```bash
#!/bin/bash
# Your executable script here
# Hook receives JSON via stdin with tool_input, tool_name, tool_result fields
# Use jq to parse: jq -r '.tool_input.file_path'

# Example: echo the tool name
tool_name=$(jq -r '.tool_name // empty')
echo "Hook triggered by: $tool_name"

### Hook Events

| Event | Description |
|-------|-------------|
| `PreToolUse` | Before a tool is called |
| `PostToolUse` | After a tool completes |
| `Stop` | When Claude Code finishes |
| `SessionStart` | When a session begins |
| `SessionEnd` | When a session ends |

### Hook Categories

| Category | Description |
|----------|-------------|
| `notifications` | Slack, Discord, Telegram alerts |
| `git` | Auto-staging, smart commits |
| `development` | Lint on save, auto-format |
| `formatting` | Code formatting |
| `security` | File protection, scanning |
| `automation` | General automation |
| `performance` | Performance monitoring |
| `testing` | Test automation |

## Contributing Skills

Skills are reusable capabilities from plugins.

### Skill Location

Create a directory: `plugins/all-skills/skills/<skill-name>/SKILL.md`

### Skill Structure

```markdown
---
name: skill-name
category: category-name
description: What this skill does and when to use it
---

# Skill Name

Description of the skill.

## When to Use This Skill

- Use case 1
- Use case 2

## What This Skill Does

1. Step 1
2. Step 2

## How to Use

### Basic Usage

Example prompt...

## Example

**User**: "Example request"

**Output**:

Example output...

## Tips

- Tip 1
- Tip 2

Plugins are bundled packages containing agents, commands, hooks, or skills.

plugins/<plugin-name>/
├── .claude-plugin/
│   └── plugin.json
├── agents/           # Optional
│   └── *.md
├── commands/         # Optional
│   └── *.md
└── hooks/            # Optional
    └── *.md

{
  "name": "plugin-name",
  "version": "1.0.0",
  "description": "Description of the plugin",
  "author": {
    "name": "Your Name",
    "url": "https://github.com/username"
  },
  "repository": "https://github.com/username/repo",
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"]
}

• Format: descriptive-name.md
• Rules:
  • Use lowercase letters only
  • Separate words with hyphens (-)
  • Be descriptive but concise
  • Name must match the name field in frontmatter

Good examples: code-reviewer.md, python-pro.md, discord-notifications.md

Bad examples: CodeReviewer.md, code_reviewer.md, cr.md

# Install dependencies (from root)
npm install

# Run all validations
npm test

# Or run specific validations
npm run validate              # Master validation
npm run validate:subagents    # Validate agents/commands
npm run validate:hooks        # Validate hooks

1. Installation Test:

   # Install agents
   find plugins/agents-*/agents -name "*.md" -exec cp {} ~/.claude/agents/ \;
   
   # Install commands
   find plugins/commands-*/commands -name "*.md" -exec cp {} ~/.claude/commands/ \;
   
   # Restart Claude Code

2. Functionality Tests:

   • Test with various prompts
   • Verify output matches expectations
   • Check tool restrictions work

1. Branch Naming: add-<component-name> or update-<component-name>

2. PR Title:

   • New: "Add [name] [type]" (e.g., "Add python-pro agent")
   • Updates: "Update [name]: [description]"

3. PR Description:

   ## Summary
   Brief description of the contribution
   
   ## Component Details
   - **Name**: component-name
   - **Type**: Agent/Command/Hook/Skill
   - **Category**: category-name
   
   ## Testing
   - [ ] Ran validation (`npm test`)
   - [ ] Tested functionality
   - [ ] No overlap with existing components
   
   ## Examples
   Provide 2-3 example usages

1. Automated Checks: Validation runs automatically
2. Manual Review: Uniqueness, quality, documentation
3. Merge: Once approved, auto-deploys to buildwithclaude.com

• Be respectful and constructive
• Focus on improving Claude Code's capabilities
• No components for malicious purposes
• Respect intellectual property
• Help others improve their contributions

• Check existing issues
• Join the discussion in pull requests
• Browse the Web UI for examples

Thank you for contributing to Build with Claude!