# Plugin System Quick Start Guide

Get started with Claude Code plugins in 5 minutes.

## Installation

The plugin system is included with Claude Code. No additional installation required.

## Your First Plugin

### Step 1: Discover Available Plugins

```bash
claude-plugin discover
```

Output:
```
🔍 Discovering plugins...

Found 3 plugin(s):

📦 git-workflow
   Description: Enhanced Git workflow automation for Claude Code
   Version: 1.0.0
   Author: Your Name
   Source: claude-plugins-official

📦 docker-helper
   Description: Docker container management without Docker Desktop
   Version: 1.0.0
   Author: Your Name
   Source: claude-plugins-official

📦 knowledge-base
   Description: AI-powered knowledge base with semantic search
   Version: 1.0.0
   Author: Your Name
   Source: claude-plugins-official
```

### Step 2: Install a Plugin

```bash
claude-plugin install claude-plugins-official git-workflow
```

Output:
```
📦 Installing git-workflow from claude-plugins-official...

✓ Successfully installed git-workflow v1.0.0
  Location: /home/user/.claude/plugins/cache/claude-plugins-official/git-workflow-1.0.0
  Permissions: read:files, write:files, execute:commands
```

### Step 3: Use the Plugin

Now you can use the plugin's commands in Claude Code:

```
# In Claude Code
git:smart-commit --type feat --scope api
git:pr-create --title "Add new API endpoints"
git:branch-cleanup --local --remote
```

## Creating Your Own Plugin

### Step 1: Create Plugin Structure

```bash
mkdir my-plugin
cd my-plugin
mkdir -p .claude-plugin commands hooks
```

### Step 2: Create Plugin Metadata

Create `.claude-plugin/plugin.json`:

```json
{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "My first Claude Code plugin",
  "author": "Your Name",
  "license": "MIT",
  "claude": {
    "permissions": ["read:files", "execute:commands"],
    "commands": [
      {
        "name": "my:hello",
        "description": "Say hello",
        "handler": "commands/hello.ts",
        "permissions": []
      }
    ]
  }
}
```

### Step 3: Create Command Handler

Create `commands/hello.ts`:

```typescript
export interface HelloOptions {
  name?: string
}

export async function handle(
  args: HelloOptions,
  context: any
): Promise<string> {
  const { name = 'World' } = args
  return `Hello, ${name}!`
}

export default { handle }
```

### Step 4: Test Locally

```bash
# Validate your plugin
claude-plugin validate .

# Test it (if integrated with Claude Code)
my:hello --name "Claude"
```

### Step 5: Publish to GitHub

```bash
git init
git add .
git commit -m "Initial plugin"
git branch -M main
git remote add origin https://github.com/yourusername/my-plugin.git
git push -u origin main
```

### Step 6: Share Your Plugin

Others can now install your plugin:

```bash
claude-plugin install-github yourusername/my-plugin
```

## Using Hooks

Hooks allow your plugin to react to events in Claude Code.

### Example: Auto-save After Edits

Create `hooks/auto-save.ts`:

```typescript
export async function handle(context: any): Promise<void> {
  if (context.event === 'PostFileEdit') {
    const filePath = context.data.filePath
    console.log(`File edited: ${filePath}`)

    // Your auto-save logic here
  }
}

export default { handle }
```

Add to `.claude-plugin/plugin.json`:

```json
{
  "claude": {
    "hooks": [
      {
        "event": "PostFileEdit",
        "handler": "hooks/auto-save.ts",
        "priority": 10
      }
    ]
  }
}
```

## Common Use Cases

### 1. Custom Git Workflows

```typescript
// Auto-create branches from JIRA tickets
export async function handle(args: any) {
  const ticket = args.ticket
  await exec(`git checkout -b feature/${ticket}-description`)
  return `Created branch for ${ticket}`
}
```

### 2. Project Templates

```typescript
// Scaffold new projects
export async function handle(args: any) {
  const { type, name } = args
  // Create project structure
  // Install dependencies
  // Initialize git
  return `Created ${type} project: ${name}`
}
```

### 3. External Tool Integration

```typescript
// Integrate with external APIs
export async function handle(args: any) {
  const response = await fetch('https://api.example.com', {
    method: 'POST',
    body: JSON.stringify(args)
  })
  return await response.json()
}
```

### 4. File Generation

```typescript
// Generate boilerplate code
export async function handle(args: any) {
  const { component, path } = args
  const template = `// Component: ${component}\nexport function ${component}() {}`
  await fs.writeFile(path, template)
  return `Created ${component} at ${path}`
}
```

## Security Best Practices

1. **Request Minimal Permissions**: Only ask for permissions you need
2. **Validate Input**: Always sanitize user input
3. **Handle Errors**: Gracefully handle failures
4. **Avoid Dangerous Commands**: Don't execute destructive commands
5. **Respect User Privacy**: Don't send data without consent

## Troubleshooting

### Plugin Not Found

```bash
# List installed plugins
claude-plugin info my-plugin

# Reinstall
claude-plugin uninstall my-plugin
claude-plugin install-github username/my-plugin
```

### Permission Denied

Check your plugin has the required permissions in `plugin.json`:

```json
{
  "claude": {
    "permissions": ["read:files", "write:files"]
  }
}
```

### Hook Not Firing

Check hook priority and event name:

```json
{
  "event": "PostFileEdit",
  "priority": 100
}
```

## Next Steps

- 📖 Read the full [Plugin Documentation](README.md)
- 🔧 Explore [Example Plugins](examples/)
- 🚀 Share your plugins with the community
- 💬 Join the discussion on GitHub

## Getting Help

- GitHub Issues: https://github.com/anthropics/claude-code/issues
- Documentation: https://docs.anthropic.com

Happy plugin building! 🎉