Claude Codeのカスタムスキル自作|作り方と3つのコツ
Claude Codeのスキルを自作してみたいけれど、カスタムスキルは難しそう。そう感じて、用意されたコマンドだけを使っていませんか。
私も最初はそうでした。いまは自作のスキルが17個あります。この記事では、その17個を数え直してわかったことと、新しく1つ作る手順をまとめます。
なお、スキルの概要は以前の記事(スキル機能で繰り返し作業を短くした話)で紹介しました。今回は「自分で作る」部分にしぼります。仕様は2026年11月16日時点の公式ドキュメントで確認した内容です。
Claude Codeのスキル自作は「フォルダ1つとSKILL.md 1枚」でできる
結論から言うと、カスタムスキルはフォルダを1つ作り、その中に `SKILL.md` というテキストファイルを1枚置けば作れます。プログラムを書く必要はありません。
置き場所は2種類あります。
| 種類 | 場所 | 使える範囲 |
|---|---|---|
| 個人用 | `~/.claude/skills/スキル名/SKILL.md` | 自分のどのプロジェクトでも |
| プロジェクト用 | `.claude/skills/スキル名/SKILL.md` | そのプロジェクトの中だけ |
`~` はホームフォルダのことです。Windowsではパスの書き方が変わるので、公式ドキュメントで確認してください。
公式ドキュメントによると、フォルダ名(または `name` に書いた名前)が、そのまま `/スキル名` というコマンドになります。名前は半角の英小文字・数字・ハイフンにしておくと無難です(Agent Skillsの仕様では64文字以内で、フォルダ名と一致させる決まりです)。
手元の17個を数え直してわかったこと
記事を書く前に、自分の `~/.claude/skills/` を集計しました。使っているClaude Codeは 2.1.268 です。
- スキルは17個。**17個すべてが `SKILL.md` 1枚だけ**で、付属ファイルはなし
- 行数は57行〜344行。いちばん長いのはブログ用の344行
- 17個中16個に `argument-hint`(引数のヒント)を書いていた
- 使っていた設定項目は `name`・`description`・`argument-hint` の3つだけ
もっと複雑なものを作ってきたつもりでしたが、実際は「3項目+手順の文章」だけで、毎日の作業が回っています。
公式ドキュメントでは、`SKILL.md` は500行未満を目安にし、細かい資料は別ファイルに分けることが勧められています。344行のブログ用スキルは目安の範囲内ですが、参照資料が増えて直しづらくなったら分割を考えるつもりです。分割はまだ試せていません。
作り方の手順(練習用フォルダで試す)
今回は「打ち合わせメモを整理するスキル」を、練習用フォルダにプロジェクト用として作りました。いきなり個人用に置かず、練習用で試すのがおすすめです。個人用に同じ名前のスキルがある場合はそちらが優先されるので、別の名前にして、フォルダ名・`name`・呼び出す名前をそろえてください。
ターミナルで、練習用フォルダを置きたい場所に `cd` で移動してから、次のように進めます。
pwd
mkdir skill-practice
cd skill-practice
mkdir -p .claude/skills/memo-tidy
`pwd` はいまいる場所の確認です。これはmacOS・Linux・WSLのターミナル(Bash/Zsh)向けの例で、WindowsのPowerShellなどでは書き方が変わります。`skill-practice` という名前のフォルダがすでにある場合は、別の名前にしてください。コマンドが不安な場合は、後半のプロンプトでClaude Codeにフォルダごと作ってもらう方法もあります。
次に、`.claude/skills/memo-tidy/SKILL.md` を作ります。最初に書いたのはこれでした。
---
name: memo-tidy
description: メモを整理する
---
渡されたメモを整理してください。
これでも形にはなります。ただ、読み返すと「いつ使うのか」「どう整理するのか」「元のファイルを書き換えるのか」が何も決まっていません。そこで次のように直しました。
---
name: memo-tidy
description: 打ち合わせメモのテキストファイルを「決定事項・TODO・要確認」に分類して整理する。メモの整理や議事録の下書きを頼まれたときに使う。
argument-hint: "[メモのファイル名]"
---
# メモ整理スキル
対象ファイル: $ARGUMENTS
1. 対象ファイルを読む。パスは現在の作業フォルダを基準にする。指定がない、または見つからない場合は処理を止めてファイル名を質問する
2. 各行を「決定事項」「TODO」「要確認」「その他」に分類する
3. 分類に迷う行は推測で振り分けず「要確認」に入れる
4. 結果はチャットに表示する。元のファイルは変更しない
5. 別ファイルへの保存を頼まれた場合は、保存先と内容を示し、確認を得てから保存する
ファイルは、テキストエディタで上の内容を貼り付け、文字コードUTF-8、ファイル名 `SKILL.md` で保存します。
試すときの流れは次のとおりです。
1. `skill-practice` フォルダに、数行のサンプルメモを `notes.txt` として置く
2. 同じフォルダで `claude` を起動する
3. チャット欄に `/memo-tidy notes.txt` と入力する
4. 分類結果がチャットに表示され、`notes.txt` が変更されていなければ成功
フォルダ作成、2つの版の `SKILL.md` 作成、サンプルメモの用意までは実際に行いました。ただし今回は、手順2〜4の呼び出し確認までは終えられていません。確認に使う予定だった環境で認証が切れていたためです。上の流れは公式ドキュメントに沿った「こう試す予定」の手順で、結果は確認でき次第追記します。
公式ドキュメントによると、スキルの編集は再起動なしで反映されます。ただし、Claude Codeの起動時に存在しなかったスキル用フォルダ(`.claude/skills`)を後から作った場合は監視の対象外で、`/reload-skills` が必要とされています。この場合、起動し直すまでは編集のたびに `/reload-skills` が必要です。作ったのに候補に出ないときは、`/reload-skills` を試すか、練習用フォルダでClaude Codeを起動し直すのが早そうです。
自作してわかった3つのコツ
1. descriptionは「いつ使うか」まで書く
`description` は説明文であると同時に、Claudeが「いまこのスキルを使うべきか」を判断する材料です。「メモを整理する」だけでは、どんな依頼のときに使うのかが伝わりません。「何をするか」と「どんなときに使うか」を1〜2文で書きます。
自動で呼ばれる精度がどこまで上がるかは、まだ比べられていません。調査ベースの話として受け取ってください。
2. 引数は `$ARGUMENTS` で受け取る
`/memo-tidy notes.txt` のように、コマンドの後ろに書いた文字は `$ARGUMENTS` の位置に入ります。`argument-hint` を書いておくと、入力時に「何を渡せばよいか」のヒントになります。
「引数がなければ質問する」と1行足しておくと、渡し忘れても止まりにくくなります。
3. 変更をともなう手順には「確認してから」を書く
スキルは一度作ると何度も実行されます。保存・上書き・削除・投稿などを含む手順には、「対象と内容を示し、確認を得てから実行する」と書いておくと安心です。
公式ドキュメントには、Claudeによる自動呼び出しを止めて自分で呼んだときだけ動かす `disable-model-invocation: true` という設定も載っています。投稿や送信をするスキルに向いていそうですが、私はまだ使っていません。
そのまま貼れるプロンプト
自分で書くのが不安な方は、Claude Codeに下書きを作ってもらう方法があります。チャット欄に貼って、【 】の中を書き換えてください。
よく行う作業を、Claude Codeのカスタムスキルにしたいです。
目的: 【例: 打ち合わせメモを決定事項・TODO・要確認に整理する】
入力: 【例: テキストファイル1つ。ファイル名は引数で渡す】
出力: 【例: チャットに表示。元のファイルは変更しない】
対象: このプロジェクトの .claude/skills/【スキル名(半角英小文字とハイフン)】/SKILL.md を新規作成。それ以外のファイルは変更しない
進め方:
1. まず、同じ名前のスキルがプロジェクト用(.claude/skills/)と個人用(~/.claude/skills/)にすでにないか確認し、結果を教えてください。同じ名前があれば作業を止め、別の名前を提案してください
2. SKILL.md の案(name、description、argument-hint、手順)をチャットに表示してください。この時点ではファイルを作らないでください
3. description には「何をするか」と「どんなときに使うか」を書いてください。ファイル指定を受ける場合は $ARGUMENTS を使い、未指定・見つからないときに確認する手順も入れてください
4. 作るスキルの手順にも、保存・上書き・削除・投稿・送信の直前に対象・内容・影響範囲を示し、私の承認を待つ手順を入れてください。投稿や送信を含む場合は disable-model-invocation: true の設定も提案してください
5. 私が確認してから、ファイルを作成してください
既存のファイルやスキルの上書き・削除はしないでください。どうしても必要な場合は、実行前に対象ファイル一覧、差分、影響範囲を表示し、私が確認してから実行してください。
不明点は推測せず、確認事項として列挙してください。
できあがったら、まず練習用のファイルで1回試し、気になった点を伝えて直してもらいます。スキルは使いながら育てるもの、という感覚は17個作ったいまも変わりません。
まだわかっていないこと
- `description` の書き方で、自動呼び出しの精度がどのくらい変わるのか
- 長いスキルを複数ファイルに分けたとき、使い勝手がどう変わるのか
- 以前からある `.claude/commands/` との使い分け。公式ドキュメントでは、こちらも引き続き動くものの、新しく作るならスキルが勧められています
まとめ
- Claude Codeのスキル自作は、フォルダ1つと `SKILL.md` 1枚から始められる
- 手元の17個は、3つの設定項目と手順の文章だけでできていた
- `description` には「何をするか」と「いつ使うか」を書く
- 引数は `$ARGUMENTS` で受け取り、`argument-hint` でヒントを出す
- 変更をともなう手順には「確認してから実行」を入れておく
「この説明、前にも打ったな」と思ったら、スキルにするタイミングです。まずは練習用フォルダで、小さな1つから試してみてください。
あわせて読みたい
- [Claude Codeのスキル機能で繰り返し作業を1秒で終わらせた話](https://maahsachi.com/?p=355)
- [/help以外に使えるスラッシュコマンド全部試した](https://maahsachi.com/2026/04/26/claude-code-slash-commands/)
- [Claude Code permissions設定の見直し手順](https://maahsachi.com/2026/11/02/claude-code-permissions-setup/)
学習アプリについて
「作って、試して、直す」流れを手を動かして学べる学習アプリ(app.maahsachi.com)を公開準備中です。公開したらこのブログでお知らせします。
参考
- [Extend Claude with skills(Claude Code 公式ドキュメント)](https://code.claude.com/docs/en/skills)
- [Agent Skills Specification(agentskills.io)](https://agentskills.io/specification)