Claude CodeのSkillをPluginとして最小構成で作る

自分だけで使うSkillは.claude/skills/に置けば足ります。複数のリポジトリへ配布する、バージョンを付ける、SkillsとHooksを一緒に管理する段階でPluginへまとめます。

最小構成

二つのパスはどちらもmy-pluginの下にあります。

• .claude-plugin/plugin.jsonPluginの名前・説明・バージョンを記す。
• skills/review/SKILL.mdレビューSkillの利用条件と実際の手順を書く。

skillsを.claude-pluginの中へ入れない点が重要です。本文のフォルダー木と同じ配置で試します。

my-plugin/
├─ .claude-plugin/plugin.json
└─ skills/review/SKILL.md

{
  "name": "my-review",
  "description": "Review project changes",
  "version": "1.0.0"
}

SKILL.mdには利用条件を示すfrontmatterと手順を書きます。Skill、agent、Hookなどのコンポーネントは.claude-plugin/の中ではなくPluginルート直下の既定ディレクトリに置きます。テスト中はプロジェクトへ登録せず、claude --plugin-dir ./my-pluginでそのセッションだけ読み込む方法があります。

descriptionと配布

descriptionには「どの依頼で使うか」と対象範囲を書きます。一般的すぎる説明は意図しない自動発火の原因になります。補助スクリプトをbin/へ置く場合は、相対パスだけを使い、外部入力をコマンド文字列へ無検証で連結しないでください。Pluginのパス外を参照できない制限もあります。動作確認ではSkill単体、Hook単体、MCP接続を分けて調べます。

共有するならREADME、変更履歴、必要な権限、対応バージョンを添え、Marketplaceへ登録します。インストール時はuser/project/localのscopeを利用者に説明し、更新後は/reload-pluginsを案内します。配布元が信頼できるかを利用者が判断できる情報を残してください。

公式Plugin作成ガイド、仕様、導入ガイドを確認しました。Skill単体の作り方はSkills実践、Hookとの組み合わせはHooks解説へ。実機検証はしていません。

SKILL.mdの実例

Pluginルートの skills/review/SKILL.md は次のように書けます。

---
name: review
description: Review changed files and report risks without editing
---
# Review
1. Read the diff and relevant tests.
2. Report findings with file and line.
3. Do not edit, commit, or send data.

このSkillは /my-review:review のように名前空間付きで呼び出されます。description、対象範囲、変更禁止を明記したうえで、プロジェクトのテスト用ブランチから動作を確認します。