この記事は playpark Blog からの転載です。

この記事で分かること

「仕様書を読んでから書く」より「Claude に書かせてから調整する」が合理的な理由
description フィールドが起動精度を左右する仕組みと判断基準
スキルが思い通りに動かないとき、何を直すべきか

背景: こういう疑問があった

Claude Code の Skills を試そうとしたとき、多くの人が最初に直面するのは「SKILL.md ってどう書けばいいのか」という疑問だ。公式ドキュメントを読むと frontmatter のフィールド一覧が出てくるが、allowed-tools や model といった項目の使いどころは、実際に作ってみないとピンとこない。

「仕様を全部理解してから書こう」と思うと、そのまま手が止まる。

選択肢の検討

SKILL.md を書く方法として、実質的に 2 つのアプローチがある。

アプローチ	進め方	コスト
仕様書を先に読む	frontmatter の全フィールドを把握してから書く	学習コストが高い / 実際の動作と乖離しやすい
Claude に書かせる（採用）	作業を1回通してから「skill 化して」と頼む	学習コスト低 / 実際の動作ベースで生成される

仕様書を先に読むアプローチは一見正確に見えるが、「フィールドをどう組み合わせると期待通りに動くか」は実際に使ってみないと分からない部分が多い。Claude に書かせる場合、生成された SKILL.md は直近の会話の文脈を反映しているため、実際の動作に即した記述になりやすい。

なぜ「Claude に書かせる」を選んだか

実運用の判断として、2 つの理由が大きかった。

1. frontmatter の最小構成が name + description の 2 フィールドで十分

Claude が吐き出す SKILL.md は、だいたいこの形になる。

---
name: blog-fact-check
description: 'MDX 記事内の統計データ・バージョン情報・料金を抽出し、公式ソースと照合する。ユーザーが「ファクトチェック」「事実確認」「この数字合ってる？」と言ったときに使う。'
---

allowed-tools / model / when_to_use などのオプションフィールドは、「ここで副作用を抑えたい」「このモデルを指定したい」と感じた時点で1つずつ追加すれば間に合う。最初から全部盛りにする必要はなく、仕様書を暗記する意味がそもそも薄い。

2. 動いてから調整するほうが、修正対象が具体的になる

先に仕様を理解しようとしても、「この記述が起動精度にどう影響するか」は動かしてみないと分からない。作業を先に通して Claude に書かせると、最初のバージョンがすでに動いている状態になる。そこから「呼ばれない」「誤爆する」という具体的な問題に対して、description を調整するという流れになる。問題が具体的な分、何を直すべきかが明確になる。

スキル化のプロンプト例

今のやり取りで実施した「MDX 記事の統計値を抽出して公式ソースと照合する手順」を
Claude Code の Skill にしてほしい。

要件:
- スキル名は blog-fact-check
- 対象は content/blog/*.mdx
- 起動条件: ユーザーが「ファクトチェック」「事実確認」と言ったとき
- 副作用のあるコマンドは実行しない（読み取りのみ）

プロジェクト固有で使いたいので <project>/.claude/skills/ 配下に配置して。

要件を自然言語で渡すだけで、Claude が frontmatter 付きの SKILL.md を書いてくれる。

まとめ: どういう場面で使うべきか

「作業を何度かやった」「また同じことを頼んでいる」と気づいた時点が、スキル化のタイミングだ。完璧な SKILL.md を最初から書こうとしなくていい。

順序の整理：

やりたい作業を Claude Code と会話しながら1回通す
「今やった手順を〈name〉という skill 名で skill 化して」と頼む
生成された description だけ読み返し、起動ワードが自然文で書かれているか確認する
呼ばれなかったら description の起動ワードを足す、呼ばれすぎたら否定条件を足す

この流れで、frontmatter の全フィールドを事前に把握していなくても動くスキルが作れる。

さらに深掘りしたい方へ

この記事では SKILL.md を「仕様書から書く」のではなく「Claude に書かせてから調整する」を選ぶ判断背景を解説した。

skill.md とは？書き方の最短ルートと運用で気をつけること ではさらに：

10 個を超えたスキル同士の競合が起きる仕組みと、description の否定条件・オーケストレーター設計で解消する方法
300 行を超えた SKILL.md を references/ に分割してコンテキスト消費を抑えるアプローチ
プロジェクト固有値を skill-config.json に外出しするポータブル設計

を扱っている。

playpark について

playpark LLC - 業務自動化・AI活用・Web開発

お問い合わせ | ブログ