Creating a Claude Code Plugin and sharing it with your team

Introduction

More than half a year has passed since Claude Code was officially released.
While it has become commonplace to use it daily,
various challenges have also emerged.

Context Problems

• Explaining specialized knowledge (coding conventions, review perspectives, domain knowledge) in prompts every time is cumbersome (consuming many tokens)
• Want to execute multiple specialized tasks simultaneously, but they don't fit in the context window and compact runs frequently

Inefficient Task Processing

• Detailed work causes the main conversation to go off track, losing sight of the original goal
• Sequential processing of multiple specialized tasks takes time
• Granting unnecessary permissions for tasks

Difficult to Share and Standardize Settings

• Inefficiency due to different settings for each team member
• Copying and pasting the same settings across multiple repositories
• Distribution and maintenance of best practices is troublesome

Three features of Claude Code can help solve these challenges.

In this article, I'll explain how to create a simple Skill & Subagent,
package them as a Plugin, and share them with your team.

The Claude Code plugin created for this article is available here.

Claude Code Skills

Overview

First, let me briefly explain Skills.
Claude Code Skills are packages of reusable specialized knowledge that include task instructions and executable code.
They're like an organizational system that extracts necessary expertise when needed, in the amount needed,
similar to a librarian who listens to your question and brings you exactly the relevant books.

Skills features are:

• Automatic detection: Automatically identifies Skills related to tasks
• Gradual loading: Loads only the minimum necessary information
• Executable code: Can include arbitrary scripts

The gradual loading of Skills is implemented in three stages,
allowing efficient use of the context window:

With this design, even if hundreds of Skills are available simultaneously,
only metadata resides in memory, reducing pressure on the context window.

Directory Structure

Here is the Skills configuration.
Place them in directories as follows:

# Global (used by all projects)
~/.claude/skills/your-skill-name/
├── SKILL.md (required)
└── (other support files)

# Project-specific
<your project>/.claude/skills/your-skill-name/
├── SKILL.md (required)
└── (other support files)

If the Skill is common across multiple projects, create it under ~/.claude/skills.
If it's for a specific project, create it in the project directory's .claude/skills.

When sharing with a team, it's best to place it in the project directory
and manage it with Git or similar.

SKILL.md Structure

SKILL.md is a required file for Skills and consists of YAML front matter and
Markdown-formatted content.

---
name: skill-name
description: |
  Description of the skill. When to use it.
  Simply describe triggering phrases and use cases.
---

# Skill Documentation

## Instructions
Procedures and guidelines

## Examples
Concrete usage examples

Both the skill name and description are required.
The description explains the skill and
provides information for Claude to determine when to use this skill.

Claude Code Subagent

Overview

Claude Code Subagent is a specialized AI assistant that
autonomously executes specific tasks.
Its key feature is having a context window independent from the main conversation,
operating with dedicated tool access and system prompt.

Features include:

• Independent context: Completely separate context window from the main conversation
• Selective tool access: Can be limited to only necessary tools
• Parallel execution: Multiple Subagents can be executed simultaneously

Subagents can be defined for specific domain-specialized roles, and multiple can operate in parallel
with only necessary permissions, each working in their independent context.
Therefore, Subagents with roles such as reviewer, tester, documentation creator, and implementer
can work simultaneously in their respective contexts.

Directory Structure

Here is the Subagent configuration.
Similar to Skills, but Subagents are complete in a single file.
※Additional scripts or templates can be placed in the same directory as needed

# Global (used by all projects)
~/.claude/agents/agent-name.md

# Project-specific
<project-root>/.claude/agents/agent-name.md

# Via Plugin
<plugin>/agents/agent-name.md

Subagent Definition File Structure

Subagents are defined in .md files as follows.
The agent name is required and can only use lowercase letters and hyphens.
The description is also required, explaining when to use it.
The skills section lists Skills to be loaded automatically.

---
name: agent-name
description: When and why to use this Subagent
tools: Read, Grep, Glob, Bash  # optional
model: sonnet  # optional
skills: skill1, skill2  # optional (Skills to be loaded automatically)
---

System prompt for the Subagent.
Describe role, capabilities, specific instructions...

Skills and Subagents

While Skills and Subagents have commonalities,
their purposes and functions differ.

Skills specialize in "providing knowledge," which the main Claude references automatically when needed.
Subagents specialize in "executing tasks," operating autonomously in an independent context.

Skills and Subagents can work together.
You can use Skills within the "independent execution environment" of Subagents.

Subagent A (Programmer) → Skill-1 (TS programming)
Subagent B (Tester) → Skill-2 (Test execution)
Subagent C (AWS Architect) → Skill-1 (TS programming), Skill-3 (AWS system building)

With Skills' gradual loading feature,
each Subagent efficiently loads only the knowledge it needs.

Additionally, multiple Subagents can run in parallel.
For example, when a user requests "build a system using AWS,"
Claude will automatically try to orchestrate multiple Subagents (if defined) to execute the process.

Claude Code Plugin

Overview

Claude Code Plugin is a mechanism for packaging and
distributing the following features:

• Slash Command: Shortcuts for frequently used operations
• Subagent: Agents built for specialized development tasks
• MCP Server: Connection to tools and data sources via MCP protocol
• Hook: Customize Claude Code's behavior at arbitrary times (e.g., before Tool execution)
• Skill: Packages of specialized knowledge

Plugin Directory Structure

The structure of a Plugin is as follows.
Only plugin.json is required.
Other features can be combined and placed according to requirements.

my-plugin/
├── plugin.json           # Plugin configuration (required)
├── README.md             # Description (recommended)
├── commands/             # Slash commands
│   └── my-command.md
├── agents/               # Subagents
│   └── my-agent.md
├── skills/               # Skills
│   └── my-skill/
│       └── SKILL.md
├── mcp-servers/          # MCP server configuration
│   └── config.json
└── hooks/                # Hook configuration
    └── hooks.json

About plugin.json

Here's the content of plugin.json, which is required.
name, version, and description are mandatory.

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "Plugin description",
  "author": "Author name",
  "repository": "https://github.com/hoge/fuga",
  "license": "MIT",
  "keywords": ["code-review", "security"]
}

Create MarketPlace & Plugin

Let's create a Plugin for Database Migration that includes
Skill, Subagent, Command, Hook, and MCP server.
We'll create a sample plugin called "Automate migration management with SQLite3".

1: Create marketplace and Plugin directory

First, let's create a marketplace structure locally.
A marketplace in Claude Code plugins is
a mechanism for cataloging multiple plugins for collective distribution and management.
Teams and communities can create their own marketplaces,
with flexible sources including GitHub and local paths.

For a single plugin, you can install directly by specifying a GitHub repository
without using a marketplace.

% mkdir -p ~/dev-marketplace/plugins/database-migration-plugin
% cd ~/dev-marketplace/plugins/database-migration-plugin

# Directories for each component
% mkdir -p skills/migration-best-practices
% mkdir -p agents commands hooks scripts db migrations

2: Create a Skill

Create a Skill defining database migration best practices as
skills/migration-best-practices/SKILL.md
(This is a sample generated by AI)

---
name: migration-best-practices
description: |
  Database migration best practices.
  Automatically applied when schema changes.
---

# Database Migration Best Practices

## Naming Conventions

- File name: `YYYYMMDDHHMMSS_description.sql`
- Example: `20250121120000_add_user_email.sql`

## Migration Rules

### UP Migration (Apply)
- Always execute within a transaction
- Be careful with `NOT NULL` constraints when adding columns (set default values)
- Create indexes gradually for large tables

### DOWN Migration (Rollback)
- Always prepare DOWN corresponding to every UP
- Warning comments required for changes that may cause data loss

## Prohibitions

- Modifying existing migration files is prohibited
- Executing DDL directly in production environment is prohibited
- Data confirmation required before column deletion

3: Create a Subagent

Create a Subagent that uses the above Skill to plan and generate migrations,
agents/migration-planner.md:

---
name: migration-planner
description: Safely plan database schema changes. Used when requesting migration creation.
tools: Read, Write, Grep, Glob, Bash
model: sonnet
skills: migration-best-practices
---

You are a database architect.
Please plan safe migrations according to the migration-best-practices Skill.

## Migration Generation Procedure

1. Check existing schema (files in migrations/ directory)
2. Analyze the impact of changes
3. Generate UP/DOWN following the rules in migration-best-practices Skill
4. Save with timestamp filename

## Notes

- Include warnings for destructive changes (column deletion, type changes)
- Pay attention to foreign key constraint order
- Recommended to separate index creation into separate migrations

4: Create a Command

Next, create a custom slash command (commands/migrate.md).
This command generates migration files.

---
description: Generate database migration files
---

Use the migration-planner agent to generate a migration file for the following changes.

Changes:
$ARGUMENTS

Output destination: migrations/ directory

5: Create a Hook

Create a Hook (hooks/hooks.json) that displays a confirmation prompt before executing migrations.
$CLAUDE_PLUGIN_ROOT is an environment variable indicating the plugin's root directory.

{
  "description": "Migration safety check hook",
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/migration-check.sh",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Then, create a script for the Hook (scripts/migration-check.sh).
JSON-formatted tool information is passed to the Hook via stdin.

#!/bin/bash

# Read JSON from stdin
INPUT=$(cat)

# Extract file_path using jq (or grep as alternative if jq is not available)
if command -v jq &> /dev/null; then
    FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
else
    FILE_PATH=$(echo "$INPUT" | grep -o '"file_path":"[^"]*"' | cut -d'"' -f4)
fi

# Check if it's a migration file
if echo "$FILE_PATH" | grep -q "migrations/.*\.sql"; then
    echo "⚠️  Database migration pre-execution check:" >&2
    echo "  - Have you prepared rollback procedures?" >&2
    echo "  - Have you taken backups?" >&2
    echo "  - Have you confirmed the scope of impact?" >&2
    exit 1  # exit 1: Show warning and continue tool execution
fi

exit 0  # exit 0: No output

The meanings of Hook exit codes are as follows:

• exit 0: Do not display output
• exit 1: Display stderr to user, continue tool execution
• exit 2: Display stderr to model, block tool execution

6: MCP Server Configuration

Add an MCP server configuration to connect to SQLite3 database.
Create .mcp.json in the plugin's root directory.

{
  "mcpServers": {
    "sqlite": {
      "command": "uvx",
      "args": [
        "mcp-server-sqlite",
        "--db-path",
        "${SQLITE_DB_PATH:-./db/database.db}"
      ]
    }
  }
}

The ${SQLITE_DB_PATH} environment variable will use its value if set, otherwise the default value.

% export SQLITE_DB_PATH="./my-project/database.db"
OR
% SQLITE_DB_PATH="./my-db/data.db" claude

7: Create .claude-plugin/plugin.json

Create a plugin manifest to combine all components.

% cd ~/dev-marketplace/plugins/database-migration-plugin
% mkdir -p .claude-plugin

Create plugins/database-migration-plugin/.claude-plugin/plugin.json file as follows:

{
  "name": "database-migration-plugin",
  "version": "1.0.0",
  "description": "Plugin to automate SQLite3 migration management",
  "author": {
    "name": "Your Team"
  }
}

Place plugin.json in the .claude-plugin/ directory.
Note that other components (commands, agents, etc.) are placed in the plugin root.

8: Push the plugin to Github

The structure of the created plugin is as follows:

database-migration-plugin/                    
├── .claude-plugin/
│   └── plugin.json                          # Plugin manifest
├── .mcp.json                                # MCP Server configuration
├── agents/
│   └── migration-planner.md                 # Subagent
├── commands/
│   └── migrate.md                           # Slash Command
├── skills/
│   └── migration-best-practices/
│       └── SKILL.md                         # Skill
├── hooks/
│   └── hooks.json                           # Hook configuration
└── scripts/
    └── migration-check.sh                   # Hook script

Upload the created plugin to GitHub.
After creating a repository on GitHub, follow the steps to push it.

This completes the preparation of the marketplace and plugin.

Install Plugin

Now we'll work in the repository where you want to install the plugin.
First, install by directly specifying the GitHub URL of the plugin.

% claude

# Installation
> /plugin install https://github.com/your-team/database-migration-plugin

# Confirmation
> /plugin

For team use, add the configuration to
.claude/settings.json (or .claude/settings.local.json) in the team repository.

% mkdir -p .claude

Create settings.local.json with the following content.
Specify the marketplace URL in enabledPlugins.

{
  "enabledPlugins": [
    "https://github.com/nakamura-shuta/dev-marketplace.git"
  ]
}

After getting .claude/settings.json from the project repository,
starting Claude Code will automatically prompt you to install plugins.

# Get the project repository (clone)
# Note: This is not the plugin repository
% cd your-project

# Start Claude Code
% claude

# You'll be prompted to install automatically detected plugins

You can also install and update using the /plugin command in Claude Code:

> /plugin 
╭──────────────────────────────────────────────────────────────────╮
│ Plugins                                                          │
│                                                                  │
│ ❯ 1. Browse and install plugins                                  │
│   2. Manage and uninstall plugins                                │
│   3. Add marketplace                                             │
│   4. Manage marketplaces                                         │
╰──────────────────────────────────────────────────────────────────╯

To install, select "Add marketplace" and
enter the URL of the marketplace repository.

> /plugin 
╭──────────────────────────────────────────────────────────────────╮
│ Add Marketplace                                                  │
│                                                                  │
│ Enter marketplace source:                                        │
│ Examples:                                                        │
│  • owner/repo (GitHub)                                           │
│  • git@github.com:owner/repo.git (SSH)                           │
│  • https://example.com/marketplace.json                          │
│  • ./path/to/marketplace                                         │
│                                                                  │
│                                                                  │
╰──────────────────────────────────────────────────────────────────╯

Then,
select "Browse and install plugins"
to install plugins.

When you want to update a plugin,
select "Manage and uninstall plugins",
select the plugin, and execute "Update now".

Plugin Verification

Skill

Claude automatically recognizes the migration-best-practices Skill.
※First, create an appropriate DB

When given instructions like this, Claude uses the migration-best-practices Skill
to generate migration files.

> Create a migration to add an email column to the users table

Subagent

If you instruct "use the agent",
the migration-planner subagent will plan migrations.

> Use the migration-planner agent to create a migration
> that adds a published_at column (DATETIME type, NULL allowed) to the posts table

Custom Slash Command

Custom slash commands are also included in the plugin,
so you can generate migrations with the /database-migration-plugin:migrate command.

> /database-migration-plugin:migrate Add is_active column (BOOLEAN, default 1) to users table

commands/migrate.md is expanded, and the migration-planner agent starts.
※Plugin commands are called in the format /plugin-name:command-name

Hook

Finally, let's check the Hook's operation.
Try requesting to create a migration file as follows:

> Create migrations/002_add_posts.sql with CREATE TABLE posts content

The Hook will activate and display the following warning:

PreToolUse:Write says: Plugin hook error: ⚠️  Database migration pre-execution check:
  - Have you prepared rollback procedures?
  - Have you taken backups?
  - Have you confirmed the scope of impact?

MCP Server

The plugin also includes SQLite MCP server configuration.
You can retrieve current schema information as follows:

> Tell me the current table structure of hoge.db

By installing the plugin, the MCP server has become available.

Summary

In this article, I explained the relationship between Claude Code Skills, Subagents, and Plugins, and how to package them.

Skills:

• Group specialized knowledge in folders to teach Claude
• Describe instructions and metadata in SKILL.md
• Maximize context efficiency with 3-layer gradual disclosure

Subagent:

• Specialized agents that autonomously execute specific tasks
• Can run in parallel with independent contexts
• Handle complex workflows with orchestration patterns

Plugin:

• Package and distribute Skills, Subagents, slash commands, MCP, and hooks
• Distribute and share via distributed marketplaces
• Standardize enterprise adoption with .claude/settings.json

By combining five features (Skill, Subagent, Command, Hook, MCP) into a Plugin,
tasks in specific fields can be managed with consistent procedures.

Also, by sharing configuration files (settings.json) in repositories,
plugin settings can be shared across the team.

References

• Claude Skills: Customize AI for your workflows | Anthropic
• Equipping agents for the real world with Agent Skills | Anthropic
• Customize Claude Code with plugins | Anthropic
• GitHub - anthropics/skills: Public repository for Skills
• Sub-agents - Claude Docs
• プラグイン - Claude Docs
• プラグインマーケットプレイス - Claude Docs
• Claude CodeにおけるClaude SkillsとSubAgentsの使い分けと併用を理解する｜nogu66
• Claude Code Pluginでコマンドやサブエージェントを管理する｜ymiz
• Claude Code のプラグインで開発環境をカスタマイズする｜azukiazusa
• Claude Skills の概要｜npaka
• Claude Code の プラグイン の概要｜npaka
• jeremylongshore/claude-code-plugins-plus
• wshobson/agents