Claude Code Skillsの使い方と汎用テンプレート公開

アドベントカレンダー6日目の記事です。

今回はClaude Codeを使っていて「毎回同じ説明をするのが面倒」「プロジェクト固有のルールを覚えさせたい」という問題を解決する方法を紹介します。

また今回Web開発に使えそうな汎用Skillsのテンプレートを作成し、Githubで公開しましたのでぜひ本記事を読む際に参考にしていただき、よりよいスキルセットがあればPRお待ちしています。

https://github.com/atomic-kanta-sasaki/claude-code-general-skills/tree/main/.claude/skills

Skillsとは何か？

Skillsは、Claudeに特定のタスクの実行方法を教えるためのナレッジパッケージです。

公式ドキュメントでは以下のように説明されています：

Skillsはフォルダ内の指示、スクリプト、リソースで、Claudeが特定のタスクを繰り返し実行する方法を教えます。

簡単に言えば、新しいチームメンバーに渡すオンボーディング資料のようなものです。プロジェクトの規約、ツールの使い方、ワークフローを文書化しておけば、Claudeがそれを参照して作業してくれます。

Skillsの特徴

• 自動呼び出し: ユーザーが明示的に指定しなくても、タスクに応じてClaudeが自動で適切なスキルを選択
• プログレッシブ・ディスクロージャー: 必要な情報だけを段階的に読み込むため、コンテキストを圧迫しない
• コード実行可能: 指示だけでなく、Pythonスクリプトなども含められる

Skillsとサブエージェント・CLAUDE.mdの違い

Claude Codeには似たような機能がいくつかあります。違いを整理しておきましょう。

使い分けの指針

• Skills: 特定タスク（レビュー、テスト作成など）の専門知識
• Subagents: 独立したコンテキストで並列作業させたい場合
• CLAUDE.md: プロジェクト全体で常に参照すべき情報
• Commands: よく使うプロンプトのショートカット

Skillsのディレクトリ構造

Skillsは以下の場所に配置します：

.claude/skills/
└── your-skill-name/
    ├── SKILL.md           # 必須：メインの指示ファイル
    ├── reference.md       # 任意：参照ドキュメント
    ├── examples.md        # 任意：使用例
    ├── scripts/           # 任意：ヘルパースクリプト
    │   └── helper.py
    └── templates/         # 任意：テンプレートファイル
        └── template.txt

配置場所による違い

SKILL.md の書き方

基本構造

---
name: your-skill-name
description: |
  このスキルが何をするか、いつ使うべきかの説明。
  具体的なトリガーワードや使用シーンを含める。
version: 1.0.0
---

# Your Skill Name

## Overview
このスキルの概要説明

## Instructions
ステップバイステップの指示

## Examples
具体的な使用例

フィールドの説明

descriptionの書き方（最重要ポイント）

Skillsが正しく呼び出されるかどうかは、descriptionの書き方で9割決まります。

Claudeはdescriptionを見て「このスキルを使うべきか」を判断するため、曖昧な記述では呼び出されません。

 悪い例

description: コードを手伝う

これでは「いつ」「何を」手伝うのかわかりません。

良い例

description: |
  Pythonコードのセキュリティレビューを実施。
  OWASP Top 10に基づく脆弱性チェック、認証・認可の検証、入力バリデーション確認。
  セキュリティチェック、脆弱性診断、コードのセキュリティ評価時に使用。

良いdescriptionのポイント：

1. 具体的な動作: 何をするスキルか明確に
2. トリガーワード: どんな言葉で呼び出されるべきか
3. 使用シーン: どんな状況で使うか
4. 境界線: 何に使わないか（オプション）

Skillsの呼び出しの仕組み

プログレッシブ・ディスクロージャー

Skillsは段階的に情報を読み込む設計になっています：

1. 起動時
   └─ 全スキルの name と description だけを読み込み
   
2. ユーザーリクエスト受信
   └─ description を参照してマッチするスキルを判断
   
3. スキル選択時
   └─ SKILL.md の本文を読み込み
   
4. 必要に応じて
   └─ scripts/ や references/ を読み込み

この設計により、多数のスキルをインストールしても、実際に使うスキルの情報だけがコンテキストを消費します。

スクリプトの活用

Skillsの強力な機能の1つが、Pythonスクリプトの実行です。

指示だけでは不確実な処理（フォーマット、バリデーションなど）をスクリプトで確実に実行できます。

例：フォーマッタースキル

---
name: python-formatter
description: |
  Pythonコードをプロジェクト標準にフォーマット。
  Black, isort, ruffを適用。Pythonファイルの整形時に使用。
version: 1.0.0
---

# Python Formatter

## Workflow

### Step 1: フォーマット実行
Run: `python .claude/skills/python-formatter/scripts/format.py <file>`

### Step 2: 結果確認
フォーマット結果を確認し、問題があれば報告。

# scripts/format.py
import subprocess
import sys

def main():
    file = sys.argv[1]
    subprocess.run(["black", file])
    subprocess.run(["isort", file])
    print(f" Formatted: {file}")

if __name__ == "__main__":
    main()

スクリプトのメリット

• 確実性: LLMの揺らぎなく、決まった処理を実行
• コンテキスト節約: スクリプトの内容ではなく、出力だけがトークンを消費
• 再利用性: 同じスクリプトを複数のスキルで共有可能

Skillsが有効なケース・有効でないケース

 有効なケース

1. 定型的なレビュー作業: セキュリティチェック、コード品質チェック
2. ドキュメント生成: API仕様書、README、ADRなど
3. フォーマット・バリデーション: スクリプトと組み合わせて確実に実行
4. プロジェクト固有のルール適用: ブランドガイドライン、コーディング規約

 有効でないケース

1. 創造的なタスク: アイデア出し、自由な設計
2. 対話的な作業: フィードバックを受けながら進める作業
3. コンテキスト依存の判断: プロジェクト全体を俯瞰した判断
4. 単純な質問応答: スキルを使うまでもないタスク

ベストプラクティス

1. スキルはフォーカスを絞る

1つのスキルに複数の機能を詰め込まず、目的別に分割しましょう。

❌ code-helper（何でもやる）
✅ security-review（セキュリティ特化）
✅ test-generator（テスト生成特化）
✅ api-design（API設計特化）

2. SKILL.mdは500行以下に

長すぎるスキルはコンテキストを圧迫します。詳細は別ファイルに分割し、SKILL.mdはメニューとして機能させましょう。

3. 具体例を含める

Claudeが「成功とは何か」を理解できるよう、入出力の例を含めましょう。

4. 制限事項を明記する

スキルができないことを明示すると、誤用を防げます。

セキュリティ上の注意

Skillsは強力な機能ですが、注意点もあります：

• 信頼できるソースのみ使用: 自作またはAnthropicの公式スキルを推奨
• APIキーをハードコードしない: 環境変数を使用
• ダウンロードしたスキルは監査: 実行前にスクリプトの内容を確認

まとめ

Claude Code Skillsは、AIコーディングを「汎用アシスタント」から「プロジェクト専門家」に進化させる機能です。

ポイントをまとめると：

1. descriptionが命: 適切に書かないと呼び出されない
2. 段階的読み込み: 多数のスキルを入れてもパフォーマンスに影響しにくい
3. スクリプト活用: 確実に実行したい処理はコード化
4. フォーカスを絞る: 1スキル1目的で設計

まずはシンプルなスキルから始めて、徐々に拡張していくのがおすすめです。

次の記事では、Web開発で使い回せる汎用スキル集を紹介します。

この記事はClaude Code公式ドキュメントおよび実際の検証に基づいて作成しています。