プロンプトの手書きにうんざり？Claude Code のこの機能で効率が 3 倍に

ある実話

昨年 10 月、React プロジェクトのリファクタリングを任されました。2000 行超の God Class があり、見るだけで頭が痛くなります。Claude Code にコード最適化を頼むたび、毎回同じ指示を繰り返していました。

• 「TypeScript の strict モードを使うこと」
• 「API 呼び出しにはエラー処理を入れること」
• 「コンポーネントは単一責任の原則に従うこと」

これらをコピペするだけで、少なくとも 2〜3 分。さらに厄介なのは、十数ターン話したあと、Claude Code が最初の要件を「忘れ」、規約外のコードを書き始めることでした。

ドキュメントで Skill 機能を見つけるまでは。

1 週間試したあと、繰り返しの要件を skill ファイルにまとめました。今は @skill react-refactor と言うだけで、Claude Code が即座に動き方を理解します。2000 行のクラスは、当初 3 日かかる見込みでしたが、2 つの午後で完了しました。

Skill とは何か

要するに、Skill は Claude Code にスキルパッケージを装備させる機能です。

.claude/skills/ に Markdown ファイルを置き、よく使うプロンプト、ワークフロー、コード規約を書き込みます。必要なときは @skill スキル名 で呼び出せます。ゲームでキャラにスキルを装備するイメージ——火力が要るときは攻撃、タンクが要るときは防御。

最もシンプルな例を見てみましょう。

---

title: "React コードレビュー専門家"
description: "React コードの品質、パフォーマンス、ベストプラクティスを専門に審査"

---

# React コードレビューフロー
あなたは経験豊富な React コードレビュー専門家です。以下の基準でコードを審査してください。
## 審査の重点
1. **コンポーネント設計**
   - 単一責任の原則
   - Props 型定義の完全性
   - コンポーネント分割の妥当性
2. **パフォーマンス最適化**
   - 不要な再レンダリング
   - useMemo / useCallback の使用
   - リストレンダリングの key
3. **コード品質**
   - TypeScript の型安全性
   - エラー境界処理
   - アクセシビリティ（a11y）
## 出力フォーマット
- 問題リスト（深刻度順）
- 具体的なコード提案
- 優先度（P0 / P1 / P2）

.claude/skills/react-review.md として保存すれば、React コードレビュー時は @skill react-review だけ。Claude Code は定義した基準どおりに審査します。

手書きプロンプトでは限界が来る

以前はプロンプトエンジニアとして、Notion に数十のテンプレートを溜めていました。数ヶ月使うと、致命的な弱点が見えてきます。

繰り返し作業が多すぎる

毎回 Notion からコピペし、プロジェクトに合わせて言葉を直す。1 日のうち、プロンプトのコピペだけで 30 分は消えます。

バージョン管理が混乱する

Alibaba Cloud - 開発者向けクラウドの第一候補、Lighthouse サーバー15%OFF、プロジェクトの迅速な立ち上げを支援

15%割引を入手 →広告

今日のプロンプトと先週のが違い、効果もブレる。「前にうまくいった版」に戻りたくても、見つかりません。

チーム共有が地獄

良いプロンプトを同僚に渡す？ 手動でチャット。同僚が改善した？ また手動で同期。石器時代と変わりません。

AI は忘れる

長い会話では、Claude Code は最初の要件を忘れがち。20 ターン目あたりで、以前「やるな」と言ったミスをまた犯し始めます。

Skill はこれらを一気に解決します。

• バージョン化：Git 管理でいつでも巻き戻せる
• 共有可能：チームリポジトリを pull すれば全員同期
• 常に有効：会話が長くてもルールが消えない

"Skill の核心は再利用性と一貫性。プロンプトエンジニアリングを、メンテナンス可能で共有可能なプロジェクト資産に変える。"

最初の Skill：API インターフェースジェネレーター

EC プロジェクトで、バックエンドから 100 超の Swagger ドキュメントが投げられました。手動連携なら、1 インターフェースあたり次を書く必要があります。

1. TypeScript 型定義
2. axios リクエスト関数
3. エラー処理ロジック
4. loading 状態管理

100 個で約 30 時間。1 時間かけて api-generator skill を書きました。

---

title: "API インターフェースコードジェネレーター"
description: "API ドキュメントから TS 型定義と axios ラッパーを生成"
version: "1.3.0"

---

# API コード生成の専門家
あなたはフルスタックエンジニアで、前後端インターフェース連携が得意です。API ドキュメントから高品質な TypeScript コードを生成してください。
## 生成内容
### 1. TypeScript 型定義
```typescript
// リクエストパラメータ型
interface GetUserRequest {
  userId: string;
  includeDetails?: boolean;
}
// レスポンスデータ型
interface GetUserResponse {
  id: string;
  name: string;
  email: string;
  createdAt: string;
}

2. Axios リクエスト関数

import request from '@/utils/request';
export const getUserAPI = async (
  params: GetUserRequest
): Promise<GetUserResponse> => {
  try {
    const response = await request.get<GetUserResponse>('/api/user', { params });
    return response.data;
  } catch (error) {
    console.error('ユーザー情報の取得に失敗しました:', error);
    throw error;
  }
};

3. React Hook ラッパー（任意）

export const useGetUser = (userId: string) => {
  const [data, setData] = useState<GetUserResponse | null>(null);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState<Error | null>(null);
  useEffect(() => {
    const fetchData = async () => {
      setLoading(true);
      try {
        const result = await getUserAPI({ userId });
        setData(result);
      } catch (err) {
        setError(err as Error);
      } finally {
        setLoading(false);
      }
    };
    fetchData();
  }, [userId]);
  return { data, loading, error };
};

コード規約

• 命名はキャメルケース
• API 関数は API で終わる
• Hook 関数は use で始める
• 非同期関数はすべてエラー処理を入れる
• エクスポートする型・関数に JSDoc を付ける

出力フォーマット

1. 型定義を先に出力
2. 続けて API 関数
3. 常用インターフェースなら Hook ラッパーも
4. 最後に使用例

1 インターフェースの連携が 30 分から 5 分に。100 個は 2 日で完了。新人も同じ規約でコードを生成でき、プロジェクト全体のスタイルが揃いました。

## 上級編：Skill を連携させる

慣れると、単体 skill では足りません。実務では複数 skill の連携が前提になります。

古いコードをリファクタリングするときの標準フローはこうです。

```bash
# ステップ 1：コード問題の分析
@skill code-analyzer src/legacy/UserService.ts
# ステップ 2：リファクタリング計画
@skill refactor-planner
# ステップ 3：テストケース生成（リファク前の保険）
@skill test-generator
# ステップ 4：リファクタリング実行
（手動、または Claude Code に補助させる）
# ステップ 5：最終コードレビュー
@skill code-reviewer

4 つの skill を順に呼び出し、リファクタリングのワークフローを完成させます。自動実行用の shell スクリプトも書きました。

#!/bin/bash
# refactor-workflow.sh
echo "🔍 ステップ 1/4: コード問題を分析..."
claude-code @skill code-analyzer $1
read -p "Enter で続行..."
echo "📋 ステップ 2/4: リファクタリング計画..."
claude-code @skill refactor-planner
read -p "Enter で続行..."
echo "🧪 ステップ 3/4: テストケース生成..."
claude-code @skill test-generator
read -p "テスト通過を確認したら Enter..."
echo "✅ ステップ 4/4: 最終コードレビュー..."
claude-code @skill code-reviewer

2000 行の God Class を 7 つの小さなクラスに分割。テストカバレッジは 40% から 85% へ。想像以上にスムーズでした。

チーム共有：Skill をインフラとして扱う

チームでは skill をインフラとして管理しています。team-skills 専用 Git リポジトリを用意しました。

team-skills/
├── frontend/
│   ├── react-review.md          # React コードレビュー
│   ├── vue-component-gen.md     # Vue コンポーネント生成
│   └── css-optimizer.md         # CSS パフォーマンス最適化
├── backend/
│   ├── api-design.md            # API 設計規約
│   ├── database-review.md       # データベースレビュー
│   └── security-audit.md       # セキュリティ監査
└── common/
    ├── code-cleaner.md          # コードクリーナー
    ├── test-generator.md        # テスト生成
    └── commit-msg.md            # Git コミットメッセージ生成

各開発者はローカルプロジェクトからシンボリックリンクで接続します。

# 初回設定
git clone git@github.com:your-team/team-skills.git ~/.team-skills
ln -s ~/.team-skills/* .claude/skills/

効果はすぐに出ます。

• 新人フレンドリー：入社初日から skill ライブラリが揃い、規約どおりに書ける
• 自動同期：skill 更新後は git pull で全員が最新版を取得
• コードの統一：誰が書いてもスタイルが揃う

先月入ったインターンは、2 日目からチーム規約に沿ったコードを書いていました。以前なら最低 1 週間の研修が必要だったはずです。

Skill と CLAUDE.md は黄金コンビ

Skill の真価は、プロジェクトルートの CLAUDE.md との併用にあります。

CLAUDE.md でグローバルルールを定義します。

# プロジェクトコンテキスト
- 技術スタック：React 18 + TypeScript 5.0 + Vite 4
- コード規約：Airbnb ESLint ルール
- コミット規約：Conventional Commits
- 状態管理：Zustand（Redux 禁止）
## 重要な約束事
- すべてのコンポーネントに完全な TypeScript 型定義
- API 呼び出しは src/utils/request.ts に統一
- コンポーネントファイル名は PascalCase（例：UserProfile.tsx）
- ユーティリティ関数ファイル名は camelCase（例：formatDate.ts）
## ディレクトリ構造
src/
├── components/    # 共通コンポーネント
├── pages/        # ページコンポーネント
├── hooks/        # カスタム Hooks
├── utils/        # ユーティリティ関数
├── services/     # API サービス
└── stores/       # Zustand 状態管理

skill 側でこれらを参照します。

---

title: "React コンポーネントジェネレーター"

---

# コンポーネント生成指示
CLAUDE.md で定義された技術スタック、ディレクトリ構造、命名規則に厳密に従って React コンポーネントを生成してください。
生成コンポーネントは以下を満たすこと：
- TypeScript を使用
- プロジェクトの ESLint ルールに適合
- 正しいディレクトリに配置
- プロジェクトの状態管理方針に従う

skill が CLAUDE.md を読み込み、規約どおりのコードを生成します。新規クローンでもすぐ適応できます。

Railway - モダンなデプロイプラットフォーム、煩わしい運用から解放、数分で公開

今すぐ始める →広告

私の 5 つの必須 Skill

半年で 20 超の skill を蓄積しました。特に使う 5 つを紹介します。

1. テストケースジェネレーター（test-gen.md）

機能コードを書いたあとのテスト追加が面倒——この skill は関数ロジックを分析し、境界値・異常系を含む単体テストを自動生成します。

効果：カバレッジ 40% → 85%、テスト記述時間は半分以下に。

2. Git コミットメッセージジェネレーター（commit-msg.md）

コミットのたびに message を考えるのはもったいない。git diff を分析し、Conventional Commits 準拠のメッセージを生成します。

出力例：

feat(user-auth): OAuth2.0 ログイン機能を追加
- Google / GitHub サードパーティログインを統合
- JWT トークンリフレッシュ機構を追加
- ユーザー権限検証ミドルウェアを改善
Closes #123

30 行だけど毎日使う skill。累計で数時間は節約しています。

3. コードリファクタリングアシスタント（refactor.md）

古いコードの改善ポイントがわからないとき——

• コードスメルを特定
• リファクタリング優先度を整理
• ステップバイステップの計画を提示
• リファク前後の機能一致を担保

2000 行の God Class はこの skill で突破しました。

4. セキュリティレビュー専門家（security-audit.md）

セキュリティ観点のチェックに特化。

• SQL インジェクション
• XSS 対策
• 機密情報漏洩
• 権限チェックの完全性

リリース直前にスキャンしたら、潜在脆弱性が 3 件見つかり、冷や汗をかきました。

5. ドキュメントジェネレーター（doc-gen.md）

ドキュメントがコードに追いつかない問題——コードから API ドキュメントを生成し、関数コメントを Markdown に抽出、更新ログも維持します。

更新時間は 2 時間 → 10 分。「コードだけ変わってドキュメントが古い」は起きなくなりました。

良い Skill を書く 5 つのコツ

半年でまとめた作成のコツです。

1. Frontmatter を真面目に書く

title と description は skill 一覧に表示されます。

---

title: "フルスタックコードレビュー専門家"
description: "前後端コードを審査し、セキュリティ・パフォーマンス・保守性に焦点"
version: "2.1.0"
tags: ["コードレビュー", "セキュリティ", "パフォーマンス"]

---

version はバージョン管理、tags は分類検索に便利です。

2. 役割定義をはっきりさせる

「あなたは…の専門家です」という書き出しは効果的。Claude Code がすぐ役に入ります。

あなたは 10 年の経験を持つフルスタックエンジニアで、コードレビューとセキュリティ監査が得意です。

「コードをレビューして」よりずっと精度が上がります。

Vultr - 高性能NVMeクラウドサーバー、世界32拠点、Dockerワンクリック展開対応

価格を見る →広告

3. 対比例で説明する

✅ / ❌ で良い例・悪い例を示すと、Claude Code の理解が正確になります。

### SQL インジェクションリスク
❌ 危険な書き方：
```javascript
const query = `SELECT * FROM users WHERE id = ${userId}`;

✅ 安全な書き方：

const query = 'SELECT * FROM users WHERE id = ?';
db.query(query, [userId]);

### 4. 出力フォーマットを具体化する

「提案をください」ではなく「以下の形式で出力」と指定します。

```markdown
## 出力フォーマット
### 🔴 深刻な問題（修正必須）
- [ファイル名:行番号] 問題の説明
- リスク
- 修正提案（コード例付き）
### 🟡 改善提案（推奨）
- [ファイル名:行番号] 問題の説明
- 改善理由
- 最適化案

5. エラー処理ルールを入れる

問題発生時の振る舞いを明示します。

## エラー処理
以下の場合：
- 構文エラー：位置を指摘し、審査を中断
- ファイルアクセス不可：パス確認を促す
- コード量が多い（>5000 行）：分割審査を提案

よくある質問

Skill 名を覚えきれない？

命名規則を使いましょう。

• review-*：コードレビュー系
• gen-*：コード生成系
• util-*：ユーティリティ系
• fix-*：修正系

例：review-frontend.md、gen-api.md、util-commit.md

出力が長すぎる？

skill に簡潔モードを追加します。

デフォルトは詳細モード。ユーザーが `--brief` を付けたら簡潔版：
- 問題一覧（1 行 1 件）
- 深刻度
- 主要な修正提案

プロジェクトごとに挙動がブレる？

skill にコンテキスト取得を組み込みます。

## 分析の前提ステップ
開始前に：
1. package.json で依存バージョンを確認
2. tsconfig.json で TS 設定を確認
3. .eslintrc でコード規約を確認
4. README.md でプロジェクト構成を把握

最後に

Skill を半年使って、開発効率は少なくとも 40% 向上しました。繰り返しの知的作業から解放され、アーキテクチャ設計やビジネスロジックに時間を使えるようになりました。

まだ手書きプロンプトなら、次の 4 点から始めてください。

1. 今日から：コードレビューやテスト生成など、シンプルな skill から
2. 少しずつ改善：使うたびに更新し、バージョンを上げる
3. チームで共有：良い skill は良いツールキット——共有する価値がある
4. 継続学習：公式ドキュメントの更新を追う。書き方が変わることもある

一点だけ：Skill の価値は複雑さではなく、実問題を解くこと。30 行の commit-msg ジェネレーターが、毎日使えて累計数時間を救っています。

毎日繰り返しているプロンプトを skill に整理してみてください。3 ヶ月後、今日の自分に感謝するはずです。

関連リソース

• Claude Code 公式ドキュメント
• Skill ベストプラクティスガイド
• コミュニティ Skill テンプレート