Claude Codeのスキル・プラグイン・マーケットプレイスの違いを図解で解説

Contents

1 はじめに
2 スキル、プラグイン、マーケットプレイスとは？
3 使い分けの判断基準
4 スキルを実装してみた
5 プラグインを実装してみた
6 マーケットプレイスを実装してみた
7 まとめ
8 付録：よく使うコマンド一覧（コピー用）

はじめに

Claude Code を使い始めると、「スキル」「プラグイン」「マーケットプレイス」という三つの言葉に早々に出くわします。
ドキュメントを読んでも「結局どう違うのか」「何から手をつければいいのか」がつかみにくい、という声をよく耳にします。

スキルってファイル1個でいいの？プラグインって何が増えるの？

この記事では、その三つの概念を整理し、ローカルでのスキル作成からプラグイン化、GitHub を使ったマーケットプレイス配布までの流れを、コマンドとファイル例を交えて順を追って解説します。
「概念は何となくわかったが、実際に手を動かして確かめたい」という方を主な読者として想定しています。

スキル、プラグイン、マーケットプレイスとは？

三つの概念の関係を一言で表すなら、「機能の最小単位がスキル、それをまとめて配布できる形にしたものがプラグイン、複数のプラグインを束ねて管理・配布するカタログがマーケットプレイス」です。

カードゲームで例えるなら、スキルが一枚のカード、プラグインが複数のカードを束ねた一つのデッキ、マーケットプレイスがカードを売っているお店みたいなイメージです。

スキル（Skill）とは

スキルは、Claude に追加する「個別の機能」を定義するファイルです。
実体はほぼ一枚の Markdownファイル（SKILL.md）で、ファイル先頭のフロントマター（--- で囲んだYAML）に name や description を記載し、本文に動作の指示やテンプレートを書きます。

たとえば ~/.claude/skills/hello/SKILL.md を作成すれば、個人環境で即座に /hello スキルが使えるようになります。
設定ファイルを一つ書くだけで動く手軽さが、スキルの最大の特長です。

フォルダ構成の例

スキルは.claudeの直下の skillsフォルダに配置します。

path/to/your-skill-directory
└── .claude
    └── skills
         └── SKILL.md

SKILL.mdの例

以下がSKILL.mdの例です。
自然言語ベースで動作を定義します。

---
name: changelog
description: Generate a structured changelog entry from git diffs or commit history following Keep a Changelog format
---
与えられた差分またはコミット履歴から、Keep a Changelog 形式に準拠した変更履歴エントリを生成してください。

## ルール
1. 変更を以下のカテゴリに自動分類する:
   - **Added** — 新機能
   - **Changed** — 既存機能の変更
   - **Deprecated** — 将来削除予定の機能
   - **Removed** — 削除された機能
   - **Fixed** — バグ修正
   - **Security** — セキュリティに関する修正
2. 各エントリは **ユーザー視点** で簡潔に記述する（実装の詳細ではなく、何が変わったか）
3. 関連する Issue / PR 番号があれば末尾に付記する
4. 変更が多い場合はカテゴリごとに重要度順にソートする

## 出力フォーマット
```markdown
## [Unreleased] - YYYY-MM-DD

### Added
- 項目

### Changed
- 項目

### Fixed
- 項目
```

該当しないカテゴリは省略してください。

## 入力
$ARGUMENTS

引数が空または未指定の場合は、以下の順序で自動取得してください:
1. `git log --oneline -10` を実行して直近のコミット履歴を取得
2. コミット履歴が空の場合は `git diff --cached`、それも空なら `git diff` で差分を取得
3. どちらも空の場合はユーザーに差分またはコミットログを渡すよう案内する

- diff: 差分テキストまたはコミットログ
- version: バージョン番号（省略時は Unreleased）

プラグイン（Plugin）とは

プラグインは、スキルやエージェント、フック（hooks）、コマンド（commands）などを一つのディレクトリにまとめた「自己完結型のパッケージ」です。
ルートに.claude-plugin/plugin.jsonを配置し、メタ情報（名前・バージョン・作者など）を記載します。
あとはこのプラグインの動作を、skills/・agents/・hooks/などのコンポーネントを配置して設計します。

プラグイン化することで、複数のコンポーネントを組み合わせることができることに加えて、スキルへの呼び出しに名前空間が付き、/my-plugin:hello のように他のプラグインと名前が衝突しなくなるというメリットがあります。

フォルダ構成の例

最小限のフォルダ構成の例は以下のとおりです。
.claude-plugin直下に、plugin.jsonを配置するというのが肝です。

path/to/your-plugin-directory
├── .claude-plugin
│   └── plugin.json
└── skills
    └── add-docstring
        └── SKILL.md

plugin.jsonの例

以下が plugin.jsonの例です。
plugin.jsonには、skillsだけでなく、hooksや agentsなども定義することが可能です。

{
  "name": "plugin-demo",
  "version": "1.1.0",
  "description": "Skills・Hooks・Agentsの3機能をデモするプラグイン",
  "author": {
    "name": "kuretom"
  },
  "license": "MIT",
  "skills": "./skills/",
  "agents": ["./agents/code-reviewer.md"],
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/log-edit.sh",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

マーケットプレイス（Marketplace）とは

マーケットプレイスは、複数のプラグインをまとめて管理・配布するための「カタログ」です。

marketplace.json でプラグインの一覧とそのソースを定義し、GitHub などでホストしておくことで、/plugin marketplace addと/plugin installを使って簡単にプラグインを追加できるようになります。

マーケットプレイスの利点は、第三者にプラグインを配布できるようになることと、複数プラグインをまとめて管理できることです。

フォルダ構成の例

ルートの.claude-plugin直下に marketplace.jsonを配置します。
同様にルートの pluginsディレクトリ直下に、plugin名のフォルダを作り、その直下にpluginを設定していきます。

path/to/your-marketplace-directory
├── .claude-plugin
│   └── marketplace.json
└── plugins
    ├── nextjs-ui-advisor-plugin
    │   ├── agents
    │   │   └── ui-performance-advisor.md
    │   └── skills
    │       ├── check-accessibility
    │       │   └── SKILL.md
    │       └── review-components
    │           └── SKILL.md
    └── project-management-plugin
        ├── agents
        │   └── release-note-writer.md
        └── skills
            ├── check-dependencies
            │   └── SKILL.md
            └── organize-todos
                └── SKILL.md

marketplace.jsonの例

marketplace.jsonの記載例は以下のとおりです。

{
  "name": "demo-marketplace",
  "description": "Next.js UI改善提案とプロジェクト管理のデモ用マーケットプレイス",
  "owner": {
    "name": "kuretom"
  },
  "plugins": [
    {
      "name": "nextjs-ui-advisor",
      "source": "./plugins/nextjs-ui-advisor-plugin",
      "description": "Next.jsアプリのUI改善提案ツール（アクセシビリティ診断・コンポーネント設計レビュー・パフォーマンス改善）",
      "version": "1.0.0",
      "author": {
        "name": "kuretom"
      },
      "category": "development"
    },
    {
      "name": "project-management",
      "source": "./plugins/project-management-plugin",
      "description": "プロジェクト管理支援ツール（TODO整理・依存関係チェック・リリースノート生成）",
      "version": "1.0.0",
      "author": {
        "name": "kuretom"
      },
      "category": "productivity"
    }
  ]
}

使い分けの判断基準

迷ったときの判断軸はシンプルです。
「個人利用・単独のシンプルな機能ならスキル、いくつかのコンポーネントを組み合わた少し複雑な機能ならプラグイン、複数プラグインを管理・配布するならマーケットプレイス」

たとえば、コードの説明を生成する /explain-code スキルを使いたいとします。
まず ~/.claude/skills/explain-code/SKILL.md として個人環境で作り、使い勝手を確かめます。
hooksやagentsなどを組み合わせたい場合は、plugin.jsonを追加してプラグイン化します。

さらにプラグインを配布・複数管理したいなら、marketplace.jsonを追加してマーケットプレイス化した上でGit管理するという流れが自然です。

スキルを実装してみた

まずはローカル環境でスキルを実装してみます。
最終的なディレクトリ構成は以下のとおりです。

path/to/your-skill-directory
└── .claude
    └── skills
         └── SKILL.md

スキル実装の例

最初にスキル用ディレクトリを作成します。

mkdir -p path/to/your-skill-directory/.claude/skills/hello

次に、以下の内容で SKILL.md を作成します。
これは検証用の、単純にユーザーに尋ねるだけのスキルです。
本文部分には Claudeへの指示を自然言語で書きます。

# path/to/your-skill-directory/.claude/skills/hello/SKILL.md
---
name: hello
description: ユーザーにフレンドリーな挨拶をする
---
ユーザーに温かく挨拶し、今日どのようなお手伝いができるか尋ねてください。

name と description は、スキルの検索や一覧表示に使われる重要なフィールドです。
省略するとスキルが認識されない場合があるため、必ず記載してください。

本当にこれだけで動くの？

動くよ。
一つのスキルファイルを動かすのはとてもシンプルなんだ。

実行

Claudeの会話画面（または CLI）で次のように入力すると、スキルが呼び出されます。
（スキルを実装したディレクトリと同じ場所で、claudeを立ち上げてください）

# Claude Codeの立ち上げ
claude

# スキルの実行
/hello

以下のように質問が返ってきたら意図した通りにスキルが発動しています。

スキルが読み込まれない場合は、次の点を順番に確認してください。

まず確認すること

ディレクトリのパスが正しいか（.claude/skills/hello/SKILL.md になっているか）
name が正しく記述されているか
ファイル名が SKILL.md（大文字）になっているか
Claude を再起動してから実行したか

スキルのデモ用ソース（Github）

このスキルのデモで使ったソースコードは、以下のGitHubに格納しています。
https://github.com/kuretom-blog/claude-code-skill-demo

プラグインを実装してみた

スキルの動作を確認できたら、次はプラグインの実装をしてみます。
フォルダ構成は以下のようになります。

/path/to/your-plugin-directory
├── .claude-plugin
│   └── plugin.json
├── agents
│   └── code-reviewer.md
├── scripts
│   └── log-edit.sh
└── skills
    └── add-docstring
        └── SKILL.md

plugin.json の最小例

.claude-plugin/plugin.json を以下の内容で作成します。

# /path/to/your-project/.claude-plugin/plugin.json
{
  "name": "plugin-demo",
  "version": "1.1.0",
  "description": "Skills・Hooks・Agentsの3機能をデモするプラグイン",
  "author": {
    "name": "kuretom"
  },
  "license": "MIT",
  "skills": "./skills/",
  "agents": ["./agents/code-reviewer.md"],
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/log-edit.sh",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

name フィールドの値がそのまま名前空間になります。
プラグイン名は短く、かつ他のプラグインと重複しない名前にしてください。

SKILL.mdの例

プラグイン内の SKILL.md を作成します。
これはPythonファイルのdocstringを作成するためのスキルです。

---
name: add-docstring
description: Pythonファイルのdocstringが不足している関数・クラスにdocstringを追加する
---
ユーザーが指定したPythonファイルを読み取り、docstringが不足している関数やクラスにdocstringを追加してください。

ルール：
- 既存のdocstringは変更しない
- Google Styleのdocstringフォーマットを使用する
- 引数・戻り値・例外がある場合はArgs/Returns/Raisesセクションを含める
- docstringは日本語で記述する
- Editツールを使って既存ファイルを直接編集する

呼び出し例

ファイルが揃ったら、--plugin-dir フラグを付けて Claudeを起動してローカルでテストします。

claude --plugin-dir path/to/your-plugin-directory

プラグインが読み込まれているかどうかは、plugin コマンドで確認可能です。

/plugin

以下のように、InstalledのUserスコープに.claude-plugin/plugin.jsonで定義したnameフィールドと同じ名前が表示されていて、enabledになっていれば読み込みが成功しています。

起動後の会話画面で、次のように名前空間付きで呼び出します。

/plugin-demo:add-docstring

プラグイン内のスキルは必ず /<plugin-name>:<skill-name> の形式で呼び出します。
個人スコープのスキルと名前が同じでも衝突しないのは、この名前空間のおかげです。

プラグインのデモ用ソース（GitHub）

プラグインのデモで使ったソースコードは以下のGitHubに格納しています。
https://github.com/kuretom-blog/claude-code-plugin-demo

マーケットプレイスを実装してみた

最後に、マーケットプレイスを実装してみます。
marketplace.json でプラグインの一覧とソースを定義し、そのファイルをホスト（GitHub 推奨）しておくことで、利用者は数コマンドでプラグインをインストールできます。

最終的なフォルダ構成は以下のとおりです。

.path/to/your-marketplace/directory
├── .claude-plugin
│   └── marketplace.json
└── plugins
    ├── nextjs-ui-advisor-plugin
    │   ├── agents
    │   │   └── ui-performance-advisor.md
    │   └── skills
    │       ├── check-accessibility
    │       │   └── SKILL.md
    │       └── review-components
    │           └── SKILL.md
    └── project-management-plugin
        ├── agents
        │   └── release-note-writer.md
        └── skills
            ├── check-dependencies
            │   └── SKILL.md
            └── organize-todos
                └── SKILL.md

マーケットプレイスのホスト方法（GitHub 推奨）

marketplace.json 内の相対パスは、Git ベースでホストされている場合に正しく解決されます。
チームや組織向けに配布する場合は、GitHub リポジトリに置いて Git URL で参照するのが最も確実な方法です。

marketplace.json

.claude-plugin/marketplace.jsonは以下のとおりです。
pluginsフィールドにプラグインを設定していきます。

{
  "name": "demo-marketplace",
  "description": "Next.js UI改善提案とプロジェクト管理のデモ用マーケットプレイス",
  "owner": {
    "name": "kuretom"
  },
  "plugins": [
    {
      "name": "nextjs-ui-advisor",
      "source": "./plugins/nextjs-ui-advisor-plugin",
      "description": "Next.jsアプリのUI改善提案ツール（アクセシビリティ診断・コンポーネント設計レビュー・パフォーマンス改善）",
      "version": "1.0.0",
      "author": {
        "name": "kuretom"
      },
      "category": "development"
    },
    {
      "name": "project-management",
      "source": "./plugins/project-management-plugin",
      "description": "プロジェクト管理支援ツール（TODO整理・依存関係チェック・リリースノート生成）",
      "version": "1.0.0",
      "author": {
        "name": "kuretom"
      },
      "category": "productivity"
    }
  ]
}

マーケットプレイスのインストールとスキルの追加

マーケットプレイスからプラグインをインストールする方法は2ステップに別れています。
まずマーケットプレイスをカタログとして追加し、次に目的のプラグインをインストールします。

マーケットプレイスをカタログとして追加

以下のコマンドでマーケットプレイスのインストールが可能です。

# マーケットプレイスをカタログとして追加
/plugin marketplace add kuretom-blog/claude-code-marketplace-demo

なお、addの後のコマンドには、追加したいマーケットプレイスが格納されたGithubのリポジトリを指定します。

プラグインをインストール

以下のコマンドで追加したマーケットプレイスからプラグインをインストールできます。

# プラグインをインストール
/plugin install nextjs-ui-advisor@demo-marketplace

demo-marketplaceの部分は、.claude-plugin/marketplace.jsonで定義したnameフィールドの値を入れます。
また、nextjs-ui-advisorの部分は、.claude-plugin/marketplace.jsonで定義したpluginsフィールド内の nameフィールド（プラグイン名）を入れます。

呼び出し例

マーケットプレイスから追加したプラグインも、pluginコマンドにより追加されていることを確認可能です。

/plugin

呼び出し方は、プラグインと同様に、プラグイン名:スキル名で呼び出します。

マーケットプレイスのデモ用ソース（Github）

このマーケットプレイスのデモで使ったソースコードは、以下のGitHubに格納しています。
https://github.com/kuretom-blog/claude-code-marketplace-demo

まとめ

この記事で解説した3つの概念を最後にもう一度整理します。

スキル：SKILL.mdで定義する機能の最小単位。まず個人環境で試すのに最適。
プラグイン：スキルなど複数の要素をまとめた配布パッケージ。名前空間付きで競合を回避できる。
マーケットプレイス：複数のプラグインを束ねて配布・管理するカタログ。チームや組織規模の運用に向く。

学習の進め方も、この順番に沿うのが自然です。まずスキルを作る → プラグイン化する → マーケットプレイスで配布する、という3段階を一歩ずつ踏むことで、無理なく理解が深まります。

最初の一歩として、ぜひ ~/.claude/skills/hello/SKILL.md を作成して /hello を呼び出してみてください。
動作確認できれば、次は plugin.json を追加して --plugin-dir でのテストへ進んでみましょう。
チームへの共有が必要になった段階で、GitHub にマーケットプレイスを設ける手順を試してみると、3つの概念がつながりのワークフローとして腑に落ちるはずです。

参考：Claude Code 公式ドキュメント（スキル・プラグイン・マーケットプレイスの詳細仕様はこちら）

まずは小さく作って動かしてみよう。

付録：よく使うコマンド一覧（コピー用）

# プラグインのローカル読み込みテスト
claude --plugin-dir ./my-first-plugin

# マーケットプレイスの追加とプラグインのインストール
/plugin marketplace add ./my-marketplace
/plugin install quality-review-plugin@my-marketplace

# トラブルシューティング
claude --debug
claude plugin validate
/reload-plugins