Claude Code スキルの配布・設定ガイド

スキル（Agent Skills）とは

Claude Codeの機能を拡張するためのモジュール化された能力がスキルである。SKILL.mdファイルを含むディレクトリで構成される。

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

スキルの配置場所

スキルは以下の2つの場所に配置できる：

1. ユーザーレベル（個人用）

~/.claude/skills/
└── my-skill/
    └── SKILL.md

用途: 自分だけが使うスキル

2. プロジェクトレベル（チーム共有）

プロジェクト/
└── .claude/
    └── skills/
        └── team-skill/
            └── SKILL.md

用途: Gitにコミットしてチーム全体で共有

.skill パッケージの配布方法

パッケージの作成

スキルディレクトリを ZIP 圧縮して .skill 拡張子に変更：

# PowerShell での作成例
Compress-Archive -Path 'skill-name\*' -DestinationPath 'skill-name.zip'
Rename-Item 'skill-name.zip' 'skill-name.skill'

# Bash での作成例
cd .claude/skills
zip -r skill-name.skill skill-name/

配布方法

スキルのインストール方法

.skill ファイルからのインストール

1. .skillファイルを解凍（ZIP形式）
2. 中身を以下のいずれかに配置：
   • ~/.claude/skills/skill-name/（ユーザーレベル）
   • .claude/skills/skill-name/（プロジェクトレベル）

# 例: honda-sakubun.skill をインストール
unzip honda-sakubun.skill -d ~/.claude/skills/honda-sakubun/

手動でスキルを作成

# ディレクトリ作成
mkdir -p ~/.claude/skills/my-skill

# SKILL.md を作成
cat > ~/.claude/skills/my-skill/SKILL.md << 'EOF'
---
name: my-skill
description: |
  スキルの説明。どんなときに使うかを明記。
  「〜して」「〜を確認して」などの依頼時に使用。
---

# My Skill

## Instructions
指示内容をここに記述
EOF

SKILL.md の構造

---
name: skill-name
description: |
  スキルの説明（重要！）
  - 何をするスキルか
  - どんなときに使うか
  - トリガーとなるキーワード
allowed-tools: Read, Grep, Glob  # オプション
---

# Skill Name

## Instructions
実際の指示内容

## References
- [詳細ガイド](references/detail.md)

必須フィールド

description の書き方（重要）

悪い例:

description: ドキュメント処理

良い例（1行形式 - 推奨）:

description: "PDF ファイルからテキストと表を抽出、フォームに入力。PDF ファイルを扱う場合や、PDF、フォーム、ドキュメント抽出について言及した場合に使用。"

注意: マルチライン形式は避ける

# これは認識されないことがある
description: |
  PDF ファイルからテキストと表を抽出...

YAMLのマルチライン形式（|や>）はClaude Codeで正しく読み取られないことがあるため、1行のダブルクォート形式を推奨。

スキルの有効化・確認

自動有効化

descriptionが適切であれば、スキルは配置するだけで自動的に有効になり、Claudeが自動で使用を判断する。

有効なスキルの確認

Claude Codeで以下を質問：

利用可能なスキルをリストしてください

または

What skills are available?

スキルの無効化・削除

削除する場合

# ユーザースキル
rm -rf ~/.claude/skills/skill-name

# プロジェクトスキル
rm -rf .claude/skills/skill-name
git commit -m "Remove skill"

プラグインスキルを無効化

.claude/settings.jsonまたは~/.claude/settings.jsonで：

{
  "enabledPlugins": {
    "skill-name@plugin-name": false
  }
}

settings.json でのスキル権限設定

スキルが使用するツールの権限を設定：

{
  "permissions": {
    "allow": [
      "Skill(honda-sakubun)",
      "Skill(content-management)"
    ]
  }
}

ディレクトリ構成例

.claude/
└── skills/
    └── honda-sakubun/
        ├── SKILL.md              # 必須：メインファイル
        └── references/           # オプション：詳細ガイド
            ├── modification-order.md
            ├── punctuation.md
            └── particles.md

トラブルシューティング

Claude がスキルを使わない

1. descriptionを確認 - 具体的で、トリガーキーワードを含んでいるか
2. ファイルパスを確認 - SKILL.mdが正しい場所にあるか
3. YAML構文を確認 - ---で囲まれているか、インデントは正しいか

スキルが認識されない

# ファイルが正しく配置されているか確認
ls -la ~/.claude/skills/*/SKILL.md
ls -la .claude/skills/*/SKILL.md

スキルが効果的な分野

向いている分野

1. 専門知識が必要な分野

2. 繰り返し行うワークフロー

• コードレビュー（チームのコーディング規約に沿って）
• 翻訳チェック（英日の定訳リスト適用）
• PR/コミットメッセージの校正

3. 「暗黙知」を形式知化したい場合

honda-sakubunスキル（『日本語の作文技術』ベース）がまさにこれ：

• 本を読んでも実践が難しい
• ルールが体系化されている
• チェックリスト化できる

4. チーム固有のルール

例: 社内文書スキル
- 「弊社」ではなく「当社」を使う
- 数字は半角、単位は全角
- 見出しは体言止め禁止

向いていない分野

スキル化の判断基準

「毎回同じことを説明している」「ルールがあるのに守られない」と感じる分野がスキル化の候補

参考リンク

• Claude Code 公式ドキュメント
• Agent Skills