この記事は i-know.dev に掲載したものです。

Claude Skills完全ガイド②：自分だけのSkillsを作る編

この記事で分かること

前回の記事では、Claude Skillsの基本的な仕組みと、Claudeで用意されているSkillsを使い始める方法を紹介しました。

今回は一歩進んで、自分の業務手順や開発ルールに合わせた「カスタムSkill」を作る方法を解説します。

この記事では、次の内容を扱います。

• skill-creatorとは何か
• Claudeとの対話からSkillを作る流れ
• Skillを構成するフォルダとファイル
• SKILL.mdの基本的な書き方
• 作成したSkillをテスト・改善する方法
• Claude CodeやClaudeアプリで共有する際の考え方

毎回同じプロンプトやチェックリストを入力している場合、その手順はSkillとして再利用できる可能性があります。

skill-creatorとは

skill-creatorは、新しいSkillの作成や既存Skillの改善を支援するためのSkillです。

単にSKILL.mdの雛形を出力するだけでなく、現在のskill-creatorは次のような作業にも対応しています。

• 作成したいSkillの目的を整理する
• 業務手順や判断基準をヒアリングする
• SKILL.mdと関連ファイルを作成する
• テスト用のプロンプトを作る
• Skillを実際に動かして結果を評価する
• 評価結果をもとにSkillを改善する
• Skillが適切に呼び出されるようにdescriptionを調整する

つまり、skill-creatorは「Skillの自動生成ツール」というより、Skillの設計・作成・テスト・改善を支援する仕組みと考えると分かりやすいでしょう。

フォルダ構成や細かな仕様をすべて暗記していなくても、Claudeとの対話を通してSkillの下書きを作成できます。

ただし、生成された内容が必ずそのまま実務で使えるとは限りません。業務ルールの不足や曖昧な指示がないかを確認し、必要に応じて編集やテストを行うことが重要です。

カスタムSkillを作成する流れ

skill-creatorを使ったSkill作成は、主に次の流れで進みます。

1. 自動化したい作業をClaudeへ伝える

最初に、どのような作業をSkillにしたいのかを伝えます。

例えば、次のように依頼します。

毎週の売上CSVを集計し、社内フォーマットのExcelレポートを作るSkillを作成してください。

この時点では、細かな手順がすべて整理されていなくても構いません。

2. 作業手順やルールを整理する

Claudeは、Skillを作るために不足している情報を確認します。

例えば、次のような内容です。

• 入力ファイルの形式
• 必須となる列名
• 集計方法
• 出力するファイル形式
• 使用するテンプレート
• エラーがある場合の処理
• 完了条件や確認項目
• Skillを使用すべき依頼の例
• Skillを使用すべきではない依頼の例

普段は感覚的に行っている判断も、Skillへ組み込むには言語化する必要があります。

3. Skillのフォルダを生成する

必要な情報が整理できると、ClaudeがSkillのフォルダとSKILL.mdを作成します。

基本的な構成は次のとおりです。

weekly-sales-report/
├── SKILL.md
├── scripts/
│   └── aggregate_sales.py
├── references/
│   └── report-rules.md
└── assets/
    └── weekly-report-template.xlsx

必須なのはSKILL.mdです。

scripts、references、assetsなどのディレクトリは、Skillの内容に応じて追加します。すべてのSkillに必要なわけではありません。

4. テスト用プロンプトで動作を確認する

Skillを作成したら、実際の利用を想定したプロンプトで動作を確認します。

例えば、次のような観点でテストします。

• 必要な場面でSkillが呼び出されるか
• 関係のない依頼で誤って呼び出されないか
• 指定した手順どおりに処理されるか
• 入力データが不足している場合に確認できるか
• 出力形式が毎回安定しているか
• エラー時に危険な処理を行わないか

skill-creatorは、テストケースの作成や評価、改善の反復も支援します。

5. 結果を見ながらSkillを改善する

テスト結果に問題がある場合は、SKILL.mdや関連ファイルを修正します。

特に重要なのが、YAMLフロントマターのdescriptionです。

descriptionには、単にSkillの機能を書くのではなく、「何をするSkillなのか」と「どのような依頼で使うのか」を具体的に書きます。

Claudeはこの説明を参考に、Skillを読み込むべきか判断します。

SKILL.mdとは

SKILL.mdは、Skillの中心となるファイルです。

ファイルの先頭にはYAML形式のメタデータを記述し、その下へClaudeが従う手順やルールをMarkdownで記述します。

最小構成は次のようになります。

---
name: weekly-sales-report
description: 週次の売上CSVを集計し、前週比と前年比を含む社内フォーマットのExcelレポートを作成する。週次売上レポート、売上CSVの集計、定例報告資料の作成を依頼されたときに使用する。
---

# Weekly Sales Report

## 目的

週次の売上データを受け取り、社内フォーマットに沿った
Excelレポートを作成する。

## 入力

- CSV形式の売上データ
- 集計対象期間
- 比較対象となる前週または前年のデータ
- 出力用Excelテンプレート

## 手順

1. 入力ファイルがCSV形式であることを確認する
2. 必須列が存在することを確認する
3. 列名を社内標準へ変換する
4. 商品カテゴリ別・担当者別に売上を集計する
5. 前週比と前年比を計算する
6. 指定されたExcelテンプレートへ出力する
7. 合計値と元データの整合性を確認する

## 必須列

- sales_date
- product_name
- category
- amount
- salesperson

## エラー処理

- 必須列が不足している場合は処理を中断する
- 不足している列名をユーザーへ伝える
- 元データを推測して補完しない

## 完了条件

- 集計結果と元データの合計金額が一致している
- 前週比と前年比が計算されている
- 指定されたテンプレートへ出力されている

nameとdescriptionの書き方

基本的なSkillでは、YAMLフロントマターにnameとdescriptionを記述します。

name

nameはSkillを識別するための名前です。

英小文字とハイフンを使った名前にすると管理しやすくなります。

name: weekly-sales-report

日本語の表示名を付けたい場合でも、識別子となるnameは英小文字とハイフンで作るのが無難です。

description

descriptionには、次の2点を含めます。

1. Skillが何をするのか
2. どのような依頼で使用するのか

悪い例は次のような説明です。

description: 売上レポートを作る

これだけでは、月次レポートや簡単な売上質問でもSkillが呼ばれる可能性があります。

より具体的に書くと、次のようになります。

description: 週次の売上CSVを集計し、前週比と前年比を含む社内フォーマットのExcelレポートを作成する。週次売上レポート、売上CSVの集計、定例報告資料の作成を依頼されたときに使用する。

Skillが意図した場面で呼び出されない場合や、関係のない場面で頻繁に呼び出される場合は、まずdescriptionを見直します。

SKILL.mdには何を書くべきか

SKILL.mdには、単なる作業概要だけでなく、Claudeが迷わず処理できる具体的なルールを書きます。

特に次の項目が重要です。

入力条件

どのようなファイルや情報を受け取るのかを明示します。

作業手順

実行する順番を、再現できる粒度で記述します。

判断基準

状況によって処理が変わる場合は、分岐条件を記述します。

禁止事項

推測によるデータ補完、ファイルの上書き、外部送信など、実行してはいけない処理を明示します。

エラー処理

入力不足や形式不正があった場合に、どの時点で処理を止め、何をユーザーへ確認するかを書きます。

完了条件

何を確認できれば処理完了と判断するのかを記述します。

具体例

期待する入力と出力の例を入れると、処理のばらつきを抑えやすくなります。

関連ファイルを分割する

すべての情報をSKILL.mdへ詰め込む必要はありません。

長い仕様書やスクリプト、テンプレートは別ファイルとして配置できます。

my-skill/
├── SKILL.md
├── scripts/
├── references/
└── assets/

scripts

繰り返し実行する処理をスクリプトとして保存します。

例：

• CSVの整形
• データ検証
• ファイル名の変換
• テストの実行

references

必要なときに参照する仕様やルールを保存します。

例：

• 社内コーディング規約
• API仕様
• 用語集
• レポート作成ルール

assets

成果物の作成に使用するファイルを保存します。

例：

• Excelテンプレート
• PowerPointテンプレート
• ロゴ画像
• サンプルデータ

Skillは必要な情報を段階的に読み込むため、長い参考資料を別ファイルへ分けることで、SKILL.mdを簡潔に保ちやすくなります。

カスタムSkillsの3つの特徴

1. 複数のSkillsを組み合わせられる

Claudeは、複雑な作業で複数のSkillsを組み合わせて利用できます。

例えば、次のような構成です。

1. CSV検証Skillで入力データを確認する
2. 売上集計Skillでデータを集計する
3. Excel作成Skillでレポートを出力する
4. レビューSkillで成果物を確認する

一つのSkillへすべてを詰め込むより、役割ごとに分割した方が再利用しやすい場合があります。

2. ファイルとして管理・共有できる

Skillsはフォルダとファイルで構成されるため、Gitなどでバージョン管理できます。

Claude Codeでは、プロジェクト内の.claude/skills/へ配置して、リポジトリ単位で共有する方法があります。

また、Skillを含むClaude Codeプラグインを作成し、プラグインマーケットプレイス経由でチームへ配布することもできます。

ただし、Claudeアプリ、Claude Code、Claude APIでは、Skillの追加方法や一部の拡張機能が異なります。

Agent Skillsは共通のファイル形式を基盤としていますが、すべての環境で完全に同一の挙動になるとは限りません。利用する環境ごとにテストする必要があります。

3. 必要なときだけ詳しい内容を読み込める

Claudeは、最初からSkill内の全ファイルを読み込むのではなく、必要に応じて情報を段階的に読み込みます。

そのため、長い手順書や参考資料をSkillに含めても、使用しないタスクですべての内容がコンテキストを消費するわけではありません。

ただし、Skillsを増やせば無制限に管理できるという意味ではありません。

似たSkillを大量に登録すると、どのSkillを使うべきか判断しにくくなる可能性があります。役割の重複を避け、nameとdescriptionを明確にすることが重要です。

Skill作成時によくある失敗

descriptionが短すぎる

何をするかだけでなく、いつ使用するかまで記述します。

一つのSkillへ機能を詰め込みすぎる

責務が大きすぎる場合は、複数のSkillへ分割します。

普段の判断基準が書かれていない

「適切に処理する」「必要に応じて確認する」といった曖昧な表現を避け、具体的な条件を書きます。

正常系しかテストしていない

ファイル不足、列不足、形式不正、想定外の値などもテストします。

生成後に内容を確認していない

skill-creatorが作成したSkillも、実行内容や権限、スクリプトの安全性を人が確認する必要があります。

作成したSkillを共有する方法

作成したSkillは、利用環境に応じた方法で共有できます。

Claude Codeのプロジェクト内で共有する

プロジェクト固有のSkillは、リポジトリ内の次の場所へ配置できます。

.claude/
└── skills/
    └── weekly-sales-report/
        └── SKILL.md

このフォルダをGitで管理すれば、リポジトリを利用するメンバー間でSkillを共有できます。

プラグインとして配布する

複数のプロジェクトやチームへ配布する場合は、SkillをClaude Codeプラグインに含める方法があります。

さらに、プラグインマーケットプレイスを用意すると、次のような管理が可能になります。

• チーム内でのSkillの検索とインストール
• バージョン管理
• 更新の配布
• 利用可能なマーケットプレイスの制限
• 社内で承認されたプラグインの配布

Claudeアプリへ追加する

Claudeアプリでは、設定画面からカスタムSkillを追加できます。

組織で利用する場合は、プランや管理者設定によって共有方法や利用範囲が異なるため、現在の管理画面と公式ドキュメントを確認してください。

Claude APIへアップロードする

Claude APIでは、Skills APIを使用してカスタムSkillをアップロードし、アプリケーションから利用できます。

APIではSkillのバージョンや実行環境をアプリケーション側で管理する必要があるため、Claudeアプリでの利用よりも開発者向けの内容になります。

まとめ

skill-creatorを使うと、Claudeとの対話を通してカスタムSkillの設計、作成、テスト、改善を進められます。

Skillを作成するときの重要なポイントは次のとおりです。

• 自動化したい作業と利用場面を明確にする
• SKILL.mdに具体的な手順と判断基準を書く
• descriptionへ「何をするか」と「いつ使うか」を記述する
• 長い資料やスクリプトは別ファイルへ分割する
• 正常系だけでなくエラーケースもテストする
• 生成されたSkillの内容と安全性を人が確認する
• 利用環境ごとに動作を確認する

毎回貼り付けている長いプロンプト、チェックリスト、定型的な作業手順がある場合は、カスタムSkill化を検討する価値があります。

次回は、Claude CodeでSkillsを利用する方法について、.claude/skills/への配置、スラッシュコマンドからの実行、プラグインマーケットプレイスを使ったチーム共有まで具体的に解説します。

参考資料

• Anthropic「Extend Claude with skills」
• Anthropic「Agent Skills」
• Anthropic公式GitHub「anthropics/skills」
• Anthropic「Create and distribute a plugin marketplace」