はじめに
60行のMarkdownを書いたら、毎回30分かけていたCRUD生成が10分で終わるようになった。
やったのは SKILL.md というファイルに手順を書いただけ。プロンプトの工夫も、外部ツールの導入も不要だった。
この記事では、ゼロからSkillを自作して動かすまでをハンズオン形式で解説する。所要時間は約15分。
実際のプロジェクトで運用されているSkillsの実例はSkills Pack（無料あり）で公開しています。SKILL.mdの設計パターンの参考にどうぞ。
Skillsとは何か（30秒で理解）
Skillsは SKILL.md というMarkdownファイル。このファイルに**ワークフロー（手順書）**を書くと、Claude Codeがその手順に従って動作する。
SKILL.md = 熟練エンジニアの作業手順書をAIに読み込ませるもの
具体的には：
- 「テストを先に書く」→ TDDワークフロー
- 「要件を確認してから実装する」→ 要件定義ワークフロー
- 「3案比較してから選ぶ」→ 設計レビューワークフロー
CLAUDE.mdとの違い:
| CLAUDE.md | SKILL.md | |
|---|---|---|
| 役割 | プロジェクト全体のルール | 特定タスクのワークフロー |
| 適用範囲 | 常に適用 | 該当タスク時のみ |
| 例 | 「Python 3.12を使う」 | 「API設計の手順」 |
効果: CLAUDE.mdが「憲法」なら、SKILL.mdは「業務マニュアル」。組み合わせることでAIの出力品質が安定する。
ハンズオン: CRUDジェネレーターを作る
実際に手を動かして、FastAPIのCRUDエンドポイントを自動生成するSkillを作る。
Step 1: ディレクトリ構成
mkdir -p ~/.claude/skills/crud-generator
1コマンドで完了。特別な設定ファイルやビルドツールは不要。
効果: セットアップ所要時間は10秒。
Step 2: SKILL.mdを書く
---
name: crud-generator
description: FastAPIのCRUDエンドポイントをモデル定義から自動生成する。
「CRUDを作って」「APIを生成して」で起動する。
---
# CRUD Generator
FastAPIのCRUDエンドポイントを対話的に生成するスキル。
## ワークフロー
### Step 1: モデル情報の確認
ユーザーに以下を確認する:
- モデル名（例: User, Product, Order）
- フィールド一覧（名前、型、必須/任意）
- リレーション（他モデルとの関連、あれば）
### Step 2: ファイル生成
以下のファイルを順番に生成する:
1. **Pydanticスキーマ** (`schemas/{model_name}.py`)
- CreateSchema, UpdateSchema, ResponseSchema の3つ
- バリデーション付き
2. **CRUDルーター** (`routers/{model_name}.py`)
- GET /（一覧取得、ページネーション付き）
- GET /{id}（詳細取得）
- POST /（作成）
- PUT /{id}（更新）
- DELETE /{id}（削除）
3. **テスト** (`tests/test_{model_name}.py`)
- 各エンドポイントの正常系テスト
- バリデーションエラーの異常系テスト
### Step 3: 動作確認
生成したコードが既存のプロジェクト構成と整合するか確認する。
main.pyへのルーター登録コードも提示する。
## 鉄則（Iron Laws）
- フィールドにpasswordがある場合、レスポンスには含めない
- DELETEは論理削除（is_deletedフラグ）をデフォルトとする
- ページネーションは必ず付ける（デフォルト: 20件/ページ）
これだけで完了。たった60行のMarkdownで、CRUDの自動生成ワークフローが完成した。
効果: スキル定義の作成時間は15分。一度書けば何度でも再利用できる。
Step 3: 使ってみる
Claude Codeを起動して、こう話しかけるだけ:
「Productモデルの CRUD を作って。
フィールド: name(str,必須), price(int,必須), description(str,任意), stock(int,デフォルト0)」
Skillが自動で読み込まれ、以下が順番に生成される:
-
schemas/product.py- 3つのPydanticスキーマ -
routers/product.py- 5つのエンドポイント -
tests/test_product.py- 正常系+異常系テスト
鉄則（Iron Laws）も自動適用されるため、ページネーションの付け忘れや、パスワードのレスポンス漏れといったミスが構造的に発生しなくなる。
効果: CRUD生成が30分→10分に短縮（-67%）。セキュリティルールの適用漏れゼロ。
Skill設計の5つのコツ
コツ1: 「対話型」にする
ユーザーに確認してから動くスキルの方が、汎用性が高くなる。
OK: 「ユーザーにモデル名とフィールドを確認する」
NG: 「Userモデルを生成する」（固定値はスキルにしない）
効果: 1つのスキルで複数モデルに対応。スキルの再利用率が上がる。
コツ2: 鉄則（Iron Laws）を定義する
「絶対に破ってはいけないルール」を明記する。これが品質の一貫性を担保する。
## 鉄則
- SQL文の直書き禁止（ORMを必ず使う）
- 環境変数のハードコード禁止
- テストなしの完了禁止
効果: パスワード漏れ・SQL直書きなどを構造的に防止。レビュー指摘が減る。
コツ3: フェーズゲートを入れる
各ステップの完了条件を明示すると、スキルが「やりっぱなし」にならなくなる。
### Step 2の完了条件
- [ ] スキーマファイルが生成されている
- [ ] 全フィールドにバリデーションが付いている
- [ ] ユーザーに確認を取っている
効果: 中間成果物の品質チェックが自動化。手戻り60%減。
コツ4: 出力フォーマットを固定する
毎回同じ形式で出力させると、後工程が楽になる。
## 出力フォーマット
生成完了後、以下のサマリを表示する:
| ファイル | パス | 行数 |
|---------|------|------|
| スキーマ | schemas/xxx.py | xx行 |
| ルーター | routers/xxx.py | xx行 |
| テスト | tests/test_xxx.py | xx行 |
効果: 出力のばらつきゼロ。チーム全員が同じフォーマットで確認できる。
コツ5: 小さく始めて育てる
最初から完璧なスキルを目指す必要はない。
v1: 基本的なCRUD生成（30行）
v2: バリデーション追加（+10行）
v3: テスト生成追加（+15行）
v4: ページネーション対応（+5行）
使いながら育てるのが一番効率的。
効果: 30行から始めて段階的に拡張。初日から実務で使える。
応用例: こんなSkillも作れる
| Skill | 用途 | 難易度 | 期待効果 |
|---|---|---|---|
| pr-reviewer | PR作成時に自動レビュー | 低 | レビュー待ち時間ゼロ |
| api-doc-generator | OpenAPIドキュメント自動生成 | 中 | ドキュメント作成工数-80% |
| migration-helper | DB マイグレーション生成 | 中 | マイグレーション作業を半自動化 |
| deploy-checker | デプロイ前のチェックリスト実行 | 低 | デプロイ事故を構造的に防止 |
| incident-responder | 障害対応の手順書に従って調査 | 高 | 初動対応の属人化を解消 |
まとめ
| ポイント | 内容 | 効果 |
|---|---|---|
| Skillsとは | ワークフローを定義したMarkdownファイル | 手順書がそのまま自動化に |
| 作り方 | SKILL.mdに手順・鉄則・完了条件を書くだけ | 15分で作成完了 |
| CRUD生成 | 60行のMarkdownで自動化 | 30分→10分（-67%） |
| 5つのコツ | 対話型 + 鉄則 + フェーズゲート + 出力固定 + 小さく始める | 品質のばらつきゼロ |
| 始め方 | 小さく作って育てる | 30行から即実務投入 |
まずは普段繰り返している作業を1つ選んで、SKILL.mdに書いてみてほしい。15分の投資で、以後のすべての同種タスクが1/3の時間で終わる。
関連記事
- 【実践】Claude Codeの開発速度を2倍にする10のTips - Skills以外の効率化テクニック集
- 【実践編】CLAUDE.mdの書き方 - コピペで使えるテンプレートと設計パターン - Skillsと組み合わせるCLAUDE.mdの書き方
- 【検証】Claude Codeの実装時間を56%短縮した5つの仕組み - Skillsの効果を定量検証
- 【警告】無料のClaude Code Skills、3つに1つにセキュリティ問題 - 外部Skillsを使う前に確認すべきこと
- 【Claude Code Skills】superpowers - AIエージェント向け開発ワークフローの決定版を徹底解説 - 高品質なSkillsの設計パターン
プロが設計したSKILL.mdを参考にしたい方へ
Pro Packには21エージェント分のSKILL.mdが含まれています。Iron Laws、Phase Gate、Drift Detectionなど、この記事で紹介した設計パターンの実装例としても活用できます。