Share
Embed
Agent Skills Workshop - AIへの頼み方を仕組み化する
「Agent Skills」のワークショップ資料。なぜ毎回の指示出しでは限界があるのか、Skills で何ができるのか(議事録・コードレビュー・テスト生成など)、Skillsの仕組み、SkillsBench 研究に基づく効果的な書き方、セキュリティ上の注意点まで、入門から発展的な内容まで一通り網羅しています。後半は自分の Skill を手で書いて動かすハンズオン構成。Skillsの社内勉強会やオンボーディングの教材としてそのまま使えることを意図して作成し、実際に実施しました!
対応ツール: Claude Code / Codex ほか agentskills.io 標準準拠ツール全般。
利用条件: ご自由にお使いください。引用してくれると嬉しいです!ただし本資料の無断での有償販売は禁止です。何かあればXのDMまで!
最終更新日: 2026/2/21
Gota
February 21, 2026
Transcript
39 slides
-
1. Why:なぜ Skills が必要か(5分) 2. What:何が作れるか + 仕組み(10分) 3. Hands-on:自分の
Skill を作ろう(40分) 4. Advanced:もっと知りたい方へ(付録) 今日の流れ 4 今日は「知る → 見る → 作る → 応用」の4ステップ -
全部渡しても動く。 でも絞った方がもっと良い 最新モデルは長いコンテキストに強く なった でも実務のコンテキスト量は膨大。長 くなるほど精度は落ちる 重要な情報だけ選んで渡す方が結果が 良い トークンが少ないほど速くて安い コンテキストの落とし穴
出典: Liu et al., "Lost in the Middle" (Stanford, 2023/TACL 2024) 5 -
STAGE 1 Metadata name + description 本棚で背表紙を⾒る ~100 tokens 常時ロード
match STAGE 2 SKILL.md 指⽰ + フォーマット ⽬次を開いて確認する <5,000 tokens トリガー時 需要時 STAGE 3 Resources scripts/ references/ 必要な章だけ読む オンデマンド 必要時のみ 本棚から必要な本だけ取り、必要な章だけ読む = コンテキスト効率の最⼤化 Progressive Disclosure 6 答えは「必要なときに必要な分だけ渡す」 -
27 プラットフォームが agentskills.io 標準に対応 Claude Code, Codex, Gemini CLI, Cursor,
VS Code, GitHub... オープン標準 出典: agentskills.io (2026年2月時点) 一度書けば、好きなエージェントで使える -
プログラミングなしで、こんな Skills が作れる 議事録スキル 会議メモ → 要約+アクション抽出 提案書スキル 顧客情報 →
提案書ドラフト 週報スキル 箇条書き → 整形された週報 データ分析 CSV → グラフ付きレポート ビジネスで使える Skills 10 -
エンジニアなら繰り返す手順を丸ごと任せられる 複数観点レビュー セキュリティ・性能・命名を一括チェック テスト生成 関数 → テストコード Issue 対応 /fix-issue
123 で一発修正 仕様書ドラフト 要件メモ → 設計ドキュメント エンジニア向け Skills 11 -
個人のノウハウが、チームの資産になる Git で共有: Skill をリポジトリに入れれば、チーム全員が同じ手順で動ける ナレッジ蓄積: ベテランの暗黙知が SKILL.md として明文化・蓄積される 新人オンボーディング:
Skill を使うだけで、初日からベテランの手順を再現できる 継続改善: 改善したら commit。チーム全体が即座にアップデートされる 組織で使う Skills 12 -
--- name: meeting-notes description: > 会議の録音テキストから議事録を作成する。 会議、ミーティング、打ち合わせの記録に使う。 --- 会議テキストから以下を抽出してください: 1.
**参加者**: 発言者の一覧 2. **決定事項**: 合意された内容 3. **アクションアイテム**: 誰が・何を・いつまでに Skill ファイルの構造 13 Skill は YAML ヘッダー + Markdown 本文だけ -
分野によって+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 -
詳細型が最も効果的、 詰め込みすぎは逆効果 詳細型:手順を具体的に書く 簡潔型:要点だけ絞る 標準型:README 的な書き方 全部入り型:逆効果(−2.9pp) → SKILL.md は
500行以下。長い参照資 料は references/ に分離 書き方で効果が変わる 出典: Li et al., "SkillsBench" (arXiv 2602.12670, 2026) — Format Ablation Study 15 -
Claude Code Codex CLI Antigravity プロジェクト .claude/skills/ .agents/skills/ .agent/skills/ 個人
~/.claude/skills/ ~/.agents/skills/ ~/.gemini/antigravity/ skills/ 共通 SKILL.md の書き方は全ツ ール共通(agentskills.io 標準) 配置場所と適用範囲 16 置く場所で誰が使えるかが決まる(ツールごとにパスが異なる) -
公開 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 は必ず中身を読んでから使う -
Skill の description は tools 配列に格納される Claude が意味的に「この Skill が合う」と判断したら自動ロード
キーワード一致ではなく、LLM の言語理解で判定 /skill-name で直接呼び出しも可能 ユーザー 「議事録を作って」 セマンティック マッチング SKILL.md ⾃動ロード description: 会議, 議事録, ミーティング... オートロードの仕組み 18 description をセマンティックマッチングで判断 -
どのツールからでも始められる Claude Code ターミナル Claude.ai ブラウザ(今日は手書き) Claude Desktop デスクトップアプリ Codex
/ Antigravity 契約なしなら Antigravity(無料) 使えるツール 20 -
AI と苦戦した経験が、最高の Skill になる AI がなかなか正しい答えを出せなかった作業 → モデルがその手順を知らないサイン 試行錯誤して解決したら、そのセッション自体が Skill
の原材料 解決手順を SKILL.md にまとめれば、次回から一発で解決する SkillsBench でも「自己生成 Skills は効果なし」→ 人間の苦戦経験にこそ価値がある Skill のタネの見つけ方 22 -
初めての Skill は思ったより早く作れる Step 1: 選ぶ 繰り返してる作業を1つ選ぶ Step 2: 手で書く
SKILL.md にやり方を手書きする Step 3: 動かす フォルダに置いて話しかけるだけ 3ステップで Skill を作る 23 -
--- name: weekly-report description: > 箇条書きメモから週報を作成する。 週報、ウィークリーレポート、今週のまとめに使う。 --- 入力された箇条書きメモから、以下のフォーマットで週報を作成: ##
週報: [日付範囲] ### 今週の成果 ### 進行中 Step 2: SKILL.md を手で書く 25 まずは手書きで構造を理解する(慣れたら Skill Creator で量産 OK) -
フォルダに置いて、 話しかけるだけ Claude Code: .claude/skills/my- skill/SKILL.md Codex: .agents/skills/my- skill/SKILL.md Claude.ai:
Skill Creator で直接アップ ロード テスト: 関連する質問で自動発動を確認 /skill-name で直接起動 Step 3: 配置して試す 26 -
「次もやりそう」→ Skill にする → 使いながら育てる 「またやりそうだな」と思った作業は、その場で Skill 化する 作って終わりではない。使う →
直す → また使うのループで育てる 慣れたら自分専用の Skill Creator(Skill を生成する Skill)を自作すると量産が楽になる チームの Skill が増えるほど、組織全体の生産性が上がる 最初の1つから広げよう 28 -
1 絞った方がもっと良い結果が出る 全部渡しても動く時代。でも必要な分だけ渡す方が精度もコストも良い 2 SKILL.md はただの Markdown プログラミング不要。誰でも書ける 3 好きなエージェントで使えるオープン標準
27プラットフォームが対応。一度書いたらどのツールでも再利用できる 今日のまとめ 29 Skills は「頼み方をファイルにする」だけ ちなみに、このスライドも 10+ の Skills を組み合わせたハーネスで作成しています -
Skill は「テストから作る」のが公式推奨 1 Skill なしで実行 まず Claude に素で作業させ、失敗点を記録 2 評価セット作成
3〜5件のテストケース(発動/不発動/エッジ) 3 最小限の Skill を書く テストを通す最小限の指示だけ書く 4 比較・改善 Skill あり/なしを比較 → 指示を改善 → 繰り返す Eval 駆動開発 出典: Anthropic Best Practices, OpenAI "Testing Agent Skills Systematically with Evals" 31 -
テストは「発動」 「品質」 「効率」の3軸で評価 トリガーテスト 正しい質問で発動し、無関係な質問で発動し ないか。目標: 90%+ 機能テスト 出力が期待どおりか。手順は正しいか。フォ ーマットは一貫しているか
効率テスト トークン消費量の比較。Skill ありで 12,000→6,000トークン(50%削減)の事例も Skill のテスト3領域 出典: Anthropic Complete Guide, OpenAI eval-skills 32 -
--- # ── 標準フィールド(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 の全設定オプション -
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 はファイルを分けて整理する -
構成パターン ドメイン別分割: 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つの設計パターン -
Skills CLAUDE.md / AGENTS.md Subagents Hooks 役割 手続き知識 + オーケス
トレーション 必ず毎回読まれる必須 ルール コンテキスト分離 ツール実行前後の自 動処理 読込 オンデマンド or /name 呼出 常時ロード spawn時に独立コン テキスト イベント駆動 用途 繰り返す手順、ワーク フロー自動化 守らせたいルール・制約 並列化、コンテキス ト保護 バリデーション、自 動承認 Skills vs CLAUDE.md vs Subagents 36 使い分けの判断基準 Skills + Subagents + Hooks の組み合わせが強力 -
症状 原因 対処法 発動しない description が曖 昧 ユーザーが実際に使う言い回しを description に
キーワードとして追加 誤発動が多い description が広 すぎ 具体的に絞る。確実にしたければ disable- model-invocation: true 認識されない トークン予算超 過 /context で使用量を確認。Skill 数を整理・統 合 指示が無視さ れる SKILL.md が長す ぎ 500行以下に。詳細は references/ に分離 ファイル名エ ラー 大文字小文字 必ず SKILL.md (全大文字) 。 skill.md は認識 されない よくあるトラブルと対処法 出典: Anthropic Troubleshooting docs, Complete Guide 37 Skill がうまく動かないときのチェックリスト -
公式ドキュメント: 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 さらに学びたい方への公式リソース