What are Claude Code Plugins?

Plugins extend Claude Code’s functionality by adding new commands, skills, agents, and hooks to your CLI experience. They’re modular extensions that integrate seamlessly into your workflow.

Plugin Types

Commands:

• Slash commands you can invoke directly
• Examples: /commit, /ralph-loop, /hookify
• Available via tab completion

Skills:

• Auto-invoked based on file patterns or user actions
• Examples: frontend-design (triggers on frontend work)
• Contextual assistance without manual activation

Agents:

• Specialized subprocesses for complex tasks
• Examples: code-reviewer, comment-analyzer
• Run in parallel for comprehensive analysis

Hooks:

• Lifecycle event handlers
• Examples: PreToolUse (security-guidance), SessionStart, Stop (ralph-wiggum)
• Automatic behavior modification

Benefits for Multi-Repo Workflows

If you’re managing multiple projects in a multi-repository setup, plugins provide:

• Consistency: Same workflows across all repos
• Automation: Reduce repetitive tasks (commits, reviews, refactoring)
• Enforcement: Prevent mistakes before they happen (hookify)
• Speed: Autonomous iteration loops (ralph-wiggum)
• Quality: Automated PR reviews with specialized agents

The 8 Essential Plugins

This guide covers the 8 plugins recommended for professional multi-repo development:

What You’ll Learn

1. Installation - How to discover, install, and manage plugins
2. Essential Plugins - Quick-start commands for everyday use
3. Ralph Wiggum - Master autonomous iteration loops
4. Hookify - Build custom enforcement rules
5. Frontend & Security - Automatic quality checks
6. Agent Development - Validate and build custom agents
7. Marketplace - Find and publish plugins

Plugin Management

Claude Code includes built-in commands for discovering, installing, and managing plugins.

Installing Plugins

Install from official marketplace:

claude plugin install <plugin-name>

Install from specific marketplace:

claude plugin install <plugin-name>@<marketplace-name>

Examples:

# Install ralph-wiggum from official marketplace
claude plugin install ralph-wiggum

# Install all 8 recommended plugins
claude plugin install ralph-wiggum
claude plugin install commit-commands
claude plugin install frontend-design
claude plugin install security-guidance
claude plugin install hookify
claude plugin install pr-review-toolkit
claude plugin install feature-dev
claude plugin install agent-sdk-dev

Managing Installed Plugins

Enable a disabled plugin:

claude plugin enable <plugin-name>

Disable a plugin temporarily:

claude plugin disable <plugin-name>

Uninstall a plugin:

claude plugin uninstall <plugin-name>
# or
claude plugin remove <plugin-name>

Update a plugin:

claude plugin update <plugin-name>

Plugin Commands

Once plugins are installed, their commands appear in tab completion:

claude <tab>
# Shows all available commands including plugin commands

claude /ralph<tab>
# Completes to /ralph-loop or /cancel-ralph

Check installed plugins’ commands:

• Use /help to see all available commands
• Plugin commands are prefixed with / (slash commands)
• Tab completion works for all plugin commands

Marketplace Discovery

Official marketplace:

Browse plugins at: https://github.com/anthropics/claude-code/tree/main/plugins

Available official plugins (as of 2026-01):

• agent-sdk-dev
• claude-opus-4-5-migration
• code-review
• commit-commands
• explanatory-output-style
• feature-dev
• frontend-design
• hookify
• learning-output-style
• plugin-dev
• pr-review-toolkit
• ralph-wiggum
• security-guidance

Plugin Validation

Check if a plugin is installed and enabled:

# List all plugin commands
/help

# Try invoking a plugin command
/commit --help
/ralph-loop --help
/hookify --help

If the command is recognized, the plugin is active.

Troubleshooting

Command not found:

• Ensure plugin is installed: claude plugin install <name>
• Check if it’s enabled (not disabled)
• Restart Claude Code session
• Verify plugin compatibility with your Claude Code version

Plugin conflicts:

• Some plugins may conflict (e.g., code-review vs pr-review-toolkit)
• Disable conflicting plugins: claude plugin disable <name>
• Only keep the one you prefer active

commit-commands

Streamline your Git workflow with one-command commits, pushes, and PRs.

Commands

/commit - Auto-generated commit message

/commit

Claude analyzes your staged changes and generates an appropriate commit message following your repository’s conventions.

Example workflow:

# Stage your changes
git add src/components/Button.tsx tests/Button.test.tsx

# Let Claude commit with auto-generated message
/commit

/commit-push-pr - One-command workflow

/commit-push-pr

Combines commit + push + PR creation into a single command. Claude:

1. Analyzes changes
2. Generates commit message
3. Pushes to remote
4. Creates pull request with summary

Perfect for sprint-based workflows where documentation → commit → PR is a regular pattern.

/clean_gone - Clean up merged branches

/clean_gone

Removes local branches that have been merged and deleted on the remote.

pr-review-toolkit

Comprehensive PR review with 6 specialized agents running in parallel.

Command

/pr-review-toolkit:review-pr - Full PR analysis

/pr-review-toolkit:review-pr

Launches 6 specialized agents:

1. comment-analyzer - Reviews code comment quality
2. pr-test-analyzer - Analyzes test coverage
3. silent-failure-hunter - Finds error handling gaps
4. type-design-analyzer - Reviews TypeScript/type system design
5. code-reviewer - General quality review
6. code-simplifier - Identifies over-engineering

The code-simplifier Agent

Aligns with the “avoid over-engineering” principle:

• Flags unnecessary abstractions
• Identifies premature optimization
• Suggests simpler implementations
• Questions overly complex patterns

Example findings:

• “This helper function is only used once - inline it?”
• “Feature flag adds complexity - just change the code directly”
• “These 3 lines don’t need a utility function”

When to Use

• Before requesting human PR review
• On your own PRs before submitting
• When reviewing teammate PRs (supplement your review)
• For large refactoring PRs (catches issues early)

feature-dev

Structured 7-phase feature development workflow with automatic documentation.

Command

/feature-dev - Guided feature development

/feature-dev

Interactive workflow that guides you through:

Phase 1: Understand - Clarify requirements

• Asks questions to understand scope
• Identifies ambiguities
• Defines success criteria

Phase 2: Explore - Examine codebase

• Searches for existing patterns
• Identifies related code
• Maps dependencies

Phase 3: Design - Plan implementation

• Proposes architecture
• Considers trade-offs
• Outlines approach

Phase 4: Plan - Break down tasks

• Creates step-by-step plan
• Identifies files to modify
• Estimates complexity

Phase 5: Implement - Write code

• Implements feature
• Follows established patterns
• Maintains code quality

Phase 6: Test - Verify functionality

• Writes tests
• Runs test suite
• Validates coverage

Phase 7: Document - Update docs

• Updates .claude/implementation_progress.md
• Adds inline documentation
• Creates user-facing docs

Perfect For

• Complex features requiring planning
• Cross-repo patterns (applying same feature to multiple repos)
• Features with unclear requirements
• Sprint-based development workflows

Example Use Case

# In your knowledge-base repository
/feature-dev

# Claude asks: "What feature would you like to develop?"
# You respond: "Add user authentication with session management"

# Claude then:
# - Explores existing auth patterns in your codebase
# - Proposes JWT vs session-based approach
# - Creates implementation plan
# - Implements with tests
# - Documents in .claude/implementation_progress.md

When to Use Each

All three plugins are self-guided - they prompt you for information and walk you through the process. No complex configuration needed!

The Game Changer

Ralph Wiggum enables autonomous iteration loops where Claude reads its own previous work and iteratively improves it until a task is complete. This is production-tested technology that has:

• Built entire repositories overnight
• Completed $50k contracts for $297 in API costs
• Created programming languages over months of iterations

How It Works

Ralph uses a Stop hook that intercepts Claude’s exit attempts and re-feeds the same prompt automatically:

You run ONCE → /ralph-loop "task" --max-iterations 50

Then Claude:
1. Works on task
2. Tries to exit
3. Stop hook blocks exit
4. Re-feeds prompt
5. Claude reads own work
6. Improves it
7. Repeat until done

This creates a self-referential feedback loop where each iteration sees:

• File changes from previous iterations
• Git commit history
• Test results and build output
• The unchanged original prompt

Command Syntax

/ralph-loop "<task description>" \
  --max-iterations <N> \
  --completion-promise "<text>"

Parameters

<task description> (required)

• Clear description of what to accomplish
• Include success criteria
• Specify verification steps

--max-iterations <N> (required)

• Maximum number of iterations before stopping
• CRITICAL: Always set this as a safety net
• Start small (10-20) before overnight runs (50-100)

--completion-promise "<text>" (required)

• Exact phrase Claude outputs when done
• Typically: COMPLETE, DONE, SUCCESS
• Must appear in prompt so Claude knows what to output

Real Examples for Your Workflow

PREFIX Doc Compliance Sweep

/ralph-loop "Scan all docs/ folders across all repositories.
Find any PREFIX files not matching pattern: {PREFIX###} Descriptive Title.md.
Fix the filenames to include descriptive titles.
List all modified files.
When all PREFIX docs are compliant, output <promise>COMPLETE</promise>" \
--max-iterations 20 \
--completion-promise "COMPLETE"

Overnight Refactoring with Test Validation

/ralph-loop "Refactor audio-lib/apps/editor following patterns in ARCHITECTURE.md.
After EACH change:
1. Run tests with: cd audio-lib && npm test
2. If tests fail, debug and fix
3. Commit the change if tests pass
4. Move to next refactoring task

When all patterns are applied AND all tests pass, output <promise>COMPLETE</promise>" \
--max-iterations 50 \
--completion-promise "COMPLETE"

TDD Feature Development

/ralph-loop "Implement user authentication in knowledge-base with TDD approach:
1. Write failing test
2. Implement minimal code to pass test
3. Refactor if needed
4. Repeat for next feature

Requirements:
- Session-based auth (not JWT)
- Login, logout, session validation
- Test coverage must be >80%
- Update .claude/implementation_progress.md when done

Output <promise>COMPLETE</promise> when feature is complete with passing tests and docs updated." \
--max-iterations 60 \
--completion-promise "COMPLETE"

Cross-Repo Pattern Enforcement

/ralph-loop "Apply spacing standards from ~/workspace/docs/design-standards.md to frontend CSS.
Repos to update: dashboard-v2, dict-app, task-app, portfolio, data-viz.
For each repo:
1. Update CSS to match spacing standards
2. Run build: npm run build
3. Fix any build errors
4. Commit changes
5. Move to next repo

When all repos are updated with consistent spacing AND all builds pass, output <promise>COMPLETE</promise>" \
--max-iterations 40 \
--completion-promise "COMPLETE"

Prompting Best Practices

1. Clear Completion Criteria

❌ Bad: “Build a todo API and make it good.”

✅ Good:

Build a REST API for todos.

When complete:
- All CRUD endpoints working
- Input validation in place
- Tests passing (coverage > 80%)
- README with API docs
- Output: <promise>COMPLETE</promise>

2. Incremental Goals

❌ Bad: “Create a complete e-commerce platform.”

✅ Good:

Phase 1: User authentication (JWT, tests)
Phase 2: Product catalog (list/search, tests)
Phase 3: Shopping cart (add/remove, tests)

Output <promise>COMPLETE</promise> when all phases done.

3. Self-Correction Loop

Include verification:

Implement feature X following TDD:
1. Write failing tests
2. Implement feature
3. Run tests
4. If any fail, debug and fix  ← Self-correction
5. Refactor if needed
6. Repeat until all green
7. Output: <promise>COMPLETE</promise>

4. Safety Mechanisms

ALWAYS set --max-iterations:

/ralph-loop "Complex task" --max-iterations 20
# Not: /ralph-loop "Complex task"  ← Will run indefinitely!

In your prompt, add fallback behavior:

After 15 iterations, if not complete:
- Document what's blocking progress
- List what was attempted
- Suggest alternative approaches

When to Use Ralph Wiggum

✅ Perfect For:

• Well-defined tasks with automatic verification (tests, builds)
• Refactoring with test suites
• Documentation compliance sweeps
• TDD workflows
• Overnight/weekend work sessions

❌ Avoid For:

• Unclear requirements or goals
• Tasks requiring human judgment
• Design decisions without clear criteria
• One-shot operations (just do them normally)
• Exploratory/research tasks

Monitoring Ralph Loops

While Ralph runs, you can:

• Watch file changes in your editor
• Monitor git commits (if you instructed commits)
• Check test output (if tests are running)
• Cancel anytime: /cancel-ralph

Cancel Command

/cancel-ralph

Immediately stops the active Ralph loop.

Advanced: Pairing with Hookify

hookify prevents future violations, ralph fixes existing ones.

Example workflow:

# First: Create hook to prevent bad PREFIX files
/hookify
# Create rule: Block Write if filename matches docs/**/[A-Z]{3,4}\d{3,4}\.md$ without space

# Then: Use ralph to fix all existing violations
/ralph-loop "Fix all existing PREFIX files..." --max-iterations 20

This ensures:

1. Ralph fixes all current violations
2. Hookify prevents new violations going forward

Testing Your First Ralph Loop

Start small to learn the pattern:

/ralph-loop "Create a simple test file at /tmp/ralph-test.txt with the word 'Hello'.
Then read the file to verify it exists.
Output <promise>COMPLETE</promise> when file exists with correct content." \
--max-iterations 5 \
--completion-promise "COMPLETE"

Watch how Ralph:

1. Creates the file
2. Reads it back
3. Verifies content
4. Outputs COMPLETE
5. Stops

Custom Rule Enforcement

Hookify lets you create custom hooks that prevent unwanted behaviors before they happen. Think of it as “linting for Claude’s actions.”

Commands

/hookify - Interactive hook creation

/hookify

Launches an interactive workflow to create a new hook. Claude asks:

• What behavior to prevent or warn about
• When to trigger (file patterns, content patterns)
• What action to take (block, warn, allow with confirmation)

/hookify:list - Show active hooks

/hookify:list

Lists all hooks currently active in your project.

/hookify:configure - Edit hook settings

/hookify:configure

Modify existing hooks or their settings.

Your Use Case: PREFIX Naming Enforcement

Perfect example from your multi-repo workflow.

Problem

You have a strict naming convention:

• Pattern: \{PREFIX###\} Descriptive Title.md
• ✅ Good: CGD001 Project Overview.md
• ❌ Bad: CGD001.md (missing title)

Claude might accidentally create files without titles.

Solution

Create a hook to block these:

/hookify

Interactive prompts:

1. What behavior to prevent?

   “Prevent creating PREFIX files without descriptive titles”

2. Pattern to match:

   docs/**/[A-Z]\{3,4\}\d\{3,4\}\.md$

3. Action:

   “Block Write”

4. Error message:

   “PREFIX files must follow pattern: {PREFIX###} Descriptive Title.md”

Result

Now when Claude tries:

/write docs/cgd/CGD042.md

Hookify blocks it with:

❌ Blocked: PREFIX files must follow pattern: {PREFIX###} Descriptive Title.md

Claude must use:

/write docs/cgd/CGD042 Sprint 7 Implementation.md

Hook Syntax Patterns

File Pattern Matching

Block writes to specific paths:

Pattern: src/components/legacy/**
Rule: Block Write
Message: "Do not modify legacy components - create new ones instead"

Warn on sensitive files:

Pattern: .env*
Rule: Warn Write
Message: "Be careful - this file may contain secrets"

Require specific file extensions:

Pattern: src/**/*.js
Rule: Block Write if new file
Message: "Use TypeScript (.ts/.tsx) for new files, not JavaScript"

Content Pattern Matching

Block specific code patterns:

if content contains "eval("
Rule: Block Write
Message: "eval() is dangerous - use safer alternatives"

Warn about TODO comments:

if content contains "TODO:"
Rule: Warn Write
Message: "TODO found - consider creating a GitHub issue instead"

Enforce import patterns:

if filename matches "src/components/**/*.tsx"
and content does not contain "import React"
Rule: Block Write
Message: "React components must import React"

Action Types

Block - Prevents the action entirely

• Use for: Rules that must never be broken
• Example: “Never modify production config directly”

Warn - Shows warning but allows action

• Use for: Soft guidelines
• Example: “Consider adding tests for new features”

Confirm - Asks user to confirm before proceeding

• Use for: Potentially dangerous but sometimes necessary
• Example: “Are you sure you want to delete this file?”

Common Hook Patterns

Documentation Standards

Pattern: docs/**/*.md
if content does not contain "## References"
and content contains "[1]"
Rule: Warn Write
Message: "Citations found but no References section - add ## References"

Code Quality

Pattern: src/**/*.ts
if content contains "any"
Rule: Warn Write
Message: "Avoid 'any' type - use specific types or 'unknown'"

Security

Pattern: **/*.{js,ts}
if content contains "process.env"
and not in file ".env.example"
Rule: Warn Write
Message: "Avoid hardcoding env vars - use config files"

Git Workflow

Pattern: .git/config
Rule: Block Write
Message: "Do not modify git config directly - use git commands"

Testing Hooks

After creating a hook, test it:

# Try to trigger the hook
# Example: Try creating a PREFIX file without title

# Should block:
/write docs/cgd/CGD999.md
# Error: ❌ Blocked: PREFIX files must follow pattern...

# Should allow:
/write docs/cgd/CGD999 Test Document.md
# Success: ✓ File created

Multi-Repo Hook Strategy

User-Level Hooks (Apply Everywhere)

Install at ~/.claude/hooks/ for all projects:

• Security patterns (no eval, no os.system)
• General coding standards (no console.log in production)
• Documentation requirements (PREFIX naming)

Repo-Level Hooks (Project-Specific)

Install at <repo>/.claude/hooks/ for specific repos:

• Project-specific patterns (content validation, audio processing)
• Tech stack rules (Rust in system-level apps, C++ in performance-critical code)
• Architecture enforcement (following ARCHITECTURE.md patterns)

Example: PREFIX Hook for All Repos

Create once, applies everywhere:

/hookify

# Pattern: docs/**/[A-Z]{3,4}\d{3,4}\.md$
# Rule: Block Write if filename matches pattern without space after number
# Message: "PREFIX files must follow pattern: {PREFIX###} Descriptive Title.md"

# Install at user level: ~/.claude/hooks/prefix-naming.json

Now works in:

• data-pipeline (DAT prefix)
• content-system (CNT prefix)
• audio-lib (AUD, EDI prefixes)
• dict-app (DIC prefix)
• knowledge-base (KBD prefix)
• analysis-tool (ANL prefix)

Disabling Hooks Temporarily

When you need to bypass a hook (rare):

claude plugin disable hookify

Do your work, then:

claude plugin enable hookify

Hook Development Workflow

1. Identify pattern - Notice Claude making a mistake repeatedly
2. Create hook - Use /hookify to prevent it
3. Test - Verify hook triggers correctly
4. Refine - Adjust pattern or message as needed
5. Fix existing violations - Use /ralph-loop to clean up old instances
6. Monitor - Hook prevents future violations

Example: Fixing Existing + Preventing Future

# Step 1: Create hook (prevents future)
/hookify
# Rule: Block PREFIX files without titles

# Step 2: Fix existing violations (cleans past)
/ralph-loop "Fix all PREFIX files in all repos..." --max-iterations 20

Perfect combo for maintaining standards!

Automatic Plugins

These plugins work automatically - no commands to remember, just install and they activate when needed.

frontend-design

Auto-invoked skill that enforces your design system and prevents generic AI aesthetics.

How It Works

The plugin automatically activates when you’re working on frontend code. It references:

• Your design system documentation
• Shared font library
• Spacing standards
• Component patterns

What It Enforces

Typography:

• Suggests fonts from your shared library
• Recommends: Satoshi, Cabinet Grotesk, General Sans, Switzer
• Prevents: Generic system fonts, Arial, Helvetica

Spacing:

• References design standards documentation
• Enforces app-type appropriate spacing:
  • Dashboard: 4-8-12px gaps
  • SaaS: 8-12-16px gaps
  • Marketing: 16-24px+ gaps
• Prevents: Arbitrary spacing values, inconsistent gaps

Design Tokens:

• Encourages using design token systems
• Suggests Tailwind config integration
• Prevents: Hardcoded colors, magic numbers

Component Structure:

• Follows established patterns in your repos
• Maintains consistency across components
• Avoids generic AI component aesthetics

Active Repos

The plugin is particularly useful in:

• dashboard-v2 (most advanced frontend)
• audio-editor-app (C++ app with UI)
• task-app (task management UI)
• personal-portfolio (marketing site)
• data-dashboard (3D visualization)
• dictionary-app (reference UI)

Example Interaction

You: “Create a button component”

Claude (with frontend-design):

// Uses Cabinet Grotesk from your font library
// Applies 12px spacing from your standards
// Follows your existing component patterns

import { Button } from './components/Button';

export function PrimaryButton({ children }) {
  return (
    <button className="font-cabinet text-base px-4 py-3 rounded-lg">
      {children}
    </button>
  );
}

Instead of generic:

<button style="font-family: Arial; padding: 10px;">Click me</button>

security-guidance

PreToolUse hook that monitors for security vulnerabilities before code execution.

How It Works

Before Claude uses tools that could introduce security issues, this hook:

1. Scans the planned action
2. Checks against 9 security patterns
3. Warns if dangerous patterns detected
4. Allows you to approve or reject

9 Security Patterns Monitored

1. Command Injection

// ❌ Dangerous
exec(`rm -rf ${userInput}`);

// Warning: "Potential command injection - sanitize userInput first"

2. XSS Vulnerabilities

// ❌ Dangerous
element.innerHTML = userContent;

// Warning: "XSS risk - use textContent or sanitize HTML"

3. eval() Usage

// ❌ Dangerous
eval(userCode);

// Warning: "eval() is dangerous - use safer alternatives like Function() or JSON.parse()"

4. Dangerous HTML

// ❌ Dangerous
dangerouslySetInnerHTML={{ __html: untrustedHTML }}

// Warning: "Sanitize HTML before using dangerouslySetInnerHTML"

5. Python Pickle Deserialization

# ❌ Dangerous
pickle.load(untrusted_file)

# Warning: "Pickle deserialization from untrusted sources is dangerous"

6. os.system() Calls

# ❌ Dangerous
os.system(f"process {user_input}")

# Warning: "os.system() with user input risks command injection - use subprocess with shell=False"

7. SQL Injection

# ❌ Dangerous
cursor.execute(f"SELECT * FROM users WHERE id = {user_id}")

# Warning: "SQL injection risk - use parameterized queries"

8. Path Traversal

// ❌ Dangerous
fs.readFile(`./files/${userFilename}`)

// Warning: "Path traversal risk - validate filename doesn't contain ../"

9. Unsafe Regex

// ❌ Dangerous (ReDoS vulnerability)
/^(a+)+$/

// Warning: "Regex may be vulnerable to ReDoS - test with long inputs"

Multi-Language Support

Security-guidance works across your entire stack:

• Python: data-pipeline (pandas, data processing)
• TypeScript/Node: content-system, knowledge-base, task-app
• Rust: dict-app (safer by default, but still monitors)
• C++: audio-lib (additional C++-specific checks)

What Happens When Triggered

Scenario: Claude tries to add code with potential SQL injection

security-guidance activates:

⚠️ Security Warning

Potential security issue detected:
  Pattern: SQL Injection
  Location: src/database/queries.py:42
  Issue: String interpolation in SQL query

Suggested fix:
  Use parameterized queries instead:
  cursor.execute("SELECT * FROM users WHERE id = ?", (user_id,))

Proceed anyway? [y/N]

You can:

• Reject: Claude will use the safer approach
• Approve: Claude proceeds with original code (if you have a good reason)

No Action Required

Both plugins work automatically:

frontend-design:

• Install: ✓
• Configure: Not needed (reads your workspace docs)
• Use: Automatic when working on frontend

security-guidance:

• Install: ✓
• Configure: Not needed (monitors all languages)
• Use: Automatic when potentially dangerous code is written

Verification

Test frontend-design:

# Create a new component in any frontend repo
cd ~/projects/task-app
# Ask Claude to create a button component
# Notice: Uses Cabinet Grotesk, proper spacing, no generic styles

Test security-guidance:

# Try adding code with potential security issue
cd ~/projects/data-pipeline
# Ask Claude to add database query with string interpolation
# Notice: Warning appears before code is written

Disabling If Needed

If a plugin becomes intrusive:

# Temporarily disable
claude plugin disable frontend-design
# or
claude plugin disable security-guidance

# Re-enable later
claude plugin enable <plugin-name>

But in practice, these plugins are non-intrusive:

• frontend-design just improves suggestions
• security-guidance only warns on actual security issues

Agent SDK Development Plugin

Tools for validating existing agents and building new ones following Agent SDK best practices.

Why This Matters

You already have custom agents in your repos:

• data-pipeline/.claude/agents/
• content-system/.claude/agents/
• audio-lib/.claude/agents/
• dict-app/.claude/agents/
• knowledge-base/.claude/agents/
• analysis-tool/.claude/agents/

This plugin ensures they follow best practices and helps you build new ones correctly.

Commands

/new-sdk-app - Interactive SDK project setup

/new-sdk-app

Guides you through creating a new Agent SDK application:

1. Choose language (Python or TypeScript)
2. Select project template
3. Configure dependencies
4. Set up directory structure
5. Generate boilerplate code

When to use:

• Building standalone agent applications
• Creating complex multi-agent systems
• Developing agents for distribution

Validators

agent-sdk-verifier-py

Validates Python Agent SDK applications.

What it checks:

• Correct import patterns
• Proper async/await usage
• Tool registration
• Error handling
• API usage patterns
• Type hints

Example validation:

cd ~/projects/data-pipeline/.claude/agents/data-analyzer
# If this is a Python SDK agent:
# The plugin validates it automatically

Common issues caught:

# ❌ Missing await
result = agent.run_tool("search")

# ✅ Correct
result = await agent.run_tool("search")

# ❌ Wrong import
from claude import Agent

# ✅ Correct
from claude_sdk import Agent

agent-sdk-verifier-ts

Validates TypeScript Agent SDK applications.

What it checks:

• TypeScript configuration
• Proper async patterns
• Tool type definitions
• Error boundaries
• Module exports

Example validation:

// ❌ Missing types
async function runAgent(input) {
  return await agent.process(input);
}

// ✅ Correct
async function runAgent(input: string): Promise<AgentResult> {
  return await agent.process(input);
}

Validating Your Existing Agents

Workflow

# Navigate to each repo
cd ~/projects/data-pipeline

# If you have Python agents in .claude/agents/:
# The validator runs automatically when you work with them

# Check for issues:
ls .claude/agents/
# agent-sdk-dev will flag any non-compliant agents

Common Issues & Fixes

Issue: Agent doesn’t follow SDK patterns

# Old pattern (CLI-only agent)
{
  "name": "my-agent",
  "description": "Does stuff",
  "agent_type": "code-reviewer"
}

# SDK pattern (if converting to SDK)
# Needs proper Python/TS entry point with Agent SDK imports

Issue: Missing error handling

# ❌ No error handling
def process_data(data):
    result = expensive_operation(data)
    return result

# ✅ Proper error handling
async def process_data(data: Dict) -> Result:
    try:
        result = await expensive_operation(data)
        return Result(success=True, data=result)
    except Exception as e:
        logger.error(f"Processing failed: {e}")
        return Result(success=False, error=str(e))

Issue: Synchronous instead of async

# ❌ Synchronous (blocks)
def search_codebase(query):
    return tool.search(query)

# ✅ Asynchronous (non-blocking)
async def search_codebase(query: str) -> SearchResults:
    return await tool.search(query)

Building New Agents

Use Case Examples from Your Repos

data-pipeline: Data Pipeline Validator

/new-sdk-app

Language: Python
Purpose: Validate data pipelines before processing
Tools: File reading, schema validation, data quality checks

content-system: Content Validator

/new-sdk-app

Language: TypeScript
Purpose: Analyze content structure and metadata
Tools: File system, JSON parsing, content extraction

audio-lib: Audio Quality Checker

/new-sdk-app

Language: Python
Purpose: Verify audio files meet quality standards
Tools: Audio analysis, FFmpeg integration, report generation

dict-app: Dictionary Data Validator

/new-sdk-app

Language: Rust (or TypeScript)
Purpose: Validate database data integrity
Tools: Database queries, schema checks, consistency validation

Agent SDK Best Practices

1. Always Use Async/Await

# SDK agents should be async by default
async def main():
    agent = Agent(name="my-agent")
    result = await agent.run()
    return result

2. Proper Error Handling

from typing import Result, Error

async def process(input: str) -> Result[str, Error]:
    try:
        output = await heavy_processing(input)
        return Result.ok(output)
    except ProcessingError as e:
        return Result.err(Error(str(e)))

3. Type Hints (Python) / Types (TypeScript)

# ✅ Python with types
async def search(query: str, limit: int = 10) -> List[SearchResult]:
    ...

# ✅ TypeScript with types
async function search(query: string, limit: number = 10): Promise<SearchResult[]> {
    ...
}

4. Tool Registration

from claude_sdk import Agent, Tool

@Tool(name="search", description="Search codebase")
async def search_tool(query: str) -> str:
    # Implementation
    pass

agent = Agent(tools=[search_tool])

When to Use CLI Agents vs SDK Apps

CLI Agents (.claude/agents/*.json or .md):

• Simple, declarative agents
• Workflow automation
• Quick helpers for specific repos
• No programming needed

SDK Applications (built with /new-sdk-app):

• Complex multi-step logic
• External API integrations
• Advanced error handling
• Reusable across projects
• Requires programming

Validation Workflow Summary

# 1. Install plugin (already done)
claude plugin install agent-sdk-dev

# 2. Work with your agents
cd ~/projects/data-pipeline
# Edit agents in .claude/agents/

# 3. Validation happens automatically
# Any issues flagged with suggestions

# 4. Fix issues
# Follow validator recommendations

# 5. Test agent
# Verify it works as expected

# 6. Repeat for other repos
cd ~/projects/content-system
cd ~/projects/audio-lib
# etc.

Building vs Validating

Validating existing agents:

• Automatic when working with .claude/agents/
• Flags issues, suggests fixes
• No command needed

Building new SDK apps:

• Use /new-sdk-app
• Interactive setup
• Generates compliant boilerplate

Most users: Validation is what you’ll use most. Building SDK apps is for advanced scenarios.

Plugin Marketplace

Discover new plugins, evaluate their usefulness, and learn how to build your own.

Official Marketplace

Repository: https://github.com/anthropics/claude-code/tree/main/plugins

All officially supported plugins are hosted here.

Available Plugins (2026-01)

Installed (8 essential):

• ✅ ralph-wiggum - Autonomous iteration loops
• ✅ commit-commands - Git workflow automation
• ✅ frontend-design - Design system enforcement
• ✅ pr-review-toolkit - Comprehensive code review
• ✅ security-guidance - Security monitoring
• ✅ hookify - Custom rule enforcement
• ✅ feature-dev - 7-phase development workflow
• ✅ agent-sdk-dev - Agent development & validation

Not Installed:

• code-review - Alternative to pr-review-toolkit (different review agents)
• plugin-dev - For building distributable plugins
• explanatory-output-style - Adds educational context (token-heavy)
• learning-output-style - Interactive learning mode (asks user to code)
• claude-opus-4-5-migration - Model migration tool

Installing from Marketplace

Default (Official)

claude plugin install <plugin-name>

Installs from the official marketplace automatically.

Specific Marketplace

claude plugin install <plugin-name>@<marketplace-name>

For third-party or custom marketplaces.

Examples

# Official marketplace (default)
claude plugin install ralph-wiggum

# Specific marketplace (if you had one)
claude plugin install my-custom-plugin@company-marketplace

Evaluating New Plugins

Before installing a new plugin, consider:

1. What Problem Does It Solve?

• Does it automate something you do manually?
• Does it prevent mistakes you’ve made?
• Does it enforce standards you care about?

Example: hookify solves PREFIX naming violations

2. What’s the Token Cost?

High Cost:

• SessionStart hooks (run every session): explanatory-output-style
• Always-active skills: Some aggressive linters

Low Cost:

• Commands (only when invoked): commit-commands
• Conditional hooks (only when triggered): security-guidance
• PreToolUse hooks (only before dangerous actions): hookify

3. Does It Conflict?

Conflicting plugins:

• code-review ↔ pr-review-toolkit (both do PR review)
• Multiple commit automation plugins
• Overlapping security scanners

Check before installing:

# See what's installed
/help
# Look for similar functionality

4. Is It Maintained?

Check the official repo:

• Last updated date
• Number of issues/PRs
• Community activity

Building Your Own Plugins

When to Build a Plugin

Good reasons:

• Workflow specific to your multi-repository setup
• Enforcement rule unique to your conventions
• Integration with internal tools
• Pattern repeated across projects

Bad reasons:

• One-off task (just do it directly)
• Already exists in marketplace
• Workflow still evolving (standardize first)

Plugin Anatomy

Minimum structure:

my-plugin/
├── .claude-plugin/
│   └── plugin.json         # Manifest
├── commands/               # Slash commands (optional)
│   └── my-command.sh
├── skills/                 # Auto-invoked skills (optional)
│   └── my-skill.json
├── agents/                 # Specialized agents (optional)
│   └── my-agent.py
├── hooks/                  # Lifecycle hooks (optional)
│   └── pre-tool-use.sh
└── README.md

plugin.json example:

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "Does something useful",
  "commands": ["commands/my-command.sh"],
  "skills": ["skills/my-skill.json"],
  "hooks": {
    "PreToolUse": "hooks/pre-tool-use.sh"
  }
}

Using plugin-dev

For building distributable plugins:

# Install plugin-dev
claude plugin install plugin-dev

# Create new plugin
/plugin-dev:create-plugin

# Follow interactive workflow:
# 1. Choose plugin type
# 2. Select features
# 3. Generate structure
# 4. Implement functionality
# 5. Test locally
# 6. Package for distribution

Custom Plugin Ideas for Your Workflow

1. Cross-Repo Documentation Syncer

Problem: CLAUDE.md files across 6 repos get out of sync

Solution: Plugin that:

• Scans all repos for CLAUDE.md changes
• Identifies drift from workspace standards
• Suggests syncs
• Auto-updates with approval

Type: Command + Agent

2. PREFIX Consistency Checker

Problem: Different PREFIX patterns across repos

Solution: Plugin that:

• Validates PREFIX files in all repos
• Checks sequential numbering
• Ensures title presence
• Reports violations

Type: Command (or use ralph-wiggum with hookify)

3. Multi-Repo Test Runner

Problem: Running tests across 6 repos manually

Solution: Plugin that:

• Detects test frameworks in each repo
• Runs tests in parallel
• Aggregates results
• Reports failures

Type: Command

4. Dependency Audit Reporter

Problem: Tracking outdated dependencies across repos

Solution: Plugin that:

• Scans package.json, Cargo.toml, pyproject.toml
• Checks for outdated deps
• Reports security vulnerabilities
• Suggests updates

Type: Skill (auto-invoked when dependencies change)

Publishing Plugins

Internal Use (Your 6 Repos)

Option 1: User-level installation

# Copy plugin to:
~/.claude/plugins/my-plugin/

# Claude Code auto-detects it

Option 2: Repo-level installation

# Copy plugin to each repo:
~/projects/data-pipeline/.claude/plugins/my-plugin/
~/projects/content-system/.claude/plugins/my-plugin/
# etc.

Public Distribution

Steps:

1. Create plugin following structure
2. Test thoroughly
3. Write comprehensive README
4. Submit PR to official marketplace repo
5. Wait for review and merge

Requirements:

• Clear documentation
• Test coverage
• Security review
• Maintainer commitment

Plugin Maintenance

Updating Your Installed Plugins

# Update all plugins
claude plugin update <plugin-name>

# Check for updates
# Visit: https://github.com/anthropics/claude-code/tree/main/plugins

Removing Unused Plugins

# Disable temporarily
claude plugin disable <plugin-name>

# Uninstall permanently
claude plugin uninstall <plugin-name>

Integration with MCP Servers

MCP (Model Context Protocol) Servers provide external integrations:

• Database connections
• API access
• File system extensions
• Custom tools

Plugins vs MCP:

• Plugins: Extend Claude Code behavior (commands, hooks, agents)
• MCP Servers: Provide external data/tools to Claude

They work together:

Plugin (ralph-wiggum)
  → Calls MCP Server (database)
  → Retrieves data
  → Processes it iteratively

MCP documentation: See /help or Claude Code docs for MCP server setup.

Next Steps

Explore marketplace: Visit https://github.com/anthropics/claude-code/tree/main/plugins

Try other plugins:

• code-review (alternative PR review)
• plugin-dev (if building custom plugins)

Build your own: Use /plugin-dev:create-plugin if you have a specific workflow to automate

Share feedback:

• GitHub issues for bug reports
• PRs for improvements
• Discussions for feature requests