「Agentを作るな、Skillを作れ」が刺さる理由

IQ300の数学者に確定申告を頼まない

先日、自社アカウントでこんな投稿をしました。

Anthropicのエンジニアが「Agentを作るな、Skillを作れ」と言い切った話、すごく刺さりました。
Claude Codeって賢いんですが、あなたの業務のことは何も知らないんですよね。
Barry Zhang氏がこんなたとえを使っていて「IQ300の天才数学者と、20年キャリアのベテラン税理士、確定申告を頼むならどっち？」という話なんですが、答えは明らかに税理士ですよね。

このたとえが刺さるのは、数学者に能力が足りないからではありません。
確定申告に必要なのは、控除の要件や提出期限、その事業所特有の仕訳のクセといった前提知識のほうだからです。

Claude Codeが知らないのは能力ではなく前提

Claude Codeは、コードを読んで直す力も、文章を組み立てる力も持っています。
持っていないのは、あなたの会社の見積フォーマットや請求の締め日、社内でだけ通じる言い回しのほうです。

「出力がブレる」「同じ修正を何度も頼んでいる」という症状の原因は、たいていここにあります。
モデルを上位のものに替えても直りません。
前提を渡していないという一点が原因なので、渡す仕組みを作るしかないからです。

Anthropicの公式エンジニアリングブログは、Skillを作る作業を「新しく入った人向けのオンボーディング資料を作ること」に喩えています（出典: anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills）。
新人に「察してくれ」とは言いません。
手順書を渡します。

「Agentを作るな」は排他の主張ではない

なお、「Agentを作るな」は排他の主張ではありません。
公式はMCP（外部サービスへの接続の仕組み）を接続性、Skillsを手順知識と役割分担させ、併用するものとして整理しています（出典: claude.com/blog/skills-explained）。

Skillの中身と、数を増やしても軽い理由

実体はフォルダ1つで足りる

Skillの実体はフォルダ1つで、中身は3点セットです。
いつ使うかと手順の概要を書いたSKILL.md、詳細手順やテンプレートを置く参照ファイル群、繰り返し実行するスクリプト。
3つ全部が必要なわけではなく、SKILL.md 1枚だけでも成立します。

必須項目はnameとdescriptionだけ

SKILL.mdは、YAMLフロントマター（ファイル冒頭を --- で囲んだ設定欄）とマークダウン本文の2部構成です。
公式ドキュメントによると、必須項目はnameとdescriptionの2つだけとされています（出典: platform.claude.com/docs/en/agents-and-tools/agent-skills/overview）。

descriptionの1024文字は、日本語も1文字と数えます。
思ったより早く上限に近づくので、説明を詰め込みすぎないほうがいいでしょう。

置き場所は自分専用と共有の2つ

格納先は2つです。
自分専用にしたいものは ~/.claude/skills/ に、案件やリポジトリで共有したいものは .claude/skills/ に置きます（出典: code.claude.com/docs/en/skills）。

起動時に読むのは名前と概要だけ

AIが一度に覚えていられる作業メモの容量を、コンテキストと呼びます。
Skillをいくつも作ると、そのぶんコンテキストを食い潰すのではないか。
私も最初はそう思っていましたが、実際の動き方は逆でした。

Claude Codeは起動時に、全Skillのnameとdescriptionだけをシステムプロンプトに読み込みます。
SKILL.mdの本体は、Claudeが「このタスクにはこのSkillが要る」と判断したときに、はじめて開かれます。

常時載っているのは索引だけ、ということです。
これが、数百個のSkillを持たせても動く理由でした。
スクリプトはさらに軽く、bashで実行され、出力された結果の分だけがコンテキストを消費します。

500行を超えたら分割を疑う

公式のベストプラクティスは、SKILL.md本文を500行以内に収めることを推奨しています。
超える場合は、必要になったときだけ別ファイルを開かせる書き方（progressive disclosure）で分割せよ、というのが公式の指示です（出典: platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices）。
500行は推奨であって強制ではありません。
ただ、越えはじめたら分割単位を見直すサインとして扱うのが実務的だと思います。

SkillとSubagent、どちらを先に作るか

公式の線引きは「訓練資料」と「専門社員」

Anthropic公式は、Skillを「どのClaudeインスタンスでも読み込んで使える能力」、Subagentを「独自のコンテキストとツール権限を持つ自己完結型エージェント」と整理しています。
前者は全会話にまたがる訓練資料、後者は専門社員のようなものです。

併用が前提の設計になっている

公式ブログには、code-reviewサブエージェントが言語別ベストプラクティスのSkillを使う、という併用例が挙げられています。
専門社員に訓練資料を渡す構図です。

Claude Codeでは、フロントマターに context: fork を付けるとSkillを隔離実行できます。
このときSkillの内容がそのサブエージェントを動かすプロンプトになり、会話履歴にはアクセスしません。

増築で済むほうを先に作る

手順知識をSkillに書いておけば、後からSubagent化するときにそれがそのまま材料になります。
逆順でSubagentから作ると、同じ知識を二度書くことになります。
増築で済むほうを先に作る。
それだけの理由で、Skillが先です。

業務知識をSkillに落とす5ステップ

起点は同じ指示を繰り返していると気づいた瞬間

起点は、同じプロンプトを複数の会話で繰り返し打っていると気づいた瞬間です。

ここから先、Claudeがそのスキルを選んで読み込むことを「発火」と呼びます。
書いたのにClaudeが使ってくれない状態は、この発火が起きていない状態です。

必要な文脈は書きながら見つける

公式が推奨するプロセスは、事前に必要な文脈を全部想定しないというものです。
タスクをClaudeと一緒に進めながら、うまくいったやり方とよくある失敗をSkillに書き取らせる。
これを繰り返して「実際に必要だった文脈」を発見していきます。

作り方そのものに詰まったら、公式のskill-creatorスキル（github.com/anthropics/skills）を使う手もあります。

3つのケースでテストする

テストは、想定どおりのケース、対象外のケース、境界のケースの3つで回します。
対象外のケースで勝手に発火するならdescriptionが広すぎ、想定どおりで発火しないなら狭すぎます。

自社業務をSkill化して分かった、分割単位とつまずき

1業務1Skillにすると太る

私がいま運用しているSkillのひとつが、この記事を書くのに使っている文章の規範です。
最初に想定していたのは「記事執筆」という業務単位で1本にまとめる形でした。

結果として、いまは2本に分かれています。
一方は一文一行や脚注の使い方といった整形と論証のルール、もう一方は文章の緩急と読ませ方の設計です。

分けた理由は、呼び出す場面が違ったからです。
整形と論証のルールは提案書でもレポートでも要りますが、緩急の設計は記事のような読み物にしか要りません。
実際、後者には「戦略・提案書・レポート・経理・議事録などの実務文書には適用しない」という但し書きを後から足しています。

業務名で割ると、この線は引けません。
どちらも「記事執筆」だからです。

本文が伸びる原因はテンプレートと文例

本文が伸びる原因は、たいていテンプレートと文例でした。
長くて変化の少ない情報は参照ファイルへ逃がし、本文には道案内だけ残します。

使ってくれないときはほぼdescriptionが原因

書いたのに使ってくれない、という状態には何度か遭遇しました。
本文の書き方を疑って直しても変わりません。
当たり前で、Claudeは本文をまだ読んでいないからです。

公式ベストプラクティスも「Skillのnameとdescriptionに特に注意すること」と明記しています。
理由は「Claudeはこれを見て、そのタスクでSkillを起動するか判断します」という一点です。

私のSkillのdescriptionは、前半で規範の中身を列挙し、後半を「日本語で技術書の章、草稿、記事、解説文を書くとき、または推敲・リライトするときに使用する」で締めています。
後半の「いつ使うか」を書き足したことが、発火の安定に効きました。

Skillにしないほうがいい業務

繰り返さない作業は単発の指示で足りる

繰り返さない作業をSkillにするのは、失敗例として整理されています。
一度きりのデータベース移行のような作業は、Subagentか、その場の単発の指示で十分です。

更新しないSkillは古い手順を実行する

作ったSkillは、置きっぱなしでは劣化します。
業務手順が変わったのにSKILL.mdを更新しないと、Claudeは古い手順を正しい手順として実行します。
古い手順を自信満々に実行されるほうが、何も知らない状態より厄介です。

着手の目安は3条件

私の運用では、着手の目安を3条件に置いています。
月1回以上やっていること、手順が固定されていること、アウトプットの形が決まっていること（推測：この条件設定は自社運用での判断基準であり、公式の推奨ではありません）。

他人のSkillを拾う前に知っておく安全面

Skillは任意のコードを実行できる

Skillはスクリプトを含められます。
つまりClaudeの環境で任意のコードを実行できるということで、公式ドキュメントも信頼できる提供元のものだけをインストールすべきだとしています（出典: platform.claude.com/docs/en/agents-and-tools/agent-skills/overview）。

守るのは3つだけ

小規模事業者向けに、最低限のルールを3つに絞るとこうなります。

• 導入前にSKILL.mdとスクリプトを全部読む
• 社外の配布物は、業務データを含むディレクトリで動かさない
• 自社業務のSkillは自分で書く

3つめは制約に見えて、実は結論でもあります。
自社の手順は外部から拾えないので、自作が最も安全かつ有効だからです。

よくあるご質問

完成したSKILL.mdの実例

ここまでの要素を入れた形が次のSKILL.mdです。
.claude/skills/monthly-invoice/SKILL.md として置けば、そのまま動きます。

---
name: monthly-invoice
description: 月次請求書の作成手順。対象顧客の抽出、金額の集計、請求書ファイルの生成、送付前チェックまでを扱う。月次の請求書を作るとき、請求金額を確認するとき、請求書の書式を直すときに使用する。
---

# 月次請求書の作成手順

## 使う場面

毎月の請求書作成。前月分の作業実績をもとに、顧客ごとの請求書を作る。
単発の見積書はこの手順の対象外とする。

## 手順

1. 前月の作業記録を集計する
   - 対象期間は前月1日から末日まで
   - 顧客ごとに合計金額を出す
2. 請求書の書式に流し込む
   - 書式は `references/invoice-template.md` を使う
   - 記載項目と並び順は変更しない
3. 送付前チェックを行う
   - チェック項目は `references/checklist.md` の全項目
   - 1つでも未達なら送付しない
4. 顧客名、請求金額、チェック結果の3点を一覧で報告する

## よくある失敗

- 締め日をまたいだ作業を前月分に含めてしまう
  → 期間の境界は必ず作業記録の日付で判定する
- テンプレートの項目を勝手に増減する
  → 書式の変更が必要なときは、先に確認を取る

## テストシナリオ

- 想定どおり：前月分の作業記録が揃っている状態
- 対象外：単発の見積書を作りたいと言われた状態（このSkillを使わない）
- 境界：作業記録が月末日と翌月1日にまたがっている状態

本文に書かなかったもの

書式そのものもチェック項目の中身も、本文には書いていません。
どちらも references/ 以下に置き、本文は「どのファイルを、どの順で使うか」だけを指しています。

まず繰り返している手順を1本だけ書く

作る順番は、Skillが先、必要ならSubagentが後です。
手順知識が先にあれば、後工程は増築で済みます。

着手するのは1本だけで構いません。
直近1か月でいちばん繰り返した指示を選んで、SKILL.mdに書く。
それだけで、その業務の出力のブレは目に見えて減ります。

完璧なSKILL.mdを目指す必要もありません。
公式が推奨しているのも、使いながら失敗を書き足して育てるやり方でした。

私たちがAI顧問やセットアップ支援でご相談を受けるときも、最初に整理するのはこの論点です。
どの業務が繰り返されていて、どこを手順として渡せるのか。
ここが決まらないまま道具を増やしても、指示を書く手間が積み上がるだけになります。

もし「うちの場合はどこから手をつけるべきか」で止まっているようでしたら、そのあたりからご相談ください。