Plugin Skills

Skills committed to a repository serve a single team. Managed settings serve a single organization. But some skills are universally useful — generating REST API boilerplate, scaffolding test suites, analyzing code quality, or integrating with specific frameworks. These skills belong in the plugin ecosystem, where they can be packaged, versioned, published, and installed by anyone.

What Are Agent Plugins?

An agent plugin is a packaged collection of skills distributed through standard package managers (npm, Git URLs) or private registries. Plugins are installed per-project or globally, and their skills become available to the agent just like locally defined skills. The plugin format adds structure around raw skills — metadata, versioning, documentation, and dependency management.

Plugins solve a distribution problem that repository skills and managed settings cannot: sharing skills across organizational boundaries. An open-source maintainer can publish a plugin that helps contributors follow the project's conventions. A framework author can publish a plugin that teaches the agent how to use their library. A consultancy can distribute best-practice skills to all their clients.

Plugin Directory Structure

A plugin follows a well-defined directory structure. At its core, it is a directory containing a manifest file and one or more skill directories:

The skills/ directory contains standard skill directories, each with a SKILL.md and any supporting files. The claude-plugin.json manifest provides metadata about the plugin, and package.json enables npm distribution.

The Plugin Manifest

The claude-plugin.json file is the heart of a plugin. It declares the plugin's identity, the skills it provides, any configuration it accepts, and compatibility requirements.

{
  "name": "claude-plugin-react-patterns",
  "version": "1.2.0",
  "description": "Opinionated React component patterns, hooks, and testing skills for Claude Code",
  "author": "React Patterns Team <plugins@example.com>",
  "license": "MIT",
  "claude": {
    "minVersion": "1.0.0"
  },
  "skills": [
    {
      "slug": "create-component",
      "name": "Create React Component",
      "description": "Scaffold a new React component with TypeScript, tests, and Storybook story",
      "path": "skills/create-component"
    },
    {
      "slug": "create-hook",
      "name": "Create Custom Hook",
      "description": "Create a custom React hook with proper TypeScript typing and unit tests",
      "path": "skills/create-hook"
    },
    {
      "slug": "add-test",
      "name": "Add Component Test",
      "description": "Add comprehensive React Testing Library tests for an existing component",
      "path": "skills/add-test"
    },
    {
      "slug": "performance-audit",
      "name": "Performance Audit",
      "description": "Analyze a React component tree for common performance issues and suggest fixes",
      "path": "skills/performance-audit"
    }
  ],
  "config": {
    "componentDir": {
      "description": "Default directory for new components",
      "default": "src/components"
    },
    "testFramework": {
      "description": "Testing framework to use",
      "enum": ["jest", "vitest"],
      "default": "vitest"
    },
    "storybook": {
      "description": "Whether to generate Storybook stories",
      "type": "boolean",
      "default": true
    }
  }
}

The skills array explicitly declares each skill the plugin provides. The config object defines user-configurable options that skills can reference via string substitutions. The claude.minVersion field ensures compatibility — if the user's agent version is too old to support a feature the plugin needs, installation warns them.

Packaging for npm

The most common distribution method is npm (or a private npm registry for internal plugins). The package.json bridges the plugin into the npm ecosystem:

{
  "name": "claude-plugin-react-patterns",
  "version": "1.2.0",
  "description": "React component patterns and testing skills for Claude Code",
  "keywords": [
    "claude-code-plugin",
    "claude-skills",
    "react",
    "typescript",
    "testing"
  ],
  "files": [
    "claude-plugin.json",
    "skills/**/*",
    "README.md",
    "LICENSE"
  ],
  "publishConfig": {
    "access": "public"
  }
}

The keywords array includes claude-code-plugin which makes the plugin discoverable through npm search. The files array ensures only the relevant files are included in the published package — no development artifacts, no build output.

Installing Plugins

Users install plugins through the agent's CLI. Plugins can be installed from npm, Git URLs, or local file paths:

When installed per-project, plugins are tracked in .claude/plugins.json, which should be committed to the repository so that all team members get the same plugins:

{
  "plugins": {
    "claude-plugin-react-patterns": {
      "version": "1.2.0",
      "source": "npm"
    },
    "claude-plugin-internal": {
      "version": "0.5.0",
      "source": "git",
      "url": "https://github.com/acme/claude-plugin-internal.git"
    }
  }
}

Authoring Your Own Plugin

Creating a plugin starts with writing skills, then wrapping them in the plugin structure. Here is the workflow from initial idea to published plugin:

Step 1: Develop Skills Locally

Start by writing your skills in a project's .claude/skills directory. Test them thoroughly in the context of a real project. Once you are confident they work well, extract them into a plugin.

Step 2: Scaffold the Plugin

Step 3: Test via Local Install

Before publishing, test the plugin by installing it from the local filesystem. This verifies that the manifest is correct and all skill paths resolve properly.

Step 4: Publish

# Ensure package.json has the right metadata
# Add claude-code-plugin to keywords for discoverability

# Publish to npm
$ npm publish

# Or publish to a private registry
$ npm publish --registry https://npm.internal.company.com

Plugin Configuration

Plugins can accept configuration from the project that installs them. Configuration values are defined in the plugin manifest's config section and set by the user in their project's .claude/plugins.json:

{
  "plugins": {
    "claude-plugin-react-patterns": {
      "version": "1.2.0",
      "source": "npm",
      "config": {
        "componentDir": "src/ui/components",
        "testFramework": "vitest",
        "storybook": false
      }
    }
  }
}

Inside skill files, these configuration values are accessible via string substitutions. The skill can reference $CONFIG.componentDir to use the project's configured component directory instead of hard-coding a path.

Private Plugin Registries

Organizations that want to share plugins internally without publishing to public npm can use private registries. The same npm infrastructure supports scoped packages and private hosting:

# .npmrc in the project root
@company:registry=https://npm.internal.company.com/

# Install a private scoped plugin
# claude plugin add @company/claude-plugin-internal-tools

This approach combines the distribution convenience of npm with the access control of a private registry. Only developers with registry credentials can install the plugin, making it suitable for proprietary skills that should not be publicly available.

What's Next

You have now covered the full spectrum of skill deployment — from sharing within a team via Git, to enterprise governance with managed settings, to public and private distribution through plugins. These three mechanisms give you the tools to get the right skills to the right people at every scale, from a solo developer to a global enterprise.