Claude Code シリーズ第3回。前回の学習編で押さえた Skills を、今回は実際に作って動かします。題材は「今日の最新AI・テックニュースを収集し、要点だけ日本語でまとめて表示する」スキル。

ただし今回は、うまくいった話だけでなく、最初に自動起動しなかった"つまずき"と、その直し方までそのまま載せます。学習編で「自動起動の精度は description で決まる」と書きましたが、これは実際に詰まってみて初めて腹落ちしました。

ひとことで言うと：.claude/skills/news-digest/SKILL.md を1枚作るだけ。ただし最初は自動起動せず、原因は「①追加したスキルが読み込まれていない」「②description が機能説明止まり」の2つ。description に"呼ばれたい言い回し"を足したら、話し言葉でも動いた。

このシリーズ（全10回・順次追加）

  1. 基礎 ― 全体像と拡張機能の地図
  2. Skills（学習編）― 繰り返す手順を覚えさせる
  3. Skills（実践編）― 作って、つまずいて、直す（この記事）
  4. Subagents（学習編）― 作業を別の文脈に切り出す
  5. Subagents（実践編）― 温泉宿を調べて比較する
  6. Hooks ― 特定のタイミングで自動実行する
  7. MCP（学習編）― 外部サービスへの接続口
  8. MCP（実践編）― Google ドライブ連携でつまずいた話
  9. Plugin ― 作った部品をひとつの箱にまとめる
  10. Marketplace ― 箱を並べて配る（完結編）

作りたいもの

ゴールはシンプルです。/news-digest と打つ、あるいは「今日のAIニュースをまとめて」と話しかけるだけで、Claude が最新のAI・テックニュースを集め、要点だけを日本語で並べてくれる。これを .md ファイル1枚で作ります。

手順1 ― 置き場所を作る（まずフォルダ）

スキルは「.claude/skills/<スキル名>/SKILL.md」という決まった場所に置きます。言葉で説明するより、作ってから構造を見たほうが早いので、まずフォルダを作ります。プロジェクトのルートで、ターミナルから次を実行します。

mkdir -p .claude/skills/news-digest

mkdir は「フォルダを作る」コマンド、-p は「途中のフォルダもまとめて作る」オプションです。これで .claude → skills → news-digest が一気にできます。

できた構造を tree で確認すると、こうなっています。

.claude └── skills └── news-digest └── SKILL.md ← これから作る

ポイントは、スキルは1つにつき1フォルダで、その中の SKILL.md が本体だということ。ファイル名は大文字の SKILL.md で固定です（skill.md や news.md では認識されません。最初に私が引っかかった点でもあります）。

手順2 ― SKILL.md を書く

.claude/skills/news-digest/SKILL.md を作り、次の内容を書きます。

--- name: news-digest description: 今日の最新テック/AIニュースを収集し、要点だけ日本語で簡潔にまとめる。 --- # ニュースダイジェスト手順 1. Webで「今日のAI・テックニュース」を検索し、信頼できる情報源を優先する。 2. 重要度の高い話題を5件まで選ぶ。 3. 各項目を「見出し（1行）＋要点（2〜3行）＋出典」で日本語にまとめる。 4. 推測は避け、確認できた事実だけを書く。 5. 最後に「今日のひとこと総括」を1〜2行で添える。

--- で囲んだ上半分が「フロントマター」（設定欄）、下が実際の手順です。この description が、あとで"つまずき"の原因になります。覚えておいてください。

手順3 ― 動かしてみる（そして、つまずく）

Claude Code を開き、自然な言葉で頼んでみます。

> 今日のAIニュースまとめて

ところが、返ってきたのはスキルを使った形跡のない、ふつうの返事でした。

最新のニュースをお調べするには、いくつか教えてください。 分野（AI全般／半導体／スタートアップ など）や、 件数のご希望はありますか?

SKILL.md に「5件・出典つき・推測しない」と書いたのに、その手順がまったく反映されていません。スキルが起動していないのです。

つまずきの原因 ― 2つあった

落ち着いて切り分けると、原因は2つ重なっていました。

原因1：追加したスキルが読み込まれていなかった

スキルのファイルは、セッションの途中で追加しても自動では拾われないことがあります。確認方法は簡単で、入力欄に /（スラッシュ）だけを打つこと。登録済みのスキルはスラッシュコマンドの候補に出ます。

> /

このとき候補に news-digest が出てこなければ、まだ認識されていません。Claude Code を一度開き直す（再起動する）と、.claude/skills/ が読み直されます。

原因2：description が「機能の説明」止まりだった

再起動して /news-digest と明示的に打てば動きました。ところが「今日のAIニュースまとめて」と話し言葉で頼むと、まだ起動しない。

これが学習編で書いた「自動起動は description 次第」の正体でした。最初の description は機能の説明（何をするか）しか書いておらず、こちらが実際に打つ言い回し（呼ばれたいトリガー語）が入っていなかったのです。

直す ― description にトリガー語を足す

description を、次のように書き換えました。

--- name: news-digest description: 今日の最新テック/AIニュースを収集し、要点だけ日本語で簡潔にまとめる。「今日のニュースをまとめて」「AIニュース教えて」「ニュースダイジェスト」と頼まれたら使う。 ---

変えたのは、ユーザーが実際に打ちそうな言葉（「今日のニュースをまとめて」「AIニュース教えて」「ニュースダイジェスト」）を description に並べたこと。これが自動起動の"呼び水"になります。

保存して開き直し、もう一度話し言葉で頼むと、今度は手順どおりに動きました。

> 今日のAIニュースまとめて

返ってきた実際の出力（一部）はこんな形です。

今日のAI・テックニュース ダイジェスト 1. 大手AIラボが新モデルを公開 - 推論性能と長文処理の改善が中心。価格は据え置きと案内。 - 出典: 各社公式ブログ 2. 国内大手が社内文書検索にAIを本格導入 - 数万件規模の社内文書を対象に検索・要約を提供との発表。 - 出典: プレスリリース （中略・全5件） 今日のひとこと総括: モデル性能の話題より、「社内データにどうつなぐか」の実装事例が増えてきた一日。

見出し＋要点＋出典という、手順に書いた体裁のまま返ってきています。「5件まで」「推測しない」「総括を添える」も効いていました。

補足：上の出力は実行例です。ニュースは日々変わるので、手元で一度動かし、実際に返ってきた結果に差し替えると、記事の説得力がさらに上がります。

動かして分かったこと

① 「動かない」は description を疑う前に、まず読み込みを疑う

スキルが効かないとき、いきなり中身を直したくなりますが、そもそも読み込まれているか（/ で候補に出るか、再起動したか）が先です。私はここで10分溶かしました。

② description は「説明」ではなく「呼ばれたい言葉」を書く

機能の説明だけでは話し言葉で起動しません。自分が打ちそうな言い回しをそのまま入れる。これが自動起動を安定させる最大のコツでした。

③ 出力の体裁と禁止事項は、本文の手順に明記した分だけ守られる

「見出し＋要点＋出典」「推測しない」を手順に書いておくと、毎回その形で返ります。逆に書かないとぶれます。スキルはガードレールを文章で書けるのが利点です。

まとめ ― Skills は「小さく作って、つまずいて、言葉で育てる」

  • スキルは .claude/skills/<名前>/SKILL.md を1枚置くだけ。ファイル名は大文字固定。
  • 追加直後は読み込まれないことがある。/ で候補確認 → 再起動が先。
  • 話し言葉で起動させたいなら、description に実際に打つ言い回しを入れる。
  • 出力の体裁・禁止事項は本文の手順に明記すると守られる。

つまずきは恥ずかしいものではなく、「どこを直せば動くか」を読者に手渡せる一番の教材です。次回からは Subagents に進みます。