エージェント スキルの厳しい真実
← Back
Jozo
Jozo
2026/01/22
8 min read
AI AgentsSkillsClaude CodePrompts

エージェント スキルの厳しい真実

2025年12月、Anthropicはエージェント スキルをオープンスタンダードとして公開しました。Microsoft、Cursor、およびその他の企業がこれを採用しました。現在、agentskills.ioに仕様が存在し、ディレクトリ構造があり、YAMLフロントマター要件があり、そして全体のエコシステムが構築されています。

しかし、フレームワークと仕様に進む前に、スキルが実際に何であるかを理解しましょう。

Anthropicが言うスキルとは

公式ドキュメントから：

エージェント スキルは、Claudeの機能を拡張するモジュラー機能です。各スキルは、指示、メタデータ、およびオプションのリソース（スクリプト、テンプレート）をパッケージ化し、Claudeが関連する場合に自動的に使用します。

Anthropicのエンジニアリングブログからの主要な洞察：スキルは、Claude に専門知識を与える再利用可能なファイルシステムベースのリソースです。毎回の会話で同じことを説明する代わりに、スキルとして一度書きます。

スキルが解決する問題

スキルなし：

  • 毎セッション、プロセスを再度説明する
  • コンテキストが繰り返される指示で満たされる
  • 会話全体で一貫性がない

スキルあり：

  • 指示を一度書く
  • 関連する場合にのみロードされる
  • セッション全体で一貫した動作

これがピッチです。そして理にかなっています。

公式な構造

Anthropicの仕様は特定の構造を要求します：

.claude/skills/youtube-transcribe/
├── SKILL.md              # 必須
├── scripts/
│   └── transcript.sh     # オプション
└── references/
    └── api-docs.md       # オプション

SKILL.mdファイルにはYAMLフロントマターが必要です：

---
name: youtube-transcribe
description: Transcribe YouTube videos to text. Use when user wants to extract transcript from a YouTube URL.
---

# YouTube Transcription

To transcribe a video:
1. Run: `scripts/transcript.sh "<youtube-url>"`
2. Output saves to: `transcripts/<video-id>.txt`

段階的な情報開示

Anthropicはスキルを3つのロードレベル周辺に設計しました：

レベルロード時期ロード内容
1. メタデータスタートアップ時名前 + 説明（約100トークン）
2. 指示トリガー時完全なSKILL.mdボディ
3. リソース参照時スクリプト、ドキュメント、テンプレート

考え方：必要な時に、必要なものだけをロードします。全てを全ての会話にダンプしないでください。

これはコンテキスト管理のための本当に巧妙なアーキテクチャです。

ここからが厳しい真実

仕様が強調しないことはここにあります：

スキルは単なるテキストです。

YAMLフロントマター？プロンプト用のテキストに解析されます。ディレクトリ構造？組織の慣例です。「段階的な情報開示」？Claudeがディスクからファイルを読みます。

フレームワークを削除して、スキルは：

  • 説明（Claudeが使用する時を知るため）
  • 指示（どのようにそれを行うか）
  • 多分スクリプト（実行するため）

それだけです。

これが実践的に何を意味するか

これらの2つのアプローチを考えてください：

アプローチA：フォーマルスキル

.claude/skills/youtube-transcribe/SKILL.md

---
name: youtube-transcribe
description: Transcribe YouTube videos to text files
---

# YouTube Transcription
Run: bun scripts/youtube-transcript.sh "<url>"

アプローチB：シンプルガイド

guides/how-to-transcribe-youtube.md

# How to Transcribe YouTube Videos
Run: bun scripts/youtube-transcript.sh "<url>"

Claudeにとって、これらはほぼ同じです。どちらもテキストファイルで指示があります。どちらも検索で見つけることができます。どちらもClaudeに何をするかを告げます。

違い：

  • アプローチA：フロントマターはスタートアップ時にプリロードされます（約100トークン）
  • アプローチB：Claudeは必要な場合に情報を検索します

説明をプリロードすることは構造オーバーヘッドの価値がありますか？時々はい、時々いいえ。

構造が役立つ場合

Anthropic構造は次の場合に本当に役に立ちます：

多くのスキルがあり、検出可能性が必要な場合

50の機能がある場合、説明をプリロードするとClaudeがそれらが存在することを知ることができます。50つのファイルすべてを読む必要なく。メタデータはインデックスとして機能します。

スラッシュコマンド呼び出しをしたい場合

スキルは/youtube-transcribeコマンドになります。ユーザーはそれを直接呼び出すことができます。これは本当のUXメリットです。

ツール制限が必要な場合

allowed-toolsフィールドはスキルが何をできるかを制限します。機密操作のセキュリティ利益。

スキルを他の人に配布する場合

オープンスタンダードはスキルがClaude Code、Cursor、VS Codeで機能することを意味します。移植性が重要です。

シンプルガイドが勝つ場合

しかし、多くの場合、シンプルなマークダウンガイドは同等に機能します：

ワンオフプロセデューア

# Deploy to Production
1. Run tests: `bun test`
2. Build: `bun run build`
3. Deploy: `./deploy.sh production`

これはフォーマルスキルである必要がありますか？おそらく違います。それはガイドです。Claudeは関連する場合に見つけます。

プロジェクト固有の知識

# Our Brand Voice
- Professional but approachable
- No jargon unless explained
- Examples over abstractions

これはコンテキストであり、機能ではありません。docs/のマークダウンファイルは問題ありません。

クイックリファレンス

# API Credentials
- Google Analytics: Property 478766521
- Mailgun: Check .env for MAILGUN_API_KEY
- Sentry: Project teamday-cc

情報にインデックスを付けます。段階的な情報開示は必要ありません。

スペクトラム

スキルは些細なものから包括的なものまでスペクトラムに存在します：

ワンライナー（多分フォーマルスキルを必要としない）

Email notifications: bun scripts/mailgun.send.js --to="x" --subject="y"

クイックリファレンス（境界線上）

# Google Analytics
Use the mcp__google-analytics tools.
Property ID: 478766521
Common queries: pageviews, sessions, top pages

ステップバイステップガイド（フォーマルスキルは理にかなっている）

# Add YouTube Video to Newsfeed

1. Fetch transcript
2. Extract metadata with curl (not WebFetch!)
3. Create feed post
4. Update embeddings
5. Extract entities
6. Trigger translations

包括的なワークフロー（確実にスキル）

マルチステップ手順、スクリプト、検証、エラー処理。私たちが使用するニュースフィードスキルは、特定のタスク用の250行以上のサブドキュメント付きです。

機能が複雑になるほど、フォーマル構造がより多くの価値をもたらします。

ファイルシステムはあなたの友達です

Anthropicエンジニアリングブログが強調しており、しばしば見落とされることはここにあります：

Claudeはファイルシステムアクセスを持っています。スクリプトはbashを介して実行されます。リファレンスファイルはディスク上に存在します。効果的に無制限のリファレンスマテリアルをバンドルできます。

Claudeはできます：

  • ファイルを検索：grep -r "transcribe" docs/
  • 見つけたものを読む：Read: docs/how-to-transcribe.md
  • スクリプトを実行：bash scripts/transcribe.sh

段階的な検出はスキルフレームワークを必要としません。 良いファイル組織とAIが検索方法を知ることが必要です。

スキルフレームワークはこれをメタデータで正式化します。しかし、基礎となるメカニズムはファイルシステムナビゲーションに過ぎません。

コンテキストがすべてです

Anthropicの設計からの本当の洞察：コンテキストウィンドウは限られています。

Claude Codeのシステムプロンプトは報告によると72kb。それは作業を始める前に約18,000トークンです。すべてのスキル説明はこれに追加されます。

段階的な情報開示設計はこれに対処しています：

  • スタートアップ時のメタデータのみ（小）
  • トリガー時の完全な指示（中）
  • 必要な場合のスクリプト/リファレンス（無制限、コンテキストにない）

しかし、以下から同じメリットが得られます：

  • 最小システムプロンプト
  • Claudeが必要な場合にドキュメントを検索
  • 関連するもののみを読む

原則は実装よりも重要です。

実際に重要なもの

数十のAIワークフローを構築した後、ここで学んだことがあります：

1. 明確な指示は巧妙な構造に勝ります

# Generate Blog Cover

We use FAL AI. Images save to public/images/.

Run:
bun scripts/generate-image.ts "prompt" name.webp

Good prompts:
- Include style ("minimalist illustration")
- Include subject ("AI agents collaborating")
- Include mood ("professional, tech-forward")

Claudeはこれをフォーマルスキルであろうとドックファイルであろうと従います。

2. 検出可能性は現実です

Claudeがあなたの指示を見つけられない場合、構造は重要ではありません。スキル説明であろうと良いファイル名であろうと、物事を見つけやすくします。

  • ✅ guides/how-to-transcribe-youtube.md
  • ✅ 明確な説明を持つスキル
  • ❌ notes/misc/stuff-v2-final.md

3. スクリプトは複雑さを解決します

指示が複雑になった場合、スクリプトを書きます：

# Instead of 20 lines of instructions:
bun scripts/add-video-to-newsfeed.ts "<youtube-url>"

スクリプトは複雑さをカプセル化します。スキルはそれを呼び出す方法を文書化するだけです。

4. 失敗に基づいて反復します

Claudeが何か間違ったことをした場合：

  • 不明確な指示？ → テキストを改善
  • 情報がありません？ → 追加
  • 見つけられない？ → より良い命名またはスキルインデックスに追加

防御的なルールを追加しないでください。実際の問題を修正してください。

要点

Anthropicはアレクスダンドロポロスが言ったように、AIの機能を整理するための思慮深いシステムを構築しました。段階的な情報開示は巧妙です。オープンスタンダードは移植性を可能にします。スラッシュコマンドはUXを改善します。

しかし、ここが厳しい真実です：

スキルはClaudeがファイルから読むテキスト指示に過ぎません。

フレームワークは追加されます：

  • プリロードされた説明（インデックス）
  • スラッシュコマンド呼び出し
  • ツール制限
  • クロスプラットフォーム移植性

これらは複数の機能を持つ複雑なセットアップの実際の利益です。

しかし、日常業務の場合：

  • 良く命名されたマークダウンファイルが機能する
  • Claudeは物を検索して見つけることができます
  • 明確な指示は構造よりも重要です
  • ファイルシステムは既に検出システムです

過度にエンジニアリングしないでください。シンプルなガイドで始めてください。メリットがオーバーヘッドを正当化する場合、フォーマルスキル構造を追加してください。

明確に書いてください。適切に組織してください。Claudeにその仕事をさせてください。

TeamDayで両方のアプローチを使用しています。ニュースフィード管理などの複雑なワークフロー用のフォーマルスキル。ワンオフプロセデューア用のシンプルなガイド。鍵はツールをタスクに合わせることです。