13.4 Plugins: Reusable Extension Packages

Course: Claude Code - Enterprise Development Section: Extending Claude Code Video Length: 3-4 minutes Presenter: Daniel Treasure

Opening Hook

"You've built subagents, hooks, and skills. Now, imagine packaging all of that—agents, skills, tools, hooks—into a single reusable bundle that any project can use. That's a plugin. Let me show you how to create one, install it, and why it's the foundation of shared functionality at enterprise scale."

Key Talking Points

1. What Is a Plugin?

What to say: "A plugin is a package of related Claude Code extensions. It bundles agents, skills, hooks, MCP server configs, and metadata into a single unit. Install a plugin once, and every project can access its agents and skills. Plugins live in a plugin directory—local, per-project, or cloud-hosted. They're version-controlled, shareable, and focused on one area of functionality."

What to show on screen: - Show plugin directory structure: /plugins or .claude/plugins - Show typical plugin contents: agents/, skills/, hooks.json, plugin.json (metadata) - List installed plugins with /plugins command - Show plugin marketplace: GitHub marketplace, file path, directory, npm package sources

2. One Plugin, One Focus

What to say: "Don't build a mega-plugin that does everything. Build focused plugins. A 'testing-framework' plugin has agents for test generation and validation, skills for running tests, hooks for linting. A 'security-scan' plugin has a security auditor agent and a vulnerability-check skill. Each plugin solves one clear problem. That makes it reusable, maintainable, and easy to disable if you don't need it."

What to show on screen: - Show directory of plugin marketplace with 10-20 plugins - Highlight: each plugin name describes its focus (testing, security, api-docs, database-migration) - Contrast: good (focused) vs. bad (generic "utilities" plugin with everything)

3. Plugin Metadata and Structure

What to say: "Every plugin has a plugin.json that describes it: name, version, description, dependencies, author. It declares which agents, skills, hooks, and MCP servers it provides. Claude Code reads this metadata on install to understand what functionality is being added. You can require specific models, enable/disable features per project, and manage dependencies between plugins."

What to show on screen: - Open plugin.json in a sample plugin - Show fields: name, version, description, author, license, dependencies (array of other plugins), provides (agents, skills, hooks, mcp) - Show how Claude Code displays this in /plugins list

4. Installing Plugins: From GitHub, Files, and Marketplaces

What to say: "Install a plugin from GitHub, a local directory, an npm package, or a custom URL. Each source type works slightly differently. GitHub and npm are great for open-source community plugins. Local directories are perfect for internal company tools. URLs work for custom deployments. Once installed, the plugin's agents and skills appear in your workspace automatically."

What to show on screen: - Demo /plugins → Browse Marketplace → search "testing" → click Install on a plugin - Show result: agents from plugin appear in agent list - Manually install from file: /plugins → Add from Path → select directory - Show enabled/disabled toggle for plugins

5. Plugin Development: From Idea to Install

What to say: "To build a plugin, create a directory with agents/, skills/, plugin.json, and optionally hooks and MCP configs. Version it with git. Push to GitHub, publish to npm, or keep it internal. Update plugin.json as you add features. Users install once and get updates automatically or on demand. You've now built infrastructure that scales across an entire team."

What to show on screen: - Create a new plugin directory locally - Add agents/ and skills/ subdirectories - Create plugin.json with metadata - Add an example AGENT.md to agents/ - Add an example SKILL.md to skills/ - Commit and push (or show the end state if time is tight)

Demo Plan

(0:30) Open /plugins command, show installed plugins and marketplace
(1:00) Click "Browse Marketplace," search for a category (e.g., "testing"), show available plugins
(1:30) Install a sample plugin from marketplace, watch agents/skills appear in lists
(2:00) Show plugin.json from an installed plugin, walk key fields
(2:30) Create a new plugin directory locally: mkdir my-plugin && add agents/, skills/, plugin.json
(3:00) Add a sample AGENT.md and SKILL.md to the plugin
(3:30) Install the local plugin: /plugins → Add from Path
(4:00) Verify agents/skills from new plugin appear and are usable

Code Examples & Commands

plugin.json metadata

{
  "name": "security-auditor",
  "version": "1.0.0",
  "description": "Security code review and vulnerability scanning agents and skills.",
  "author": "Acme Corp Security Team",
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://github.com/acme/claude-plugin-security-auditor.git"
  },
  "dependencies": [],
  "provides": {
    "agents": ["SecurityAuditor", "PenetrationTester"],
    "skills": ["ScanVulnerabilities", "AuditDependencies"],
    "hooks": true,
    "mcp": false
  },
  "minClaudeCodeVersion": "1.5.0"
}

Plugin directory structure

my-plugin/
├── plugin.json
├── agents/
│   └── CodeReviewer/
│       └── AGENT.md
├── skills/
│   ├── GenerateTests/
│   │   └── SKILL.md
│   └── ValidateSchema/
│       └── SKILL.md
├── hooks.json
└── README.md

Managing plugins via CLI

/plugins                           # List installed plugins
/plugins --refresh                 # Refresh from marketplace
/plugins search <keyword>          # Search marketplace
/plugins install <name>            # Install from marketplace
/plugins add-from-path <path>      # Install from local directory
/plugins remove <name>             # Uninstall plugin
/plugins enable <name>             # Enable a plugin
/plugins disable <name>            # Disable without removing

Example AGENT.md in plugin

---
name: CodeReviewer
description: "Reviews code for quality, best practices, and maintainability. Part of the Code Quality plugin."
tools: [Read, Bash, Grep]
model: sonnet
permissionMode: read-only
maxTurns: 8
---

You are a thorough code reviewer. When asked to review code:
1. Check for clarity and maintainability
2. Identify performance issues
3. Suggest refactoring with specific examples
4. Reference the codebase context

Be constructive. Explain the 'why' behind each suggestion.

Example SKILL.md in plugin

---
name: GenerateTests
description: "Generates unit tests for Python functions using pytest."
argument-hint: "<python-file>"
allowed-tools: [Read, Write, Bash]
user-invocable: true
model: sonnet
---

Generate comprehensive pytest tests for the functions in $ARGUMENTS[0].

Include:
- Unit tests for each function
- Edge case coverage
- Mock external dependencies
- Docstring-based test discovery

Output: test_*.py file in the same directory.

settings.json integration

{
  "enabledPlugins": [
    "security-auditor",
    "testing-framework",
    "api-docs-generator"
  ]
}

Gotchas & Tips

Plugin names should be unique. If two plugins provide agents with the same name, there's a conflict. Use namespacing if necessary (my-company-testing-utils vs. generic testing).

Dependencies between plugins are rare. Most plugins are independent. If Plugin A requires Plugin B, document it clearly in plugin.json. Users should install both.

Hooks in plugins apply globally. If your plugin defines hooks, they affect all tool use in that project, not just within the plugin's agents. This is powerful; use it carefully and document the side effects.

Plugin.json version is semantic versioning. Follow semver (1.0.0, 1.1.0, 2.0.0) so users understand breaking changes. Claude Code can auto-update or warn on major version bumps.

MCP servers in plugins. Advanced: plugins can include MCP server configs to extend functionality beyond Claude Code's built-in tools. This is the bridge to external systems (see Section 13.5).

Disable vs. remove. Disabling a plugin keeps it installed but inactive. Useful for testing or temporarily turning off a plugin. Removing deletes it. Prefer disable for iteration.

Plugin discovery. Users won't know your plugin exists unless you list it in a marketplace or share the GitHub URL. The built-in marketplace helps with discoverability.

Lead-out

"Plugins are how you distribute expertise. Build one plugin for testing, one for security, one for API documentation. Install them in projects that need them. In the final video, we'll go deeper: MCP Servers. They're how you bridge Claude Code to external systems—databases, APIs, third-party services. With plugins and MCP servers, you're not just extending Claude Code, you're building an entire enterprise AI platform."

Reference URLs

Claude Code Plugins documentation
Plugin.json schema reference
Plugin marketplace (GitHub Marketplace for Claude Code)
Publishing plugins to npm/GitHub

Prep Reading

Plugin best practices and patterns
Versioning and dependency management
Plugin security and permission scoping
Marketplace discovery and promotion

Notes for Daniel: Have a simple working plugin ready to install locally. The testing-framework or security-auditor examples work well. If you can show a real plugin from GitHub being installed from marketplace, that's impactful. Pre-create the plugin.json and sample AGENT.md/SKILL.md files so you don't spend time typing. Emphasize the focus principle—one plugin, one job—because that's the key to building a reusable ecosystem. If time allows, show an example of disabling vs. removing a plugin.

Quick Reference