メインコンテンツへスキップ
見出し画像

Claude Codeのスキル(Skills)の作り方|SKILL.mdで毎回の頼み方を手順書にして、自動で呼ばれるようにする【実機で確認・2026年10月】

    「同じような頼み方を、毎回コピペしている」。「CLAUDE.md が長くなりすぎて、AI が全部は守ってくれない」。Claude Code を使い込むほど、こんな悩みが出てきます。

    その答えの1つが、スキル(Skills)です。この記事では、スキルとは何か、どこに何を書けばよいか、うまく呼ばれないときはどうするかを、実際に動かして確かめながら説明します。

    私は Claude Code と Codex を毎日使って、教材づくり、note・Gumroad への出品、画像づくりを自動化しています。私の作業場にも、7つのスキルが入っています(note の無料と有料の分け方の指針、画像の量産の手順、動画の仕上げの手順、新しいプロジェクトの作り方、など)。

    この記事のスキルは、読み物のために書いたものではなく、実際に動かして確かめたものです。Windows 11 の Claude Code で、試作したスキルを /スキル名 で呼び、さらに「スキル名を言わずに頼んでも、説明文を見て自動で呼ばれるか」まで試しました。全文無料です。

    この記事で分かること

    • スキルとは何か。CLAUDE.md・カスタムコマンドとの違い

    • 置き場所と、最小のスキルの作り方(動作を確かめた例つき)

    • frontmatter(先頭の設定)の主な項目

    • 呼び方の2つ(/スキル名 と、説明文による自動呼び出し)

    • 引数の渡し方

    • 補助ファイルの置き方と、長さの目安

    • うまく呼ばれないときの直し方

    先に結論

    • スキルは、手順書を1つのファイル(SKILL.md)にして、必要なときだけ読ませる仕組みです

    • 置き場所は .claude/skills/<スキル名>/SKILL.md(そのプロジェクトだけ)か、~/.claude/skills/<スキル名>/SKILL.md(自分の全プロジェクト)

    • いちばん大事なのは、先頭の description(説明文)です。Claude はこれを見て、「いま、このスキルを使うべきか」を判断します

    • 呼び方は2つ。/スキル名 と打つか、頼み方が説明文に合うと Claude が自分で呼びます

    • CLAUDE.md は「毎回読む短い決まりごと」、スキルは「必要なときだけ読む手順」。CLAUDE.md が手順だらけになってきたら、スキルに移すサインです

    • 向いているのは、繰り返し貼っている指示・チェックリスト・複数の手順がある定型作業です

    スキルとは

    スキルは、Claude Code に覚えさせたい手順を、1つのフォルダにまとめたものです。中心は SKILL.md というファイル1枚で、先頭に名前と説明を、その下に手順を書きます。

    公式のドキュメントには、こう書かれています。

    Claude uses skills when relevant, or you can invoke one directly with /skill-name.

    つまり、「関係がありそうなときは Claude が使い、自分で呼びたいときは /スキル名 と打つ」ものです。

    CLAUDE.md との違い

    CLAUDE.md は、Claude Code が毎回、最初に読むファイルです。だから、短く保つ必要があります。長くなるほど、読まれても守られにくくなります。

    スキルは、必要になったときだけ読み込まれます。普段は、名前と説明文だけが見えていて、本文は呼ばれるまで読みません。そのため、手順が長くても、会話の記憶(コンテキスト)を圧迫しません。

    公式のドキュメントでも、CLAUDE.md の内容が手順のようになってきたら、スキルへの移行が勧められています。

    使い分けの目安は、こうです。

    • CLAUDE.md:このフォルダの目的、守ってほしい決まりごと、よく使うコマンド(短く)

    • スキル:「〇〇を頼まれたら、この順で進める」という手順(長くてもよい)

    CLAUDE.md の書き方は、CLAUDE.mdの書き方(無料)にまとめています。

    カスタムコマンドとの関係

    以前は、.claude/commands/ に Markdown を置くと、/コマンド名 で呼べました。いまは、これがスキルに統合されています。公式のドキュメントによると、.claude/commands/deploy.md と .claude/skills/deploy/SKILL.md は、どちらも /deploy を作り、同じように動きます。同じ名前なら、スキルが優先されます。

    すでに commands/ に置いたものは、そのまま動きます。新しく作るなら、スキルが勧められています(補助ファイルを置ける、呼び出しを制御できる、Claude が自動で読み込める、という追加機能があるため)。

    置き場所

    公式のドキュメントによると、主な置き場所は2つです。

    • 自分用(personal):~/.claude/skills/<スキル名>/SKILL.md。このパソコンの、すべてのプロジェクトで使える

    • プロジェクト用:.claude/skills/<スキル名>/SKILL.md。そのリポジトリの中だけ。Git に入れれば、チームで共有できる

    どちらにも同じ名前があるときは、自分用が優先です(組織の管理設定がある場合は、それがいちばん上になります)。

    迷ったら、プロジェクト用から始めてください。そのフォルダの作業にだけ関係する手順なら、そこに置くのが自然です。

    画像

    最小のスキルを作る

    作るのは、記事の下書きを公開前に点検する「article-check」です。.claude/skills/article-check/SKILL.md を、次の内容で作ります。

    ---
    name: article-check
    description: 記事・文章の下書きを公開前に点検する。「記事をチェックして」「公開前の確認」と頼まれたときに使う
    argument-hint: [下書きのファイル]
    ---
    
    $ARGUMENTS を読み、次の4点を点検して、直す箇所を箇条書きで返してください。ファイルは書き換えないでください。
    
    1. 題名: 検索されそうな言葉が先頭にあるか
    2. 誇大な表現: 「誰でも月○万円」「必ず」「絶対」などの言い切りがないか
    3. 数字・固有名詞: 根拠の書かれていない数字がないか
    4. 最後: 次に読むもの・読者にしてほしいことが1つ書かれているか
    
    出力は「点検項目:OK か 要修正」を1行ずつ、要修正のものは直し方を1文で添える。

    構造は単純です。--- で囲んだ先頭部分(frontmatter)に設定を、その下に、Claude に読ませたい手順を書きます。

    呼んでみる(/スキル名)

    動作を確かめるために、わざと問題のある下書き(draft.md)を作りました。

    # 副業で月100万円!誰でも必ず稼げる
    
    この方法なら絶対に成功します。1週間で売上が3倍になりました。

    そして、次のように呼びました。

    /article-check draft.md

    draft.md の部分が、本文の $ARGUMENTS に入ります。返ってきた結果は、4つの項目すべてが「要修正」でした。「誰でも必ず稼げる」「絶対に成功します」を削る提案、根拠のない「3倍」の数字を示すか削る提案、末尾に次の行動を足す提案が、項目ごとに出ました。点検の観点が、手順どおりに使われたことが分かります。

    スキル名を言わずに頼んでみる(自動呼び出し)

    次に、スキルの名前を出さずに、こう頼みました。

    draft.md を、公開前の確認として見てください。

    Claude Code の動きを記録して見ると、article-check のスキルが呼び出されていました(ファイルを読んだあと、Skill というツールで article-check を指定していました)。頼み方の中の「公開前の確認」が、説明文の「公開前の確認」と合ったからです。

    これが、スキルの強みです。自分が覚えておく必要はなく、頼み方が合えば、Claude が手順書を見つけて使います。

    ただし、毎回必ず呼ばれる保証はありません。呼ばれないときの直し方は、あとの章に書きます。

    frontmatterの主な項目

    先頭の設定には、次のような項目があります(公式のドキュメントで確かめたものです)。すべて任意ですが、description は付けることが勧められています。

    • name:コマンド名。省略するとフォルダ名になる

    • description:何をするスキルか、いつ使うか。Claude が自動で呼ぶかどうかを決める材料

    • when_to_use:呼び出す場面の補足。description に足されて、合計 1,536 文字で切り詰められる

    • argument-hint:入力のときに出る、引数のヒント(例:[ファイルのパス])

    • arguments:名前つきの引数($名前 で使う)

    • disable-model-invocation:true にすると、Claude は自動で呼ばない。自分が / で打ったときだけ動く

    • user-invocable:false にすると、/ のメニューから隠れて、Claude だけが呼べる

    • allowed-tools:このスキルの実行中に、確認なしで使えるツール

    • model:このスキルの実行に使うモデル

    • effort:作業の力の入れ具合(low から max)

    • context:fork にすると、別の作業者(サブエージェント)の中で実行する

    重要な注意があります。公式のドキュメントには、「認識されないフィールドは、エラーなしで無視される」と書かれています。項目名を間違えても、何も警告されません。「設定したのに効かない」ときは、綴りを疑ってください。

    自動で呼ばれたくないスキルは、止める

    「デプロイ」や「公開」のような、勝手に動かれると困るスキルは、disable-model-invocation: true を付けて、/スキル名 で自分が打ったときだけ動くようにします。逆に、日常の点検のようなスキルは、自動で呼ばれるほうが便利です。

    引数の渡し方

    スキルの名前の後ろに書いた言葉は、本文の中の $ARGUMENTS に入ります。

    ---
    name: fix-issue
    description: Fix a GitHub issue
    disable-model-invocation: true
    ---
    
    Fix GitHub issue $ARGUMENTS following our coding standards.

    これは公式のドキュメントの例です。/fix-issue 123 と打つと、$ARGUMENTS が 123 に置き換わります。

    位置で分けて使うこともできます。$0 が最初の引数、$1 が2番目です。引数に空白を含めたいときは、引用符で囲みます。本文に $ARGUMENTS が1つもないのに引数を渡したときは、末尾に ARGUMENTS: 入力した値 が足されます。

    補助ファイルと、長さの目安

    スキルは、SKILL.md 1枚だけでなくても作れます。公式のドキュメントでは、こう整理されています。

    my-skill/
    ├── SKILL.md      (必須。概要と案内)
    ├── reference.md  (細かい資料。必要なときだけ読む)
    ├── examples.md   (使用例。必要なときだけ読む)
    └── scripts/
        └── helper.py (実行するだけで、読み込まない道具)

    SKILL.md から、reference.md などへリンクしておくと、必要なときだけ読み込まれます。道具のスクリプトは、Claude が中身を読まずに実行できます。

    長さについては、公式のドキュメントに、SKILL.md は500行未満にすると書かれています。詳しい資料は、別のファイルに分けます。

    もう1つ大事な点があります。読み込まれたスキルの内容は、その後のやりとりでも、会話の記憶に残り続けます。だから、本文は簡潔に、「何をするか」を書き、長い経緯や理屈は書かないほうがよい、と説明されています。

    いい説明文(description)の書き方

    スキルが呼ばれるかどうかは、説明文でほぼ決まります。私が心がけていることを書きます。

    • 主な用途を、先頭に書く:説明文は長いと切り詰められます(description と when_to_use の合計で 1,536 文字)。大事な言葉を、前に置きます

    • 頼まれ方の言葉を入れる:自分が実際に打つ言葉(「記事をチェックして」「公開前の確認」)を入れておくと、呼ばれやすくなります。上の試作でも、そうしました

    • 「何をするか」と「いつ使うか」を、両方書く:「点検する」だけでなく、「〜と頼まれたときに使う」まで書きます

    私の作業場の「hq-intake」というスキルの説明文は、こうです。

    description: 既存フォルダを HQ に取り込んだ・整理したい・重複を確認したい・全体の状況を知りたいときに使う。hq scan で台帳とダッシュボードを更新し、重複と未収容を報告する。

    「いつ使うか」を先に、「何をするか」を後に書いています。

    うまく呼ばれないとき

    1. 説明文を見直す

    頼み方と、説明文の言葉が合っていないことが、いちばん多い原因です。実際に打った言葉を、説明文に足してください。

    2. 項目名の綴りを見直す

    前にも書いたとおり、間違った項目名は無視されます。description が discription になっているだけでも、効きません。

    3. 置き場所を見直す

    .claude/skills/<スキル名>/SKILL.md の形になっているか。フォルダ名と SKILL.md の大文字・小文字も、確かめてください。

    4. 手動で呼べるか確かめる

    まず /スキル名 で呼んでみて、動くなら、手順の中身は問題ありません。自動で呼ばれないだけなら、説明文の問題です。

    5. 長すぎないか見直す

    本文が長すぎると、読み込まれたあと、記憶を圧迫します。500行を超えるなら、補助ファイルに分けます。

    どんなスキルを作るか

    最初の1つは、自分がいま、毎回コピペしている指示を選ぶのが、いちばん続きます。

    • 公開前のチェックリスト(上の例)

    • 記事の書き方の型(題名・見出し・最後の導線)

    • 画像を量産するときの手順

    • 新しいプロジェクトを作るときの、決まった初期設定

    • 報告書やメールの、決まった形式

    逆に、向いていないものもあります。「1回きりの作業」や、「毎回、中身がまったく違う作業」は、スキルにしても使い回せません。

    私の作業場にある7つのスキルは、どれも「繰り返す定型作業」です。たとえば note の記事を書くときの「無料と有料の分け方」の指針は、スキルにしてあるので、頼むたびに説明しなくても、同じ基準で動いてくれます。

    注意点

    • 秘密を書かない:スキルは、チームで共有したり、Git に入れたりします。APIキーやパスワードは、書かないでください

    • 古くなった手順は直す:スキルの手順が現実とずれると、AI は古い手順で動きます。作業のやり方を変えたら、スキルも更新します

    • 自動で呼ばれる範囲に注意:公開や削除のような、取り返しのつかない作業を含むスキルは、disable-model-invocation: true で、自分が打ったときだけ動くようにします

    • この記事の内容は、2026年10月15日の公式ドキュメントと、私の環境で確かめたものです。項目名や挙動は、版が上がると変わることがあります

    まとめ

    • スキルは、手順書を SKILL.md にまとめ、必要なときだけ読ませる仕組み。置き場所は .claude/skills/<名前>/SKILL.md(プロジェクト用)か ~/.claude/skills/<名前>/SKILL.md(自分用)

    • 呼び方は2つ。/スキル名(引数は $ARGUMENTS)と、説明文に合う頼み方での自動呼び出し。どちらも実機で確かめた

    • いちばん大事なのは description。主な用途を先頭に、頼まれ方の言葉を入れる

    • 認識されない項目名は、エラーなしで無視される。効かないときは綴りを疑う

    • SKILL.md は500行未満。細かい資料は別ファイルへ。読み込んだ内容は会話に残り続けるので、簡潔に

    • CLAUDE.md は短い決まりごと、スキルは必要なときの手順。CLAUDE.md が手順だらけになったら、スキルに移す

    • 勝手に動かれると困るスキルは、disable-model-invocation: true

    次の一歩は、自分がいま毎回コピペしている指示を1つ選んで、SKILL.md にすることです。10行で、十分です。


    次に読む

    このアカウントをフォローすると、Claude Code や Codex の新しい手順の記事が届きます。ぜひフォローしてください。

    この先で分かること(今後の有料記事)

    • そのままコピーして使えるスキルの実物(記事・画像・調査・公開前の点検など)

    • 自動で呼ばれるスキルと、手動だけのスキルの分け方の実例

    • 作業場の手順を、スキルに少しずつ移していく進め方

    まさのAI実務ラボ|Codex・Claude Code では、有料記事が読み放題になります。テンプレートや指示文をまとめて使いたい方はご覧ください。

    あなたへのおすすめ