SuperCharged-Claude-Code-Upgrade/skills/plugins/QUICKSTART.md

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

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

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

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

Step 2: Create Plugin Metadata

Create .claude-plugin/plugin.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:

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

# Validate your plugin
claude-plugin validate .

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

Step 5: Publish to GitHub

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:

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:

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:

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

Common Use Cases

1. Custom Git Workflows

// 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

// 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

// 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

// 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

# 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:

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

Hook Not Firing

Check hook priority and event name:

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

Next Steps

• 📖 Read the full Plugin Documentation
• 🔧 Explore Example Plugins
• 🚀 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! 🎉