Project 33: Plugin Architect - Build Distributable Extensions

Project 33: Plugin Architect - Build Distributable Extensions

Comprehensive Learning Guide Package Claude Code customizations into shareable, versioned plugins with hooks, skills, MCP servers, and output styles

Table of Contents

  1. Learning Objectives
  2. Deep Theoretical Foundation
  3. Complete Project Specification
  4. Real World Outcome
  5. Solution Architecture
  6. Phased Implementation Guide
  7. Testing Strategy
  8. Common Pitfalls & Debugging
  9. Extensions & Challenges
  10. Resources
  11. Self-Assessment Checklist

Learning Objectives

By completing this project, you will master:

  • Plugin Architecture Patterns: Understand how extensible systems discover, load, and coordinate plugins. Learn the patterns used by VS Code, webpack, ESLint, and other successful plugin ecosystems.

  • Package.json Claude Field Format: Master the structure of the claude field that declares hooks, skills, MCP servers, and output styles in a discoverable format.

  • Component Coordination: Learn how different plugin components (hooks, skills, MCP) interact and share state, and how to design them as cohesive units rather than isolated pieces.

  • Semantic Versioning for Plugins: Apply npm semver principles to plugin releases, understanding breaking changes, backward compatibility, and peer dependency declarations.

  • Plugin Distribution: Navigate the npm ecosystem for publishing, versioning, and discovery of Claude Code plugins.

  • Documentation-Driven Development: Write README and API documentation that enables other developers to use your plugin effectively.

Deep Theoretical Foundation

How Plugin Systems Work

Plugin systems enable extensibility without modifying core code. Understanding the universal patterns helps you design better plugins:

Plugin System Architecture
==========================

+-------------------+     +-------------------+     +-------------------+
|   Host Application|     |   Plugin Registry |     |   Plugin Package  |
|   (Claude Code)   |     |   (Discovery)     |     |   (Your Code)     |
|-------------------|     |-------------------|     |-------------------|
| 1. Init           |---->| 2. Scan for       |---->| 3. Return         |
|                   |     |    plugins        |     |    manifest       |
|                   |     |                   |     |                   |
| 6. Call plugin    |<----| 5. Return         |<----| 4. Register       |
|    methods        |     |    instances      |     |    components     |
+-------------------+     +-------------------+     +-------------------+

Plugin Lifecycle:
================
DISCOVERY --> REGISTRATION --> INITIALIZATION --> EXECUTION --> CLEANUP
    |              |                |                |              |
    v              v                v                v              v
Find package   Parse manifest   Create instances  Handle events  Graceful
.json files    (claude field)   Set up hooks      Run skills     shutdown

The Plugin Contract: Every plugin system defines a contract - the interface between host and plugin:

Contract Elements:
=================

1. MANIFEST FORMAT (package.json claude field)
   - What components exist
   - Where they are located
   - Configuration options

2. COMPONENT INTERFACES
   - Hook: (event) => { decision, message }
   - Skill: markdown file with SKILL.md format
   - MCP Server: stdio/SSE transport protocol
   - Output Style: markdown with personality/behavior

3. LIFECYCLE EVENTS
   - onInstall: First-time setup
   - onLoad: Each session start
   - onUnload: Session end
   - onUninstall: Cleanup

4. COMMUNICATION CHANNELS
   - Hooks receive event objects
   - Skills receive user prompts
   - MCP receives tool calls
   - All can read/write files

Reference: “Building Extensible Applications” by Dustin Diaz, Chapters 4-5 cover extension point design and plugin loading patterns.

The package.json Claude Field Schema

The claude field is the manifest that declares all plugin components:

claude Field Structure:
======================

{
  "claude": {
    // HOOKS: Event handlers that intercept Claude behavior
    "hooks": [
      "./hooks/pre-tool.ts",      // Relative path to hook file
      "./hooks/post-tool.ts"
    ],

    // SKILLS: Slash commands and capabilities
    "skills": [
      "./skills/main-skill.md",   // Skill definition file
      "./skills/helper-skill.md"
    ],

    // MCP SERVERS: External tools and data sources
    "mcpServers": {
      "server-name": {
        "command": "node",        // Executable
        "args": ["./mcp/server.js"],
        "env": {                  // Optional environment
          "API_KEY": "${PLUGIN_API_KEY}"
        }
      }
    },

    // OUTPUT STYLES: Personality and behavior modifications
    "outputStyles": {
      "style-name": "./styles/custom.md"
    },

    // CONFIGURATION: Plugin settings schema (optional)
    "config": {
      "schema": "./config-schema.json"
    }
  }
}

How Claude Code Discovers Plugins:

Discovery Process:
==================

1. USER INSTALLS PLUGIN
   npm install @yourname/claude-code-plugin

2. CLAUDE CODE SCANS node_modules
   for each package in node_modules:
     if package.json has "claude" field:
       register as plugin

3. PLUGIN REGISTRATION
   - Validate manifest against schema
   - Resolve relative paths
   - Check for conflicts with existing plugins
   - Register hooks, skills, MCP servers, styles

4. COMPONENT LOADING
   - Hooks: Import and register event handlers
   - Skills: Parse markdown and register commands
   - MCP: Start server processes
   - Styles: Add to available style list

Discovery Locations (in order of precedence):
============================================
1. Project: ./node_modules/*/package.json
2. User: ~/.claude/plugins/*/package.json
3. Global: $CLAUDE_PLUGINS_DIR/*/package.json

Component Coordination Within Plugins

A well-designed plugin coordinates its components to work as a cohesive unit:

Plugin Component Interaction:
============================

Example: Security Plugin
========================

+-------------------+
|   User invokes    |
|   /security-review|
+--------+----------+
         |
         v
+-------------------+      +-------------------+
|   Skill: Review   |----->|   MCP: CVE API    |
|   (orchestrates)  |      |   (lookups)       |
+--------+----------+      +-------------------+
         |
         v
+-------------------+      +-------------------+
|   Hook: Pre-Write |<-----|   Shared: Config  |
|   (validates)     |      |   (settings.json) |
+-------------------+      +-------------------+

Data Flow:
==========
1. Skill receives /security-review command
2. Skill calls MCP server for CVE data
3. Skill analyzes code against CVE database
4. Hook intercepts Write tool to validate changes
5. All components read from shared config

Shared State Patterns:

// Pattern 1: Configuration File
// All components read from a shared config
const config = JSON.parse(
  fs.readFileSync(path.join(__dirname, '../config.json'))
);

// Pattern 2: Environment Variables
// Set during MCP server startup
"mcpServers": {
  "my-server": {
    "env": { "PLUGIN_MODE": "strict" }
  }
}

// Pattern 3: File-Based Communication
// Components write to a shared file
const state = {
  lastScan: new Date().toISOString(),
  findings: []
};
fs.writeFileSync('.plugin-state.json', JSON.stringify(state));

Reference: “JavaScript: The Good Parts” by Douglas Crockford, Chapter 5 discusses module patterns that inform plugin component design.

Semantic Versioning for Plugins

Plugins must follow semver to communicate compatibility:

Semantic Versioning:
===================

MAJOR.MINOR.PATCH
  |     |     |
  |     |     +-- Bug fixes, no API changes
  |     |         "1.0.0 -> 1.0.1"
  |     |
  |     +-------- New features, backward compatible
  |               "1.0.0 -> 1.1.0"
  |
  +-------------- Breaking changes
                  "1.0.0 -> 2.0.0"

For Plugins, "Breaking Changes" means:
=====================================
- Renamed or removed skills
- Changed hook event format
- Modified MCP server interface
- Incompatible configuration changes

Example Version History:
=======================
1.0.0 - Initial release
        - /security-review skill
        - secret-detector hook

1.1.0 - Added /cve-check skill
        - No breaking changes

1.2.0 - Added nvd-api MCP server
        - Enhanced /security-review

2.0.0 - BREAKING: Renamed /security-review to /audit
        - BREAKING: Changed config format
        - Added migration guide

Peer Dependencies: Declare Claude Code version compatibility:

{
  "name": "@yourname/claude-plugin",
  "version": "1.0.0",
  "peerDependencies": {
    "claude-code": ">=1.0.0 <2.0.0"
  },
  "peerDependenciesMeta": {
    "claude-code": {
      "optional": false
    }
  }
}

Reference: semver.org documentation provides the authoritative specification.

Complete Project Specification

Functional Requirements

Core Features (Must Have):

Feature Description Priority
Plugin manifest Valid package.json with claude field P0
At least 2 hooks PreToolUse and PostToolUse hooks P0
At least 2 skills Primary skill and helper skill P0
MCP server One functional MCP server P0
Output style One custom output style P0
README documentation Installation and usage guide P0
npm publishable Valid package structure P1
Configuration User-configurable settings P1
Tests Unit and integration tests P1
Migration guide For breaking changes P2

Plugin Structure Requirements:

my-claude-plugin/
+-- package.json           # Plugin manifest with claude field
+-- README.md              # User documentation
+-- LICENSE                # License file
+-- CHANGELOG.md           # Version history
+-- hooks/
|   +-- pre-tool.ts        # PreToolUse hook
|   +-- post-tool.ts       # PostToolUse hook
+-- skills/
|   +-- main-skill.md      # Primary skill definition
|   +-- helper-skill.md    # Supporting skill
+-- mcp/
|   +-- server.ts          # MCP server implementation
|   +-- tools.ts           # Tool definitions
|   +-- types.ts           # Shared types
+-- styles/
|   +-- custom.md          # Output style definition
+-- config/
|   +-- defaults.json      # Default configuration
|   +-- schema.json        # Configuration schema
+-- tests/
|   +-- hooks.test.ts      # Hook tests
|   +-- skills.test.ts     # Skill tests
|   +-- mcp.test.ts        # MCP server tests
+-- dist/                  # Compiled output

Real World Outcome

You’ll have a distributable security-focused plugin:

package.json:

{
  "name": "@yourname/claude-code-security-plugin",
  "version": "1.0.0",
  "description": "Security-focused Claude Code plugin with secret detection, dependency scanning, and secure coding guidance",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "keywords": [
    "claude-code",
    "claude-code-plugin",
    "security",
    "secret-detection"
  ],
  "claude": {
    "hooks": [
      "./dist/hooks/secret-detector.js",
      "./dist/hooks/dependency-scanner.js"
    ],
    "skills": [
      "./skills/security-review.md",
      "./skills/cve-check.md"
    ],
    "mcpServers": {
      "nvd-api": {
        "command": "node",
        "args": ["./dist/mcp/nvd-server.js"],
        "env": {
          "NVD_API_KEY": "${NVD_API_KEY}"
        }
      }
    },
    "outputStyles": {
      "security-focused": "./styles/security.md"
    }
  },
  "peerDependencies": {
    "claude-code": ">=1.0.0"
  },
  "scripts": {
    "build": "tsc",
    "test": "vitest",
    "prepublishOnly": "npm run build && npm test"
  }
}

Installation and Usage:

# Install the plugin
npm install @yourname/claude-code-security-plugin

# Claude automatically discovers and loads:
# - Hooks that scan for secrets in staged files
# - Skills that run security reviews on demand
# - MCP server for CVE lookups
# - Output style for security-focused responses

# Set required environment variable
export NVD_API_KEY=your-api-key

# User invokes skill
/security-review src/auth/

# Result includes:
# +------------------------------------------------------------+
# |              SECURITY REVIEW REPORT                         |
# +------------------------------------------------------------+
# | Files Scanned: 12                                           |
# | Duration: 3.2s                                              |
# +------------------------------------------------------------+
# |                                                             |
# | SECRETS SCAN                                                |
# | ============                                                |
# | Status: PASSED                                              |
# | No hardcoded secrets found                                  |
# |                                                             |
# | DEPENDENCY AUDIT                                            |
# | ================                                            |
# | WARNING: 2 dependencies with known CVEs                     |
# |                                                             |
# | lodash@4.17.15                                              |
# |   CVE-2021-23337 (High) - Prototype Pollution               |
# |   Fix: npm update lodash                                    |
# |                                                             |
# | axios@0.21.0                                                |
# |   CVE-2021-3749 (Medium) - ReDoS vulnerability              |
# |   Fix: npm update axios                                     |
# |                                                             |
# | CODE PATTERNS                                               |
# | =============                                               |
# | 3 security recommendations:                                 |
# | - Line 45: Consider using parameterized queries             |
# | - Line 89: Add input validation for user data               |
# | - Line 156: Use crypto.randomUUID() instead of Math.random()|
# |                                                             |
# +------------------------------------------------------------+

Solution Architecture

System Architecture Diagram

+------------------------------------------------------------------+
|                    CLAUDE CODE SECURITY PLUGIN                    |
+------------------------------------------------------------------+
|                                                                   |
|  +------------------+     +------------------+     +-----------+  |
|  |     Hooks        |     |     Skills       |     |    MCP    |  |
|  |------------------|     |------------------|     |-----------|  |
|  | - Secret detect  |     | - /security-     |<--->| - NVD API |  |
|  | - Dep scanner    |     |   review         |     |   queries |  |
|  |                  |     | - /cve-check     |     |           |  |
|  +--------+---------+     +--------+---------+     +-----+-----+  |
|           |                        |                     |        |
|           v                        v                     v        |
|  +---------------------------------------------------------------+|
|  |                    SHARED CONFIGURATION                       ||
|  |---------------------------------------------------------------|
|  | - Severity thresholds                                         ||
|  | - Ignore patterns                                             ||
|  | - API endpoints                                               ||
|  +---------------------------------------------------------------+|
|           |                        |                     |        |
|           v                        v                     v        |
|  +------------------+     +------------------+     +-----------+  |
|  |  Output Style    |     |   File System    |     |  Network  |  |
|  |------------------|     |------------------|     |-----------|  |
|  | - Security tone  |     | - Read source    |     | - CVE API |  |
|  | - Alert format   |     | - Scan deps      |     | - GitHub  |  |
|  +------------------+     +------------------+     +-----------+  |
|                                                                   |
+------------------------------------------------------------------+

Data Flow Diagram

User Request                  Plugin Processing                Output
============                  =================                ======

/security-review
src/auth/
      |
      v
+-------------+
| Skill Parse |
| (args)      |
+------+------+
       |
       v
+-------------+    +--------+    +-------------+
| File System |--->| Scan   |--->| Secret      |
| (read files)|    | Engine |    | Patterns    |
+-------------+    +---+----+    +-------------+
                       |
                       v
              +--------+--------+
              |                 |
              v                 v
       +-------------+   +------------+
       | Dependency  |   | Code       |
       | Scanner     |   | Analyzer   |
       +------+------+   +------+-----+
              |                 |
              v                 v
       +-------------+   +------------+
       | MCP: NVD    |   | Pattern    |
       | API Lookup  |   | Database   |
       +------+------+   +------+-----+
              |                 |
              +--------+--------+
                       |
                       v
              +--------+--------+
              | Report          |
              | Generator       |-----> Formatted
              | (output style)  |       Output
              +-----------------+

Module Breakdown

src/
+-- index.ts              # Plugin entry point (if needed)
+-- hooks/
|   +-- secret-detector.ts
|   |   +-- PATTERNS: Regex for secrets
|   |   +-- scanFile(): Check file for secrets
|   |   +-- handler(): PreToolUse handler
|   |
|   +-- dependency-scanner.ts
|       +-- parsePackageJson(): Extract deps
|       +-- checkVulnerabilities(): Call MCP
|       +-- handler(): PostToolUse handler
|
+-- skills/
|   +-- security-review.md
|   |   +-- Description and triggers
|   |   +-- Orchestration instructions
|   |
|   +-- cve-check.md
|       +-- Single-package CVE lookup
|       +-- Usage examples
|
+-- mcp/
|   +-- nvd-server.ts
|   |   +-- MCP server implementation
|   |   +-- Tool: query_cves
|   |   +-- Tool: get_advisory
|   |
|   +-- tools.ts
|   |   +-- Tool schemas
|   |   +-- Tool handlers
|   |
|   +-- nvd-client.ts
|       +-- NVD API wrapper
|       +-- Rate limiting
|       +-- Caching
|
+-- styles/
|   +-- security.md
|       +-- Security-focused personality
|       +-- Alert formatting guidelines
|
+-- config/
|   +-- defaults.json
|   +-- schema.json
|
+-- types/
    +-- index.ts
        +-- Plugin configuration types
        +-- Hook event types
        +-- MCP tool types

Phased Implementation Guide

Phase 1: Plugin Skeleton (Day 1-2)

Goal: Create a valid plugin structure with one working hook.

Milestone: Plugin installs via npm link and hook fires on file writes.

Tasks:

  1. Project Setup 
    mkdir claude-security-plugin && cd claude-security-plugin
npm init -y
npm install -D typescript @types/node vitest
npx tsc --init
  2. Configure package.json 
    {
  "name": "@yourname/claude-code-security-plugin",
  "version": "0.1.0",
  "claude": {
    "hooks": ["./dist/hooks/secret-detector.js"]
  }
}
  3. Create First Hook (src/hooks/secret-detector.ts)
    • Implement PreToolUse handler
    • Check for Write tool
    • Scan content for secret patterns
    • Return block or continue decision
  4. Test with npm link 
    npm run build
npm link
# In a test project:
npm link @yourname/claude-code-security-plugin

Success Criteria: Hook detects and warns about hardcoded API keys.

Phase 2: Add Skills (Day 3-4)

Goal: Create skills that orchestrate security reviews.

Milestone: /security-review skill runs complete analysis.

Tasks:

  1. Create Main Skill (skills/security-review.md) ```markdown — description: Comprehensive security review of code triggers:
    • security review

    • audit security

    Security Review Skill

    When invoked, perform these steps:

    1. Scan target files for secrets
    2. Check dependencies for CVEs
    3. Analyze code patterns
    4. Generate formatted report ```
  2. Create Helper Skill (skills/cve-check.md)
    • Single-package vulnerability lookup
    • Integration with MCP server
  3. Update package.json 
    "claude": {
  "hooks": [...],
  "skills": [
    "./skills/security-review.md",
    "./skills/cve-check.md"
  ]
}

Success Criteria: Skills appear in Claude Code and execute correctly.

Phase 3: MCP Server (Day 5-6)

Goal: Create MCP server for CVE lookups.

Milestone: Skills can query NVD API through MCP.

Tasks:

  1. Create MCP Server (src/mcp/nvd-server.ts)
    • Implement MCP stdio transport
    • Define query_cves tool
    • Define get_advisory tool
  2. Implement NVD Client (src/mcp/nvd-client.ts)
    • API wrapper with rate limiting
    • Response caching
    • Error handling
  3. Update package.json 
    "claude": {
  ...
  "mcpServers": {
    "nvd-api": {
      "command": "node",
      "args": ["./dist/mcp/nvd-server.js"]
    }
  }
}

Success Criteria: MCP server starts and responds to tool calls.

Phase 4: Output Style & Polish (Day 7)

Goal: Add output style and finalize documentation.

Milestone: Complete, publishable plugin.

Tasks:

  1. Create Output Style (styles/security.md)
    • Security-focused personality
    • Severity formatting
    • Actionable recommendations
  2. Write README
    • Installation instructions
    • Configuration options
    • Usage examples
    • Troubleshooting
  3. Add Tests
    • Hook unit tests
    • MCP integration tests
    • Skill validation tests
  4. Publish Preparation 
    npm run build
npm test
npm publish --dry-run

Success Criteria: npm publish --dry-run succeeds with no errors.

Testing Strategy

Unit Tests: Hook Logic

// tests/hooks/secret-detector.test.ts
import { describe, it, expect } from 'vitest';
import { scanForSecrets } from '../../src/hooks/secret-detector';

describe('secret-detector', () => {
  it('detects AWS access keys', () => {
    const content = 'const key = "AKIAIOSFODNN7EXAMPLE";';
    const findings = scanForSecrets(content);

    expect(findings).toHaveLength(1);
    expect(findings[0].type).toBe('aws_access_key');
  });

  it('detects GitHub tokens', () => {
    const content = 'const token = "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx";';
    const findings = scanForSecrets(content);

    expect(findings).toHaveLength(1);
    expect(findings[0].type).toBe('github_token');
  });

  it('ignores false positives', () => {
    const content = 'const placeholder = "your-api-key-here";';
    const findings = scanForSecrets(content);

    expect(findings).toHaveLength(0);
  });

  it('returns line numbers for findings', () => {
    const content = `line 1
    const key = "AKIAIOSFODNN7EXAMPLE";
    line 3`;
    const findings = scanForSecrets(content);

    expect(findings[0].line).toBe(2);
  });
});

Integration Tests: MCP Server

// tests/mcp/nvd-server.test.ts
import { describe, it, expect, beforeAll, afterAll } from 'vitest';
import { spawn } from 'child_process';

describe('nvd-api MCP server', () => {
  let server: ChildProcess;

  beforeAll(async () => {
    server = spawn('node', ['./dist/mcp/nvd-server.js']);
    await new Promise(resolve => setTimeout(resolve, 1000));
  });

  afterAll(() => {
    server.kill();
  });

  it('responds to tool list request', async () => {
    // Send tools/list request via stdin
    const response = await sendMcpRequest(server, {
      jsonrpc: '2.0',
      id: 1,
      method: 'tools/list'
    });

    expect(response.result.tools).toContainEqual(
      expect.objectContaining({ name: 'query_cves' })
    );
  });

  it('queries CVE database', async () => {
    const response = await sendMcpRequest(server, {
      jsonrpc: '2.0',
      id: 2,
      method: 'tools/call',
      params: {
        name: 'query_cves',
        arguments: { package: 'lodash', version: '4.17.15' }
      }
    });

    expect(response.result.content[0].text).toContain('CVE');
  });
});

Skill Validation Tests

// tests/skills/validation.test.ts
import { describe, it, expect } from 'vitest';
import { readFileSync } from 'fs';
import { parse } from 'yaml';

describe('skill definitions', () => {
  it('security-review.md has valid frontmatter', () => {
    const content = readFileSync('./skills/security-review.md', 'utf-8');
    const frontmatter = content.match(/^---\n([\s\S]*?)\n---/)?.[1];

    expect(frontmatter).toBeDefined();

    const meta = parse(frontmatter!);
    expect(meta.description).toBeDefined();
    expect(meta.triggers).toBeInstanceOf(Array);
  });

  it('cve-check.md has valid frontmatter', () => {
    const content = readFileSync('./skills/cve-check.md', 'utf-8');
    const frontmatter = content.match(/^---\n([\s\S]*?)\n---/)?.[1];

    expect(frontmatter).toBeDefined();
  });
});

Common Pitfalls & Debugging

Pitfall 1: Relative Path Resolution

Symptom: Plugin components not found after npm install.

Bad:

{
  "claude": {
    "hooks": ["src/hooks/detector.ts"]  // Source file, not built!
  }
}

Good:

{
  "claude": {
    "hooks": ["./dist/hooks/detector.js"]  // Compiled output
  }
}

Debug: Check that paths in claude field point to files in your files array:

{
  "files": ["dist", "skills", "styles"]
}

Pitfall 2: MCP Server Environment Variables

Symptom: MCP server fails to start or returns API errors.

Bad:

{
  "mcpServers": {
    "nvd-api": {
      "command": "node",
      "args": ["./dist/mcp/server.js"]
      // No env - API key missing!
    }
  }
}

Good:

{
  "mcpServers": {
    "nvd-api": {
      "command": "node",
      "args": ["./dist/mcp/server.js"],
      "env": {
        "NVD_API_KEY": "${NVD_API_KEY}"  // Reference user's env var
      }
    }
  }
}

Pitfall 3: Hook Return Format

Symptom: Hooks silently fail or don’t affect Claude behavior.

Bad:

// Returning wrong format
export default function handler(event) {
  return false;  // Wrong type!
}

Good:

// Correct format
export default function handler(event) {
  return {
    decision: 'block',  // or 'continue'
    reason: 'Security violation detected'
  };
}

Pitfall 4: Skill Not Appearing

Symptom: Skill doesn’t show up in Claude Code’s skill list.

Debug Checklist:

  1. Is the skill file in the files array in package.json?
  2. Does the skill have valid YAML frontmatter?
  3. Is the path in claude.skills correct?
  4. Did you reinstall/relink the plugin?
# Verify skill file is included
npm pack --dry-run | grep skills

Pitfall 5: Version Conflicts

Symptom: Plugin works locally but fails after npm install.

Debug: Check for peer dependency mismatches:

npm ls @yourname/claude-code-security-plugin

Fix: Add proper peer dependencies:

{
  "peerDependencies": {
    "claude-code": ">=1.0.0"
  }
}

The Interview Questions They’ll Ask

Prepare to answer these:

  1. “How would you design a plugin system that supports hot-reloading?”
    • File watchers on plugin directories
    • Unload/reload cycle without restarting host
    • State preservation during reload
    • Version compatibility checks
  2. “What’s your strategy for handling breaking changes across plugin versions?”
    • Semver compliance
    • Deprecation warnings before removal
    • Migration scripts or codemods
    • Changelog documentation
    • Beta channel for testing
  3. “How do you ensure plugins don’t conflict with each other?”
    • Namespaced skill commands
    • Hook priority/ordering system
    • Isolated MCP server processes
    • Configuration scoping
  4. “What security considerations apply to third-party plugins?”
    • Code review and auditing
    • Permission model (what can plugins access?)
    • Sandboxing capabilities
    • Signed/verified plugins
    • User consent for sensitive operations
  5. “How would you build a plugin marketplace/registry?”
    • npm as distribution mechanism
    • Metadata aggregation service
    • Search and discovery UI
    • User ratings and reviews
    • Compatibility matrix

Hints in Layers

Hint 1: Start Minimal Begin with a single hook, get it working, then add more components. Don’t try to build everything at once.

Hint 2: The claude Field The claude field in package.json is where all the magic happens. Study existing plugins and the schema carefully.

Hint 3: Testing with npm link Use npm link to test your plugin locally before publishing. This creates a symlink in your test project.

Hint 4: Documentation A good README is the difference between adoption and abandonment. Document every feature, every configuration option, every troubleshooting step.

Books That Will Help

Topic Book Chapter
Plugin patterns “Building Extensible Applications” by Dustin Diaz Ch. 4-5: Extension points, plugin loading
Package publishing “npm Cookbook” by O’Reilly Ch. 3: Publishing and versioning
Extension design “Programming TypeScript” by Boris Cherny Ch. 9: Advanced patterns
Module patterns “JavaScript: The Good Parts” by Douglas Crockford Ch. 5: Module patterns
API design “RESTful Web APIs” by Richardson & Amundsen Ch. 8: Hypermedia and extensibility

Extensions & Challenges

Extension 1: Plugin Generator CLI

Build a CLI that scaffolds new Claude Code plugins:

npx create-claude-plugin my-plugin
# Interactive prompts for components
# Generates full project structure

Extension 2: Plugin Compatibility Checker

Create a tool that validates plugins against Claude Code versions:

npx claude-plugin-check @yourname/plugin
# Checks all components load correctly
# Validates against installed Claude Code version

Extension 3: Plugin Analytics

Add telemetry to track plugin usage:

// Track skill invocations
// Track hook executions
// Track MCP tool calls
// Respect user privacy

Self-Assessment Checklist

Conceptual Understanding

  • Can you explain the plugin discovery process to a colleague?
  • Can you describe what data goes in the claude field?
  • Can you explain how hooks, skills, and MCP servers coordinate?
  • Can you list the lifecycle events of a plugin?
  • Can you explain semantic versioning for plugins?

Implementation Skills

  • Can you create a valid package.json with claude field?
  • Can you implement a PreToolUse hook?
  • Can you write a skill definition file?
  • Can you create an MCP server with tools?
  • Can you write an output style?

Plugin Quality

  • Does your plugin have a comprehensive README?
  • Does your plugin have tests for all components?
  • Does your plugin follow semver?
  • Does your plugin handle errors gracefully?
  • Is your plugin publishable to npm?

Code Quality

  • Is your code organized into logical modules?
  • Are types properly defined?
  • Are async operations properly handled?
  • Is configuration externalized?
  • Can another developer extend your plugin?

The Core Question You’ve Answered

“How do you package related Claude Code customizations into a single, shareable unit?”

Plugins solve the problem of “I have 5 hooks, 3 skills, and an MCP server that work together - how do I give this to my team?” The plugin format provides a standard answer.

By building this plugin, you have mastered:

  1. Plugin Architecture: How to design extensible systems
  2. Component Coordination: How to make hooks, skills, and MCP work together
  3. Distribution: How to package and publish for others
  4. Documentation: How to enable adoption through clear documentation

You are now ready to build and share sophisticated Claude Code extensions with the community.

Project Guide Version 1.0 - December 2025