AI Skillの手書きガイド：Claude Codeで繰り返し使える「専門能力モジュール」を作る
「AIに同じ説明を何度もしている」
技術ブログを書くたび、コードレビューを依頼するたび、ドキュメントを整形するたび——同じような指示を繰り返していないか。「丁寧に書いて」「日本語で」「コードブロックを忘れずに」。これらは一時的なプロンプトではなく、AIに定着させたい「習慣」だ。
Claude CodeのSkillは、この「習慣」をモジュール化する仕組みだ。一度書けば、次回からは名前だけで呼び出せる。しかし、ここで多くの人が陥る罠がある：「指示」を書いて満足してしまうこと。
「丁寧に書いて」は原則だ。Skillは原則を書く場所ではない。**手順を書く場所だ。**この違いを理解しないままSkillを作ると、AIは動かない。動かないから使い続けない。使い続けないから、存在すら忘れる。
本記事では、Claude Codeで「動くSkill」を手書きする方法を解説する。初めて学ぶなら、手で書くのが一番早い。skill-creatorという自動生成ツールもあるが、最初は構造を理解するために、一度手書きすることをお勧めする。
1. 基本情報クイックリファレンス
| 項目 | 内容 |
|---|---|
| 名称 | Claude Code Skill |
| 役割 | AIの「専門能力モジュール」として定義・再利用 |
| 構成ファイル |
SKILL.md（必須）＋scripts//references//assets/（任意） |
| 配置場所 | .claude/skills/skill-name/ |
| 呼び出し方法 |
/skill-name または自然言語で自動トリガー |
| 学習コスト | 手書き：初回は30分程度。理解後は5分で新規作成可能 |
| 対象ユーザー | Claude Codeユーザー（CLI環境でAIエージェントを利用） |
Skillは「魔法のプロンプト」ではない。ディレクトリに整理されたファイル群だ。呼び出す側は /skill-name をタイプするだけで、Claude Codeが該当ディレクトリの内容を読み込み、そのタスク専用の「モード」に入る。
2. Skillのファイル構造
最小構成
skill-name/
└── SKILL.md # 必須：トリガー条件＋実行手順
推奨構成
skill-name/
├── SKILL.md # 必須：トリガー条件＋実行手順
├── scripts/ # 任意：再実行可能なスクリプト
│ ├── setup.sh
│ └── validate.py
├── references/ # 任意：長文ルール・仕様書・APIドキュメント
│ ├── style-guide.md
│ └── api-spec.yaml
└── assets/ # 任意：テンプレート・画像・素材
├── template.md
└── example.png
各ファイルの役割
| ファイル/フォルダ | 役割 | 例 |
|---|---|---|
SKILL.md |
トリガー条件（いつ発動するか）と実行手順（何をするか）を定義 | 「ユーザーが技術記事を書こうとした場合、このSkillを提案」 |
scripts/ |
再実行可能なシェルスクリプトやPythonコード |
setup.sh：プロジェクト初期化、validate.py：出力チェック |
references/ |
長いガイドラインや仕様書 | コーディング規約、API仕様、フォーマット要件 |
assets/ |
テンプレートや画像リソース | 記事テンプレート、図表のサンプル |
SKILL.mdだけで動く。ただし内容が長くなると読み込みが重くなるため、適切に分割することが望ましい。
3. SKILL.mdの書き方
SKILL.mdはYAMLのfrontmatterと、実行手順の本文で構成される。
frontmatterの必須項目
---
name: tech-blog-writer
description: "技術ブログ記事を作成・編集する。Zenn/Qiita形式に対応。"
---
| 項目 | 必須 | 説明 |
|---|---|---|
name |
✅ | Skillを呼び出す際の識別子。ディレクトリ名と一致させる |
description |
✅ | ここがトリガーの鍵。自然言語でSkillが自動発動する判定基準になる |
descriptionが不適切だと、Skillは呼び出されない。広すぎると誤発動する。狭すぎると発動しない。
❌ 悪いdescription例
description: "記事を書く" # 広すぎる。何の記事？
description: "Zennの記事で、タイトルが20文字以上の場合に、カテゴリがtechで..." # 狭すぎる
✅ 良いdescription例
description: "技術ブログ記事を作成・編集する。Zenn/Qiita形式に対応。"
description: "PRレビュー依頼メッセージを生成する。日本語・丁寧語で統一。"
本文の書き方：原則ではなく手順を書く
Skillは「AIへの指示書」だが、抽象的な指示は機能しない。
❌ 悪い例：原則を書いている
## 実行手順
1. 記事を丁寧に書いてください
2. コードブロックを適切に使ってください
3. 専門用語には配慮してください
「丁寧に」「適切に」「配慮」——AIはこれを解釈できない。人間なら文脈で補完できるが、AIにとっては「どうやって？」が残る。
✅ 良い例：手順を書いている
## 実行手順
1. 見出し構造を確認する（H1は記事タイトルのみ、H2以下は節）
2. コードブロックには言語指定を付ける（```python など）
3. 専門用語の初出には、括弧で英語表記を併記する
4. 各節の末尾に「まとめ」を置かない（最後に全体まとめを一本）
5. 公開前にリンク切れを確認する
具体的で、検証可能で、AIが機械的に実行できる手順。これがSkillを動かす鍵だ。
4. 必須：禁止事項を書く
Skillには「やるべきこと」と同時に「やってはいけないこと」を書く必要がある。禁止事項がないと、AIは「推測」で埋めようとする。
よくある禁止事項の例
## 禁止事項
- 架空のデータやケーススタディを作らない
- 出典のない統計や数字を使わない
- 「〜と言えるでしょう」「〜だと思われます」などの曖昧な表現を使わない
- ユーザーが提供していない情報を補完しない
禁止事項は、AIがやってしまいがちなことを列挙する。Claude Codeユーザーなら「勝手にファイルを書き換えられた」「架空のAPIエンドポイントを捏造された」といった経験があるだろう。これを防ぐのが、禁止事項セクションだ。
5. 手書き vs skill-creator：どちらを使うべきか
| 観点 | 手書き | skill-creator（自動生成） |
|---|---|---|
| 学習コスト | 高い（構造を理解する必要がある） | 低い（対話形式で生成） |
| 初回作成時間 | 30分〜1時間 | 5〜10分 |
| カスタマイズ性 | 高い（自由に記述） | 中程度（テンプレートベース） |
| スクリプト対応 | 手動で配置が必要 | 自動生成可能 |
| 適用場面 | 初学習・複雑なSkill・特殊要件 | 定型タスク・スクリプト連携あり |
どちらを選ぶべきか
初めてSkillを学ぶ場合：手書き
-
SKILL.mdの構造を理解できる -
descriptionの書き方を体験できる - 「動かない場合のデバッグ」が身につく
すでに構造を理解している場合：skill-creator
- 対話形式で効率的に作成できる
-
scripts/やreferences/の配置も自動化 - テンプレートから逸脱しない品質を担保
スクリプトやテンプレートを含む場合：skill-creator
-
scripts/以下の実行権限やパス設定を自動化 - アセットの配置ミスを防げる
6. メリットと制約
メリット
| 項目 | 説明 |
|---|---|
| 再利用性 | 一度書けば、何度でも /skill-name で呼び出し可能 |
| 一貫性 | 同じ品質・フォーマットでAIが作業する |
| 共有可能 | チーム内でSkillディレクトリを共有すれば、全員が同じ「習慣」を使える |
| バージョン管理 | GitでSkill自体をバージョン管理できる |
| 透明性 | プロンプトが可視化されているため、AIの振る舞いを追跡可能 |
制約
| 項目 | 説明 |
|---|---|
| 学習コスト | 初回は構造理解に時間がかかる |
| 呼び出し忘れ |
/skill-name をタイプしないと発動しない（自動トリガーにはdescriptionの調整が必要） |
| 内容の陳腐化 | プロジェクトの要件変更に合わせてSkillも更新が必要 |
| 分割の判断 | 内容が長くなった場合、いつreferences/に分割するかの判断が必要 |
7. 適合ユーザー
向いているユーザー
- 同じ種類のタスクを繰り返し依頼する
- AIの出力に一貫性を持たせたい
- チーム内でAIの振る舞いを標準化したい
- Gitで作業手順を管理したい
向いていないユーザー
- 毎回異なる種類のタスクを依頼する
- 一回きりの作業で終わる
- AIに「雰囲気」で指示を出すのが好み
- プロンプトの中身を気にしない
8. クイックスタート：6ステップでSkillを作成
ステップ1：解決する問題を明確にする
Skillは「何でも屋」ではなく「専門家」だ。範囲を狭く定義する。
例：
- ✅ 「技術ブログ記事の執筆支援」
- ❌ 「文章を書く」
ステップ2：ディレクトリを作成
mkdir -p .claude/skills/tech-blog-writer
cd .claude/skills/tech-blog-writer
ステップ3：frontmatterを書く
---
name: tech-blog-writer
description: "技術ブログ記事を作成・編集する。Zenn/Qiita形式に対応。"
---
ステップ4：実行手順を具体的に書く
## トリガー条件
ユーザーが以下のような発言をした場合に発動：
- 「記事を書きたい」「ブログ書いて」
- 「Zennに投稿する」「Qiitaの記事」
- 「技術記事のテンプレート」
## 実行手順
1. 記事のテーマをユーザーに確認する
2. 以下の構造でドラフトを作成する：
- タイトル（H1）
- はじめに（200字程度）
- 本文（H2セクション複数）
- まとめ（300字程度）
3. コードブロックには言語指定を付ける
4. 専門用語の初出には英語表記を括弧で併記
5. リンク切れを確認してから完成とする
## 禁止事項
- 架空のデータやケースを作らない
- 出典のない統計を使わない
- ユーザーが提供していない情報を補完しない
ステップ5：トリガーをテスト
Claude Codeで以下を入力：
技術記事を書きたい。テーマは「Docker入門」。
descriptionが適切なら、Skillが自動的に読み込まれ、「Docker入門」の記事ドラフト作成フローが始まる。
ステップ6：必要に応じて分割
SKILL.mdが長くなった場合：
tech-blog-writer/
├── SKILL.md
└── references/
├── zenn-format.md # Zenn固有のフォーマット要件
└── qiita-format.md # Qiita固有のフォーマット要件
9. まとめ
SkillはAIに「習慣」を定着させる仕組みだ。しかし、原則を書いても動かない。「丁寧に」「適切に」は人間向けの指示だ。AIに渡すのは、機械的に実行可能な手順だ。
この記事の要点：
| 項目 | 内容 |
|---|---|
| Skillの正体 | ディレクトリに整理されたファイル群 |
| 必須ファイル |
SKILL.md（frontmatter + 実行手順） |
| トリガーの鍵 |
description（広すぎず・狭すぎず） |
| 手順の書き方 | 具体的・検証可能・禁止事項を含める |
| 初学者のお勧め | 一度手書きして構造を理解する |
一度書いたSkillは、次回から /skill-name だけで呼び出せる。AIに同じ説明を何度もしていると感じたら、Skillを書いてみよう。30分の投資が、今後の数時間を節約する。
Claude CodeでSkillを書いたことはありますか？どのようなタスクをSkill化しましたか？コメント欄で教えてください。