Claude Code ガイド

Appearance

原文（日本語訳） ​

skills/ サブディレクトリを持たずルートレベルに SKILL.md があるプラグインが、スキルとして認識されるようになりました。

原文（英語） ​

Plugins with a root-level SKILL.md and no skills/ subdirectory are now surfaced as a skill

概要 ​

これまでClaude Codeのプラグインにスキルを含めるには、skills/<スキル名>/SKILL.md という形式でサブディレクトリを作成する必要がありました。バージョン2.1.142から、プラグインのルートディレクトリに直接 SKILL.md を置き、かつ skills/ サブディレクトリが存在しない場合、そのファイルが自動的にスキルとして認識されるようになりました。この変更により、単一スキルだけを提供するシンプルなプラグインの構造を大幅に簡素化できます。

基本的な使い方 ​

従来の方法（skills/ サブディレクトリを使う） ​

プラグインに複数のスキルを含める場合は、引き続き skills/ ディレクトリ構造が必要です。

text
my-plugin/
├── .claude-plugin/
│   └── plugin.json
└── skills/
    └── my-skill/
        └── SKILL.md
json
{
  "name": "my-plugin",
  "description": "プラグインの説明",
  "version": "1.0.0"
}

スキルは /my-plugin:my-skill として呼び出せます。

新しい方法（ルートレベル SKILL.md を使う） ​

単一スキルを提供するプラグインでは、SKILL.md をルートに直接置くだけで済みます。

text
my-plugin/
├── .claude-plugin/
│   └── plugin.json
└── SKILL.md
yaml
---
name: my-skill
description: スキルの説明。このスキルがいつ使われるかを記述します。
---

## スキルの指示内容

ここに Claude への指示を記述します。

スキルの名前は SKILL.md の frontmatter にある name フィールドで決まります。name が未設定の場合はディレクトリ名（プラグイン名）がフォールバックとして使われます。

テスト方法 ​

bash
# ローカルでプラグインをテストする
claude --plugin-dir ./my-plugin

# 変更後にリロードする
# Claude Code 内で実行:
# /reload-plugins

実践例 ​

シンプルなコードレビュースキルプラグイン ​

単一のコードレビュースキルを提供するプラグインを最小構成で作成できます。

ディレクトリ構造:

text
code-reviewer/
├── .claude-plugin/
│   └── plugin.json
└── SKILL.md

code-reviewer/.claude-plugin/plugin.json:

json
{
  "name": "code-reviewer",
  "description": "コードレビューを自動化するプラグイン",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  }
}

code-reviewer/SKILL.md:

yaml
---
name: review
description: コードをレビューしてベストプラクティスや潜在的な問題を指摘する。コードレビューやPRチェックの際に使用。
---

# コードレビュースキル

以下の観点でコードをレビューしてください:

1. コードの構造と可読性
2. エラーハンドリングの適切さ
3. セキュリティ上の懸念点
4. テストカバレッジ
5. パフォーマンスの問題

$ARGUMENTS

インストール後、/code-reviewer:review で呼び出せます。

専門知識を提供するナレッジスキルプラグイン ​

特定のドメイン知識を提供するシンプルなプラグインも簡単に作れます。

aws-advisor/SKILL.md:

yaml
---
name: aws-advice
description: AWSアーキテクチャのアドバイスを提供する。インフラ設計やAWSサービス選択の際に使用。
user-invocable: false
---

# AWS アーキテクチャガイドライン

このプロジェクトでは以下のAWSベストプラクティスに従ってください:

- VPCにはプライベートサブネットを使用する
- IAMロールは最小権限の原則に従う
- S3バケットはデフォルトでパブリックアクセスをブロックする
- CloudTrailを有効化してAuditログを保持する
- コスト管理のためにAWS Budgetsを設定する

plugin.json の skills フィールドを使う方法（代替手段） ​

plugin.json の skills フィールドに "./"] を指定することで、ルートディレクトリをスキルパスとして明示的に宣言することもできます（バージョン2.1.142以前から使える方法ですが、今回の変更でこのフィールドなしでも自動認識されるようになりました）。

json
{
  "name": "my-plugin",
  "description": "単一スキルのプラグイン",
  "version": "1.0.0",
  "skills": ["./"]
}

skills: ["./"] を使う場合も、SKILL.md の frontmatter の name フィールドがスキルの呼び出し名になります。

注意点 ​

  • skills/ ディレクトリとの共存不可: skills/ サブディレクトリが存在する場合、ルートレベルの SKILL.md は自動認識されません。ルートレベル SKILL.md として動作させるには skills/ ディレクトリを置かないようにしてください。
  • name フィールドを必ず設定する: SKILL.md の frontmatter に name を設定することを強く推奨します。未設定の場合はプラグインのインストールディレクトリ名がフォールバックとして使われますが、インストール方法によって名前が変わることがあります。
  • スキル名の名前空間: プラグインのスキルは常に <プラグイン名>:<スキル名> の形式で呼び出します（例: /my-plugin:review）。
  • skills フィールドの動作: plugin.json に skills フィールドを指定した場合、デフォルトの skills/ ディレクトリのスキャンに加えてそのパスも読み込まれます（commands などのフィールドとは異なりデフォルトを置き換えません）。
  • バージョン要件: このルートレベル SKILL.md の自動認識機能はバージョン2.1.142以降で利用できます。
  • CLAUDE.md との違い: プラグインのルートに置いた CLAUDE.md はプロジェクトコンテキストとして読み込まれません。Claudeへの指示を提供するにはスキルを使用してください。
  • /doctor コマンドで確認: プラグインのスキルが正しく認識されているか確認するには /doctor コマンドを実行してください。

関連情報 ​