Agent Skills Workshop - AIへの頼み方を仕組み化する

「Agent Skills」のワークショップ資料。なぜ毎回の指示出しでは限界があるのか、Skills で何ができるのか（議事録・コードレビュー・テスト生成など）、Skillsの仕組み、SkillsBench 研究に基づく効果的な書き方、セキュリティ上の注意点まで、入門から発展的な内容まで一通り網羅しています。後半は自分の Skill を手で書いて動かすハンズオン構成。Skillsの社内勉強会やオンボーディングの教材としてそのまま使えることを意図して作成し、実際に実施しました！
対応ツール: Claude Code / Codex ほか agentskills.io 標準準拠ツール全般。

Transcript

1. Agent Skills Workshop 今日から使える"AIへの頼み方" Gota / 2026-02-20
2. AI にお願いするたび、毎回イ チから説明し直してません？ 同じ指示を何度もコピペしていませんか？ 2
3. Agent Skills = "AIへの頼み方"を ファイルに書いて、何度でも再利用す る仕組み
4. 1. Why：なぜ Skills が必要か（5分） 2. What：何が作れるか + 仕組み（10分） 3. Hands-on：自分の Skill を作ろう（40分） 4. Advanced：もっと知りたい方へ（付録） 今日の流れ 4 今日は「知る → 見る → 作る → 応用」の4ステップ
5. 全部渡しても動く。 でも絞った方がもっと良い 最新モデルは長いコンテキストに強く なった でも実務のコンテキスト量は膨大。長 くなるほど精度は落ちる 重要な情報だけ選んで渡す方が結果が 良い トークンが少ないほど速くて安い コンテキストの落とし穴 出典: Liu et al., "Lost in the Middle" (Stanford, 2023/TACL 2024) 5
6. STAGE 1 Metadata name + description 本棚で背表紙を⾒る ~100 tokens 常時ロード match STAGE 2 SKILL.md 指⽰ + フォーマット ⽬次を開いて確認する <5,000 tokens トリガー時 需要時 STAGE 3 Resources scripts/ references/ 必要な章だけ読む オンデマンド 必要時のみ 本棚から必要な本だけ取り、必要な章だけ読む = コンテキスト効率の最⼤化 Progressive Disclosure 6 答えは「必要なときに必要な分だけ渡す」
7. Skills の正体はファイルシステム Markdown だけでなく画像・CSV・ス クリプトも扱える プログラミング不要、Git で共有で きる MCP が道具なら、Skills はレシピ ファイルシステムの力 7
8. 27 プラットフォームが agentskills.io 標準に対応 Claude Code, Codex, Gemini CLI, Cursor, VS Code, GitHub... オープン標準 出典: agentskills.io (2026年2月時点) 一度書けば、好きなエージェントで使える
9. 何が作れるのか ビジネスでもエンジニアリングでも
10. プログラミングなしで、こんな Skills が作れる 議事録スキル 会議メモ → 要約+アクション抽出 提案書スキル 顧客情報 → 提案書ドラフト 週報スキル 箇条書き → 整形された週報 データ分析 CSV → グラフ付きレポート ビジネスで使える Skills 10
11. エンジニアなら繰り返す手順を丸ごと任せられる 複数観点レビュー セキュリティ・性能・命名を一括チェック テスト生成 関数 → テストコード Issue 対応 /fix-issue 123 で一発修正 仕様書ドラフト 要件メモ → 設計ドキュメント エンジニア向け Skills 11
12. 個人のノウハウが、チームの資産になる Git で共有: Skill をリポジトリに入れれば、チーム全員が同じ手順で動ける ナレッジ蓄積: ベテランの暗黙知が SKILL.md として明文化・蓄積される 新人オンボーディング: Skill を使うだけで、初日からベテランの手順を再現できる 継続改善: 改善したら commit。チーム全体が即座にアップデートされる 組織で使う Skills 12
13. --- name: meeting-notes description: > 会議の録音テキストから議事録を作成する。 会議、ミーティング、打ち合わせの記録に使う。 --- 会議テキストから以下を抽出してください: 1. **参加者**: 発言者の一覧 2. **決定事項**: 合意された内容 3. **アクションアイテム**: 誰が・何を・いつまでに Skill ファイルの構造 13 Skill は YAML ヘッダー + Markdown 本文だけ
14. 分野によって+4〜 +52ppの精度向上 全体平均 +16.2pp、専門手順のある 分野で効果大 4+ Skills は逆効果（1〜3 個の範囲で 使うのがベスト） 小モデル+Skills > 大モデル単体のケ ースも 自己生成 Skills は効果なし → 人間が 書くべき Healthcare +51.9 pp Manufacturing +41.9 pp Cybersecurity +23.2 pp Natural Science +21.9 pp Energy +17.9 pp Office / White Collar +17.8 pp Finance +15.1 pp Media & Content +13.9 pp Robotics +7.0 pp Mathematics +6.0 pp Software Engineering +4.5 pp Skills の効果（研究データ） 出典: Li et al., "SkillsBench" (arXiv 2602.12670, 2026) 14
15. 詳細型が最も効果的、 詰め込みすぎは逆効果 詳細型：手順を具体的に書く 簡潔型：要点だけ絞る 標準型：README 的な書き方 全部入り型：逆効果（−2.9pp） → SKILL.md は 500行以下。長い参照資 料は references/ に分離 書き方で効果が変わる 出典: Li et al., "SkillsBench" (arXiv 2602.12670, 2026) — Format Ablation Study 15
16. Claude Code Codex CLI Antigravity プロジェクト .claude/skills/ .agents/skills/ .agent/skills/ 個人 ~/.claude/skills/ ~/.agents/skills/ ~/.gemini/antigravity/ skills/ 共通 SKILL.md の書き方は全ツ ール共通（agentskills.io 標準） 配置場所と適用範囲 16 置く場所で誰が使えるかが決まる（ツールごとにパスが異なる）
17. 公開 Skills の36.8% にセキュリティ上の問題がある Snyk「ToxicSkills」調査: 3,984 skills 中 36.8% に脆弱性、13.4% が深刻 ClawHavoc キャンペーン: 341 skills が macOS マルウェア（AMOS）を配布 SKILL.md の全行が「命令」として解釈される → プロンプトインジェクションが容易 外部 Skills の注意点 出典: Snyk ToxicSkills (2026-02), VirusTotal (2026-02), arXiv 2510.26328 17 自分で書くのが一番安全。外部 Skills は必ず中身を読んでから使う
18. Skill の description は tools 配列に格納される Claude が意味的に「この Skill が合う」と判断したら自動ロード キーワード一致ではなく、LLM の言語理解で判定 /skill-name で直接呼び出しも可能 ユーザー 「議事録を作って」 セマンティック マッチング SKILL.md ⾃動ロード description: 会議, 議事録, ミーティング... オートロードの仕組み 18 description をセマンティックマッチングで判断
19. Hands-on Hands-on 自分の Skills を作ろう 自分の Skills を作ろう
20. どのツールからでも始められる Claude Code ターミナル Claude.ai ブラウザ（今日は手書き） Claude Desktop デスクトップアプリ Codex / Antigravity 契約なしなら Antigravity(無料) 使えるツール 20
21. 手を動かす前に、押さえておきたいコツ description は具体的に 「いつ使うか」をキーワードで 出力フォーマットを明示 一貫した結果が得られる 小さく始めて育てる 一度に全部盛り込まない 実例を1-2セット入れる 精度が上がる(入れすぎは逆効果) いい Skill を作るコツ 21
22. AI と苦戦した経験が、最高の Skill になる AI がなかなか正しい答えを出せなかった作業 → モデルがその手順を知らないサイン 試行錯誤して解決したら、そのセッション自体が Skill の原材料 解決手順を SKILL.md にまとめれば、次回から一発で解決する SkillsBench でも「自己生成 Skills は効果なし」→ 人間の苦戦経験にこそ価値がある Skill のタネの見つけ方 22
23. 初めての Skill は思ったより早く作れる Step 1: 選ぶ 繰り返してる作業を1つ選ぶ Step 2: 手で書く SKILL.md にやり方を手書きする Step 3: 動かす フォルダに置いて話しかけるだけ 3ステップで Skill を作る 23
24. 繰り返してる作業を1つ選ぶ 「毎週やってる」 「毎回同じ説明をしてる」作業はないか？ テンプレ欲しいなと思ったことはないか？ 同じ指示を複数プロジェクトにコピーしてるなら、それは Skill にすべきサイン Step 1: 何をスキル化するか 24
25. --- name: weekly-report description: > 箇条書きメモから週報を作成する。 週報、ウィークリーレポート、今週のまとめに使う。 --- 入力された箇条書きメモから、以下のフォーマットで週報を作成: ## 週報: [日付範囲] ### 今週の成果 ### 進行中 Step 2: SKILL.md を手で書く 25 まずは手書きで構造を理解する（慣れたら Skill Creator で量産 OK）
26. フォルダに置いて、 話しかけるだけ Claude Code: .claude/skills/my- skill/SKILL.md Codex: .agents/skills/my- skill/SKILL.md Claude.ai: Skill Creator で直接アップ ロード テスト: 関連する質問で自動発動を確認 /skill-name で直接起動 Step 3: 配置して試す 26
27. ハンズオン作業タイム（30-40分） 自分の業務に役立つ Skill を1つ作ってみよう
28. 「次もやりそう」→ Skill にする → 使いながら育てる 「またやりそうだな」と思った作業は、その場で Skill 化する 作って終わりではない。使う → 直す → また使うのループで育てる 慣れたら自分専用の Skill Creator（Skill を生成する Skill）を自作すると量産が楽になる チームの Skill が増えるほど、組織全体の生産性が上がる 最初の1つから広げよう 28
29. 1 絞った方がもっと良い結果が出る 全部渡しても動く時代。でも必要な分だけ渡す方が精度もコストも良い 2 SKILL.md はただの Markdown プログラミング不要。誰でも書ける 3 好きなエージェントで使えるオープン標準 27プラットフォームが対応。一度書いたらどのツールでも再利用できる 今日のまとめ 29 Skills は「頼み方をファイルにする」だけ ちなみに、このスライドも 10+ の Skills を組み合わせたハーネスで作成しています
30. Advanced もっと知りたい方へ
31. Skill は「テストから作る」のが公式推奨 1 Skill なしで実行 まず Claude に素で作業させ、失敗点を記録 2 評価セット作成 3〜5件のテストケース（発動/不発動/エッジ） 3 最小限の Skill を書く テストを通す最小限の指示だけ書く 4 比較・改善 Skill あり/なしを比較 → 指示を改善 → 繰り返す Eval 駆動開発 出典: Anthropic Best Practices, OpenAI "Testing Agent Skills Systematically with Evals" 31
32. テストは「発動」 「品質」 「効率」の3軸で評価 トリガーテスト 正しい質問で発動し、無関係な質問で発動し ないか。目標: 90%+ 機能テスト 出力が期待どおりか。手順は正しいか。フォ ーマットは一貫しているか 効率テスト トークン消費量の比較。Skill ありで 12,000→6,000トークン(50%削減)の事例も Skill のテスト3領域 出典: Anthropic Complete Guide, OpenAI eval-skills 32
33. --- # ── 標準フィールド（agentskills.io 仕様） ── name: deploy-checker # 必須。max 64文字, lowercase + hyphens + numbers description: > # 必須。max 1024文字 デプロイ前のチェックリストを実行する。 デプロイ、リリース、本番反映時に使う。 license: MIT # ライセンス名 compatibility: "Node.js 18+" # 動作環境。max 500文字 metadata: { author: me, v: "1.0" } # 任意 key-value allowed-tools: Bash(git:*) Read # Experimental # ── Claude Code 固有フィールド ── argument-hint: "[env]" # 引数のヒント disable-model-invocation: true # 手動 /name のみ model: sonnet # 使用モデル指定 context: fork # サブエージェント実行 agent: general-purpose # fork 時のエージェント種別 YAML フロントマター完全版 33 上級者向け: Skill の全設定オプション
34. my-skill/ ├── SKILL.md # メイン指示（500行以下） ├── references/ # 参照資料（必要時のみ読込） │ ├── format-guide.md # フォーマット仕様 │ └── domain-terms.csv # 専門用語辞書 └── scripts/ # 自動化スクリプト └── validate.sh # バリデーション SKILL.md が唯一の必須ファイル。残りは全てオプション references/ は Stage 3: 必要時のみ読み込まれる（Progressive Disclosure） scripts/ はツール実行時に呼ばれる（バリデーション、変換等） Skill のディレクトリ構成 34 複雑な Skill はファイルを分けて整理する
35. 構成パターン ドメイン別分割: reference/finance.md, sales.md を必要時のみ読込 Plan-Validate-Execute: 計画ファイル → スクリプト検証 → 実行で安全性確保 フィードバックループ: バリデータ → 修正 → 再検証の繰り返し 連携パターン MCP 連携: ServerName:tool_name で完 全修飾名を使う サブエージェント合成： context: fork で分離実行、 skills: で Skill を事前読 込 Skill の高度な設計パターン 出典: Anthropic Best Practices, Claude Code Subagents docs 35 実務で使える5つの設計パターン
36. Skills CLAUDE.md / AGENTS.md Subagents Hooks 役割 手続き知識 + オーケス トレーション 必ず毎回読まれる必須 ルール コンテキスト分離 ツール実行前後の自 動処理 読込 オンデマンド or /name 呼出 常時ロード spawn時に独立コン テキスト イベント駆動 用途 繰り返す手順、ワーク フロー自動化 守らせたいルール・制約 並列化、コンテキス ト保護 バリデーション、自 動承認 Skills vs CLAUDE.md vs Subagents 36 使い分けの判断基準 Skills + Subagents + Hooks の組み合わせが強力
37. 症状 原因 対処法 発動しない description が曖 昧 ユーザーが実際に使う言い回しを description に キーワードとして追加 誤発動が多い description が広 すぎ 具体的に絞る。確実にしたければ disable- model-invocation: true 認識されない トークン予算超 過 /context で使用量を確認。Skill 数を整理・統 合 指示が無視さ れる SKILL.md が長す ぎ 500行以下に。詳細は references/ に分離 ファイル名エ ラー 大文字小文字 必ず SKILL.md （全大文字） 。 skill.md は認識 されない よくあるトラブルと対処法 出典: Anthropic Troubleshooting docs, Complete Guide 37 Skill がうまく動かないときのチェックリスト
38. 公式ドキュメント: code.claude.com/docs/en/skills Complete Guide (PDF): Building Skills for Claude OpenAI Eval Skills: developers.openai.com/blog/eval-skills オープン標準仕様: agentskills.io/specification 公式 Skills リポジトリ: github.com/anthropics/skills SkillsBench 論文: arXiv 2602.12670 参考リンク集 38 さらに学びたい方への公式リソース
39. Thank You!