【2025/10/17最新アプデ】Claude Code 2.0.20、エージェントスキルの導入とチーム配布の解説

はじめに

この記事は、本日2025/10/17にリリースされたClaude Code 2.0.20以降に利用が可能となった、
スキルを自作導入する方法や、チーム内で配布するための方法を解説する記事です。

公式のドキュメント記事（日本語版はまだ無い）を、まずはご確認ください。

https://docs.claude.com/en/docs/claude-code/skills

カスタムスラッシュコマンド、サブエージェント、MCP、フック等の機能に加え、
今回新たに「エージェントスキル（以降「スキル」と表記します）」が追加されました。

当社カンリーでも早速導入してみたので、手順を記事として公開します。

想定読者

• Claude Codeの新機能が何か、興味をお持ちの方
• コンテキストウィンドウの制約に日々悩まされている方
• Claude Codeの精度を高め、個人やチームの生産性を上げたい方

導入メリット

• プロジェクト固有のスキルを定義することで、Claude Codeの精度が高まる
• CLAUDE.mdや各種設定に詰め込んでいたコンテキストが、必要に応じて呼ばれるようになる
• モデルによって自律的に読み込まれるため、利用者が意識せずともスキルを再利用可能

スキルとは何か

公式ドキュメント原文

What are Agent Skills?

Agent Skills package expertise into discoverable capabilities. Each Skill consists of a SKILL.md file with instructions that Claude reads when relevant, plus optional supporting files like scripts and templates.
How Skills are invoked: Skills are model-invoked—Claude autonomously decides when to use them based on your request and the Skill’s description. This is different from slash commands, which are user-invoked (you explicitly type /command to trigger them).
Benefits:

• Extend Claude’s capabilities for your specific workflows
• Share expertise across your team via git
• Reduce repetitive prompting
• Compose multiple Skills for complex tasks

引用：Agent Skills - Claude Docs

日本語訳

「Agent Skills」とは何か？
Agent Skills（エージェントスキル）は、専門知識を“発見可能な機能”としてパッケージ化したものです。各スキルは SKILL.md ファイルで構成されており、その中にはClaudeが必要に応じて読む指示内容が書かれています。また、スクリプトやテンプレートなどの補助ファイルを任意で含めることもできます。

スキルの呼び出し方法:
スキルは「モデルによって自律的に呼び出され」ます。つまりClaudeが、あなたのリクエスト内容とスキルの説明をもとに、いつどのスキルを使うか自動的に判断します。
これはユーザーが明示的に/commandを入力して実行する「スラッシュコマンド」とは異なります。

利点:

• Claudeの機能を自分のワークフローに合わせて拡張できる
• Gitを通じてチーム全体で専門知識を共有できる
• 繰り返しのプロンプトを減らせる
• 複数のスキルを組み合わせて複雑なタスクを実現できる

上記解説を読んでの解釈

初見では「カスタムスラッシュコマンドやサブエージェントとどう違うのか？」と感じましたが、
上記の呼び出し方法や利点を読む限り、「必要に応じて自律的に呼び出される」点が重要です。
各種設定ファイルや機能との違いを考えてみました。

CLAUDE.mdとの違い

CLAUDE.mdにあらゆる知識やスキルを詰め込むと、起動時に読み込む量が肥大化し
コンテキストウィンドウを圧迫してしまいます。
それに比べ、スキルであれば「必要に応じて自律的に呼び出される」ことで、
必要以上にコンテキストウィンドウを圧迫せずに、専門的な作業が依頼できるようになります。

カスタムスラッシュコマンドとの違い

カスタムスラッシュコマンドは、決められたワークフローを実行する際に役立ちます。
しかし、Claude Codeに対して人間が明示的にコマンドを指示する必要があります。
そのためチーム内で配布しても、コマンドの定義を人間が理解していなければ利用されません。

それに対しスキルは自律的に呼び出されるため、どのようなスキルが定義されているか
人間が認知・意識することを減らしつつ、専門的な作業の品質向上が見込まれます。

サブエージェントとの違い

サブエージェントは、例えばコードレビューの専門家やセキュリティの専門家のように
人格や役割を定義しておくことで、モデルから自律的に呼び出されます。

スキルは具体的な個々の作業に対する知見を定義するのに対し、
サブエージェントはより抽象的な、役割を担う人格を定義する違いがあると考えています。

そのため、今までサブエージェントにスキル定義をたくさん盛り込んでいたのであれば、
必要に応じてスキルに分割して定義する方が良いように思います。
そうすることでサブエージェントのトークン消費が抑えられますし、複数サブエージェントで
共通のスキルとして利用することも可能になりそうです。

スキルのベストプラクティス

公式ドキュメントをご参照ください。

https://docs.claude.com/en/docs/agents-and-tools/agent-skills/best-practices

いくつか重要な点をピックアップすると、

• 簡潔に定義する
• 自由度を高く定義する
• descriptionフィールドを元にスキル使用が判断されるため、具体的なキーワードを含める

配置場所によるスキルの読み込み

カスタムスラッシュコマンド等と同じく、配置場所によって3種類の利用方法があります。

https://docs.claude.com/en/docs/claude-code/skills#create-a-skill

1. 個人スキル

~/.claude/skills/下にディレクトリを作成し配置することで、
ローカルでのClaude Code開発時にプロジェクトを問わず、スキルが適用されます。

プロジェクトを問わないためどこからでも参照できるのが利点ですが、
例えばフロントエンドの開発作業なのに、個人スキルでバックエンドのスキルが定義されていると
作業に不要なスキルも読み込まれ、無駄にコンテキストが圧迫されてしまいます。
個人スキルとして定義するのは、あらゆるプロジェクトで横断的に利用するスキルに限りましょう。

2. プロジェクトスキル

.claude/skills/下にディレクトリを作成し配置することで、
該当プロジェクトでのClaude Code開発時にスキルが適用されます。

例えばバックエンドのプロジェクトにおいて必要な言語特有の開発スキルは、
リポジトリ直下のプロジェクトスキルとして配置しておくと良さそうです。

3. プラグインスキル

まず、先週投稿したマーケットプレイスの記事をご参照ください。

https://zenn.dev/canly/articles/d76a950bbeefc6

プラグインとマーケットプレイスの機能を利用することで、チームやコミュニティに配布できます。

プロジェクト内スキルをチームで共有する際は「2. プロジェクトスキル」で十分ですが、
プロジェクトを横断した汎用的な個人スキルをチームで共有する場合は、プラグインスキルが最適です。

スキルの自作

では、早速スキルを自作してみます。
前述のようにスキルの定義は3種類の方法があるので、それぞれのサンプルを示します。

製作サンプルは共通で、「Claude Codeのプラグイン設定スキルセット」とします。
具体的には、

• カスタムスラッシュコマンド
• サブエージェント
• MCP
• フック
• スキル

といった設定を、Claude Code自身に任せる際のスキルを定義してみましょう。

共通：Claude Codeのバージョンアップ

$ claude update

2.0.20以上になっていればOKです。

パターン1：個人スキルを自作してみる

まずサンプルとして、個人スキルを自作します。
こちらは個人設定となるため他人と共有されず、自身の全プロジェクトで有効となります。

  ~/.claude/skills/
  └── claude-code-plugin-skill/
      ├── SKILL.md                    # スキルエントリーポイント
      ├── custom-slash-commands.md    # カスタムコマンドガイド
      ├── subagents.md                # サブエージェントガイド
      ├── mcp.md                      # MCPガイド
      ├── hooks.md                    # フックガイド
      ├── skills.md                   # スキルガイド
      └── best-practices.md           # ベストプラクティス詳細

SKILL.mdがエントリーポイントとなり、nameとdescriptionが必ず読み込まれます。
その他ファイルは初期状態では読み込まれず、作業内容の必要に応じて追加で読み込まれます。

例えば「カスタムコマンドの実装をして」と指示を出せば、
SKILL.md経由でcustom-slash-commands.mdが読み込まれ、実装が行われるはずです。

SKILL.md

---
name: Claude Code拡張機能開発
description: カスタムコマンド、サブエージェント、MCPサーバー、フック、スキルを含むClaude Code拡張機能の作成ガイド。個人の開発環境カスタマイズや拡張機能の学習時に使用。
allowed-tools: Read
---

# Claude Code拡張機能開発

Claude Codeは5つのコアコンポーネントで拡張できます：カスタムスラッシュコマンド、サブエージェント、MCP、フック、スキル。

## クイックスタート

最小構成のコマンド作成：

```bash
# 1. コマンドディレクトリを作成
mkdir -p ~/.claude/commands

# 2. コマンドを作成
cat > ~/.claude/commands/hello.md << 'EOF'
---
name: hello
description: Hello World を表示
---

# Hello World

Hello, World! を表示します。
EOF
```

**使用方法:**

```bash
/hello  # Hello, World! を表示
```

## コンポーネント

各コンポーネントの詳細ガイド：

- **[カスタムスラッシュコマンド](custom-slash-commands.md)** - コマンドの実装、YAML frontmatter、引数ハンドリング
- **[サブエージェント](subagents.md)** - エージェントの作成、ツール制御、ベストプラクティス
- **[MCP (Model Context Protocol)](mcp.md)** - 外部サービス連携、認証管理
- **[フック](hooks.md)** - イベント駆動型自動化、フックタイプ
- **[スキル](skills.md)** - 知識パッケージ、Progressive Disclosure
- **[ベストプラクティス](best-practices-personal.md)** - 命名規則、テスト方法、バックアップ

## リソース

- [Claude Code ドキュメント](https://docs.claude.com/en/docs/claude-code)
- [Agent Skills 概要](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview)
- [Agent Skills ベストプラクティス](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/best-practices)
- [Claude Code Skills](https://docs.claude.com/en/docs/claude-code/skills)

全ファイルのサンプルを書くと膨大な量になるので、custom-slash-commands.mdのみ示します。

custom-slash-commands.md

# Custom Slash Commands

カスタムスラッシュコマンドは、Claude Codeで`/`で始まる独自コマンドを定義する機能です。

## クイックスタート

```bash
# 1. コマンドディレクトリを作成
mkdir -p ~/.claude/commands

# 2. コマンドファイルを作成
cat > ~/.claude/commands/hello.md << 'EOF'
---
description: Hello Worldを出力
---

# Hello

Hello Worldを出力するシンプルなコマンド

## 使用例

```
/hello

→ Hello, World!
```
EOF
```

## ファイル構造

```
~/.claude/
└── commands/
    ├── hello.md
    └── my-command.md
```

## YAML Frontmatter

```yaml
---
description: コマンドの説明（必須）
argument-hint: [引数のヒント]  # オプション
allowed-tools: Tool1, Tool2  # オプション
---
```

### フィールド

- **description** (必須): コマンドの1行説明
- **argument-hint** (オプション): 引数の形式を示すヒント
- **allowed-tools** (オプション): 使用可能なツールを制限

## 実装例

### 引数付きコマンド

```markdown
---
description: 指定されたファイルを要約
argument-hint: [ファイルパス]
allowed-tools: Read
---

# Summarize

指定されたファイルの内容を読み込んで要約します。

**引数仕様**:
- $1 (ファイルパス): 必須 - 要約対象のファイルパス

## 使用例

```
/summarize /path/to/document.md

→ ファイルの内容を読み込み、要約を生成します
```
```

### よく使うallowed-toolsパターン

```yaml
# ファイル操作
allowed-tools: Write, Read, Edit, Glob

# 検索・調査
allowed-tools: Read, Grep, Glob, WebFetch

# 開発ワークフロー
allowed-tools: Write, Read, Edit, Bash, Glob, Grep

# 外部API連携
allowed-tools: mcp__notion__*, mcp__backlog__*
```

## テスト

1. Claude Codeを再起動
2. `/`を入力してコマンドが表示されるか確認
3. コマンドを実行して動作確認

パターン2：プロジェクトスキルを自作してみる

概ねパターン1と変わりません。
配置場所が~/.claude/skills/ではなく.claude/skills/になるだけです。

パターン3：プラグインスキルを自作してみる

プラグインスキルの場合、マーケットプレイスの設定もするためファイル構造が大きく異なります。

  my-claude-code-plugin-marketplace/
  ├── .claude-plugin/
  │   └── marketplace.json    # 全プラグインの登録情報（集中管理）
  └── plugins/
      └── your-plugin/
          ├── .claude-plugin/
          │   └── plugin.json
          └── skills/
              └── claude-code-plugin-skill/
                  ├── SKILL.md
                  └── *.md

.claude-plugin/marketplace.jsonに、各プラグインを定義します。
以下サンプルはyour-pluginというサンプルを配置したものです。
もし複数プラグインを管理する場合は、pluginsの下にプラグイン定義を増やしていきます。

marketplace.json

  {
    "name": "my-claude-code-plugin-marketplace",
    "owner": {
      "name": "Your Organization",
      "url": "https://github.com/your-org/your-repo"
    },
    "description": "Your Organization's Claude Code Plugin Marketplace",
    "plugins": [
      {
        "name": "your-plugin",
        "version": "1.0.0",
        "description": "Your plugin description",
        "author": {
          "name": "Your Name"
        },
        "source": "./plugins/your-plugin"
      }
    ]
  }

plugins/your-plugin/.claude-plugin/plugin.jsonに、プラグインを定義します。
なお、your-pluginや各フィールドの中身はダミーなので、適宜自前の命名に置き換えてください。

plugin.json

  {
    "name": "your-plugin",
    "version": "1.0.0",
    "description": "Your plugin description",
    "author": {
      "name": "Your Name"
    }
  }

SKILL.mdのサンプルです。

SKILL.md

---
name: Claude Codeプラグイン開発
description: カスタムコマンド、サブエージェント、MCPサーバー、フック、スキルを含むClaude Codeプラグインの作成ガイド。新規プラグイン開発やプラグインアーキテクチャの学習時に使用。
allowed-tools: Read
---

# Claude Codeプラグイン開発

Claude Codeプラグインは5つのコアコンポーネントで構築できます：カスタムスラッシュコマンド、サブエージェント、MCP、フック、スキル。

## クイックスタート

最小構成のプラグイン作成：

```bash
# 1. プラグインディレクトリを作成
mkdir -p plugins/my-plugin/.claude-plugin
mkdir -p plugins/my-plugin/commands

# 2. plugin.jsonを作成
cat > plugins/my-plugin/.claude-plugin/plugin.json << 'EOF'
{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "私のプラグイン",
  "author": {
    "name": "your-name"
  }
}
EOF

# 3. コマンドを作成
cat > plugins/my-plugin/commands/hello.md << 'EOF'
---
name: hello
description: Hello World を表示
---

# Hello World

Hello, World! を表示します。
EOF
```

**使用方法:**
```bash
/hello  # Hello, World! を表示
```

## コンポーネント

各コンポーネントの詳細ガイド：

- **[プラグイン構造](plugin-structure.md)** - ディレクトリ構造、セットアップ手順、実装例
- **[カスタムスラッシュコマンド](custom-slash-commands.md)** - コマンドの実装、YAML frontmatter、引数ハンドリング
- **[サブエージェント](subagents.md)** - エージェントの作成、ツール制御、ベストプラクティス
- **[MCP (Model Context Protocol)](mcp.md)** - 外部サービス連携、認証管理
- **[フック](hooks.md)** - イベント駆動型自動化、フックタイプ
- **[スキル](skills.md)** - 知識パッケージ、Progressive Disclosure
- **[ベストプラクティス](best-practices.md)** - 命名規則、テスト方法、よくあるパターン

## リソース

- [Claude Code ドキュメント](https://docs.claude.com/en/docs/claude-code)
- [Agent Skills 概要](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview)
- [Agent Skills ベストプラクティス](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/best-practices)
- [Claude Code Skills](https://docs.claude.com/en/docs/claude-code/skills)

各スキルファイルは、「パターン1：個人スキルを自作してみる」を参考にしてください。

実装後、マーケットプレイスとプラグインの設定を行います。

/plugin marketplace add ./
/plugin marketplace list 
⎿  Configured marketplaces:
    • my-claude-code-plugin-marketplace

/plugin install your-plugin@my-claude-code-plugin-marketplace
> /plugin 
 ❯ 1. Browse & install plugins    
│ ❯ my-claude-code-plugin-marketplace
   1 plugin available · 1 already installed · /path/to/my-claude-code-plugin-marketplace

最後に

今回のスキル機能、そして先週リリースされたマーケットプレイス機能は、
Claude Codeを利用したチーム開発において大きく生産性を高めるポテンシャルを秘めています。

暗黙知となっているスキルを言語化してファイル化し共有することで、スキルは適切に引き継がれ
業務の属人化を解消する一歩となりそうです。

これからも当社カンリーではAIコーディングエージェントの動向を追い、
必要に応じて業務への導入と、外部発信を続けてまいります。