Claude Codeのカスタムスキル自作|作り方と3つのコツ

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)
maah

この記事を書いた人

maah

非エンジニア。日々の業務にClaudeを取り入れた実体験を、初心者の目線で発信しています。