なぜ SKILL.md を「仕様書から書く」より「Claude に書かせる」ほうが正しいのか

Last updated at 2026-06-09Posted at 2026-06-09

この記事は 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 を書いてくれる。