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化しましたか？コメント欄で教えてください。

AI Skill手書きガイド：Claude Codeで再利用可能な能力モジュール

추출된 키워드

원문