【Claude Codeスキル実践編 #0】スキルの作り方——SKILL.mdの構造と育て方
この記事では以下がわかる。
.claude/skills/にファイルを置くだけで/コマンド名が使えるようになる仕組み- SKILL.mdのフロントマター・本文の書き方
- Claude Codeに指示してスキルを作り、使いながら育てていく実際の過程
スキルとは
Claude Code のスキル機能は、.claude/skills/<name>/SKILL.md にMarkdownファイルを置くだけで /name というスラッシュコマンドが使えるようになる仕組み。
/cfn-pipeline verification/test/ # ← これが使えるようになる
/blog-post 第3回 # ← 記事執筆スキルなど
コマンドを実行すると、SKILL.mdの本文がそのままシステムプロンプトとして渡される。つまりスキルとは「繰り返し使いたいプロンプトをコマンドとして登録する仕組み」だ。
commands/ との違い
.claude/commands/ も同じようにスラッシュコマンドを定義できるが、位置づけが異なる。
commands/ |
skills/ |
|
|---|---|---|
| ファイル形式 | <name>.md |
<name>/SKILL.md |
| 推奨状況 | レガシー（後方互換） | 現在の推奨 |
| サブファイル | 不可 | スキルディレクトリ内に置ける |
| frontmatter | 非対応 | 対応（name / description / argument-hint など） |
新しく作るなら skills/ を使う。
SKILL.mdの構造
ファイルの置き場所
重要: ファイル名は必ず SKILL.md でなければならない。cfn-pipeline.md や skill.md では認識されない。
.claude/
└── skills/
├── cfn-pipeline/
│ └── SKILL.md ← /cfn-pipeline になる
├── cfn-diagram/
│ └── SKILL.md ← /cfn-diagram になる
└── blog-post/
└── SKILL.md ← /blog-post になる
フロントマター
---
name: cfn-pipeline
description: CloudFormation パイプライン オーケストレーター
argument-hint: "<要件ファイルパス or ディレクトリパス...> [--error <エラー>]"
---
| フィールド | 必須 | 説明 |
|---|---|---|
name |
必須 | スラッシュコマンド名（/name で呼び出す） |
description |
推奨 | スキルの説明文（コマンド一覧に表示される） |
argument-hint |
任意 | 引数の使い方ヒント（補完時に表示） |
allowed-tools や context はSKILL.mdではサポートされていない。誤って書いてもエラーにはならず黙って無視されるため、不要なフィールドは書かないほうがいい。
本文
フロントマターより下の本文がそのままシステムプロンプトになる。書き方はMarkdownで、Claude Codeへの指示を自由に記述できる。
# CloudFormation パイプライン オーケストレーター
あなたはCloudFormationテンプレート生成パイプラインのオーケストレーターです。
以下のフローで処理を進めてください。
## Step 1: 設計エージェント
以下のプロンプトで Agent ツールを呼び出す。
\`\`\`
あなたはAWSアーキテクチャの設計専門エージェントです。
...
\`\`\`
サブエージェントを使いたい場合は「Agent ツールを呼び出す」と本文に書けばいい。引数に渡したいプロンプトもそのまま本文に書ける。
Claude Codeに作ってもらう
スキルの中身（プロンプト）を自分で最初から書く必要はない。Claude Codeに「こういうスキルを作って」と伝えれば、SKILL.mdを生成してくれる。
最初の指示の例
以下の仕様でClaude Codeスキルを作ってほしい。
- コマンド名: cfn-pipeline
- やること: CloudFormationテンプレートをMarkdown形式の要件ファイルから生成する
- フロー:
1. 設計エージェント（要件ヒアリング → アーキテクチャ設計）
2. 生成エージェント（CFnテンプレート生成 + cfn-lint + checkov）
3. レビューエージェント（要件・設計との照合 → approved/issue判定）
- 出力先: 入力ファイルの親ディレクトリ配下の cfn/ サブディレクトリ
- 複数ファイルのディレクトリ指定にも対応する
.claude/skills/cfn-pipeline/SKILL.md に保存して。
やってほしいことの「フロー」「入出力」「条件分岐」を具体的に書くほど、意図に近いSKILL.mdが生成される。
使いながら育てる
最初に生成したSKILL.mdが完璧なことはほとんどない。実際に使ってみると「あれが足りない」「こう動いてほしかった」という点が出てくる。それをそのままClaude Codeに伝えて修正していく。
cfn-pipelineスキルを育てた実際の過程
最初の失敗：ファイル名ルール
cfn-pipeline.md という名前で作ってもらったが、/cfn-pipeline を実行しても「Unknown skill」エラーになった。
Unknown skill: cfn-pipeline
調べると、スキルとして認識されるのは SKILL.md というファイル名のみ。ファイルをリネームして解決した。これは最初に必ずハマるポイントだ。
1回目の実行：出力先が想定と違った
リネーム後に5ファイルを処理させたところ、出力ファイルが cfn-01_VPC_Subnet.yaml（同一ディレクトリ）に生成された。欲しかったのは cfn/01_VPC_Subnet.yaml（cfnサブディレクトリ内）。
→ SKILL.mdに「入力ファイルの親ディレクトリ配下に cfn/ サブディレクトリを作成し、そこに出力する」と追記。
設計確認が入っていなかった
設計エージェントが終わると自動でテンプレート生成が始まってしまう。設計内容をユーザーが確認する前に次のステップが走るのは困る。
→ Step 1 完了後に設計内容を提示し「この設計で進めてよいですか？」と確認を求めるステップを追加。
フロントマターエラー
SKILL.mdのフロントマターに allowed-tools と context を書いていたが、どちらもSKILL.mdでは非サポートのフィールド。エラーが出たので削除した。
進捗が見えなかった
サブエージェントが裏で動いている間、ユーザー側からは何も見えない。3エージェントがそれぞれ数十秒〜数分動くので「まだ処理中なのか落ちたのか」判断できない。
→ 各ステップの前後に進捗表示を追加。
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[1/3] 設計エージェント 実行中...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✓ [1/3] 設計エージェント 完了
デプロイして初めてわかるルールの必要性
生成されたテンプレートを実際にAWSにデプロイすると6つのエラーが出た。生成エージェントへのプロンプトにルールを追記することで、次回から同じエラーが出なくなるよう修正した（詳細は次の記事）。
ルール追記のサイクル
使う
↓
問題に気づく
↓
SKILL.mdに指示・ルールを追記
↓
また使う
コードのリファクタリングと同じ感覚で、使うたびにSKILL.mdが育っていく。「エラーが出た → ルールを書く → 次から出なくなる」このサイクルが気持ちいい。
まとめ
スキルは「繰り返し使いたいプロンプトをコマンドとして登録する仕組み」で、チームのベストプラクティスをコードのように管理できる。
最初からすべてを設計する必要はない。Claude Codeに「こんなスキルを作って」と伝えて動くものを作り、使いながら育てていく——それが一番早い。