はじめに

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など、この記事で紹介した設計パターンの実装例としても活用できます。

Security Scanner（¥2,980）: セキュリティスキャナーのSKILL.md設計も参考例として活用可能 → 詳細を見る
Pro Pack（¥4,980）: スキャナー含む全部入り。21エージェント分のSKILL.md設計パターン集 → 詳細を見る
Starter Pack（無料）: superpowers-jpのSKILL.mdを参考例として → 無料ダウンロード