このセクションの目標:ある第1課あの「発動する最小スキル」について、補足します reference/ タスクを階層化し、ミスが起きやすいタスクには「まず計画文書を作成 → 検証 → 実行」という検証ループを設ける。この学習を終える頃には、複数のファイルからなるSkillを提出できるようになり、自己テストにおいて「本文が肥大化せず、詳細が必要な時にのみ読み込まれる」という記録が少なくとも1回は残っているはずだ。

前提条件
完了した、あるいは少なくとも参加した第1課:30分で、自動的にトリガーされる最初のClaude Agent Skillを作成する――YAMLのフロントマターを含むファイルを1つ用意しておく必要がある SKILL.md、さらに「トリガーすべき/トリガーすべきでない」という自己診断も行いました。
環境は、引き続きAgent Skillsに対応したClaudeクライアント(claude.ai / Claude Code / Agent SDKなど)です。公式の対応状況について、私が確認したところ、2026年10月28日時点では以下の通りです:エージェントスキルの概要そしてスキル作成のベストプラクティス、および工学に関するブログ記事 「Agent Skills」で、実社会で活躍するエージェントを育成する(2025年10月16日、その後、クロスプラットフォーム標準としてオープンソース化された)。
このセクションではPythonでの記述は求められません。検証ループについては、まずは「人間が読めるJSON/Markdown形式の計画ファイル+リスト」を使用してください。スクリプト版については第3課で扱います。
コンセプト:なぜすべてを SKILL.md に詰め込めないのか
第1課では「description」でつまずきました。今回の課では「貪欲」という部分でつまずきました。週報の「Skill」がスムーズに書けるようになった後、顧客名のマッピング、言葉遣いのタブー、過去の週報のサンプル、さらにはFeishuのフィールド説明まで、すべてを1つの SKILL.md。その結果、トリガーされるたびに大量のコンテキストを消費してしまう上、通常のスケジューリングでは顧客に関する百科事典一冊分を丸ごと覚えなければならない。
公式ではその解法を プログレッシブ・ディスクロージャー(段階的開示):起動時には各スキルのname/descriptionのみをプリロードし、タスクにマッチした時点で読み込む SKILL.md 本文;その下の reference/そしてscripts/そしてassets/ 本文中で言及された場合のみ読み込まれる。ベストプラクティスには、本文はできるだけ500行以内に収め、詳細部分は別箇所に分けるよう明記されている。

もう一方は検証ループです。「ベストプラクティス」の「検証可能な中間出力を作成する」という項目では、次のように明快に述べられています。一括変更、破壊的な操作、ルールが複雑な場合には、まずエージェントに機械が検証可能な計画ファイルを作成させる(例: changes.json / plan.md))、確認が済んでから取り掛かる。私が自分用に作った「方言版」は――まず計画書を作成してから実行する、口を開くやいなや「原文を修正してください」などと言わないでください。

ステップバイステップの実践ガイド
以下、引き続き第1課の Notesからの週次レポート ベースとして、これを「簡略版本文 + 参考文献 + 計画検証」にアップグレードする。

手順 1:太字の本文を reference/ ディレクトリにコピーする
内容:「Skill」ディレクトリの横に作成する reference/、「あまり一緒に使わない」素材を削除し、本文にはナビゲーションと必須ルールのみを残す。
weekly-report-from-notes/
SKILL.md
reference/
tone-and-banwords.md
section-examples.md
stakeholder-map.md
SKILL.md 本文を次のような内容に変更してください:
---
name: weekly-report-from-notes
description: 散らかったメモを、決定事項、障害、次のアクションを含む簡潔な中国語の週次レポートに変換します。ユーザーが「周報」や「週の進捗」を要求した場合、または順序のない作業メモを貼り付けた場合に使用してください。文体のルールや例については、リンクされた参照ファイルを参照してください。
---
# 週報の整理
## 出力テンプレート
「今週の完了事項」「重要な決定事項」「障害」「来週の計画」「あなたのサポートが必要」のみを使用してください。
「議論済み」を「完了」と表記することは禁止です。情報が不足している場合は「追記必要」と記載し、事実をでっち上げることは禁止です。
## 必要に応じた読み込み(一度に関連ファイルのみを読み込む)
- 口調と禁止語:[reference/tone-and-banwords.md](reference/tone-and-banwords.md)を参照
- 段落の例:[reference/section-examples.md](reference/section-examples.md)を参照
- 関係者への呼びかけ:ユーザーが具体的なチーム/顧客に言及した場合のみ、[reference/stakeholder-map.md](reference/stakeholder-map.md)を参照
## 失敗しやすいタスク:計画してから執筆する
メモが15件を超える場合、または「外部との連携/上層部への報告」に関わる場合は、まず `plan.md`(後述の検証ループを参照)を作成し、確認後に最終稿を生成してください。
なぜ:ベストプラクティスでは、参照は「SKILL.md から1階層下」に保つことを重視しており、reference 内にさらに reference を入れ子にしないよう注意してください。そうしないと、プロキシが head 最初の数行を読んだだけで、読み終えたと思ってしまった。

手順 2:reference ファイルにインデックスを追加する(100 行を超える場合)
内容:いずれかの参照が約100行を超える場合は、ファイルの先頭に「目次」リストを追加する。例: tone-and-banwords.md::
# 口調と使用禁止語
## 目次
- 人称と視点
- 使用禁止語リスト
- 未決定事項の記述方法
- 反例
## 人称と視点
対外的な週報では「私たち」を使用し、対内的には「私」を使用してもよい。突然切り替えないこと。
## 禁止用語一覧
エンパワーメント、クローズドループ、取り組みの糸口、粒度の整合、連携……(チームの状況に応じて追加すること)
## 未解決事項の記述方法
必ず「未解決」という言葉を明記し、誰が/何が原因で停滞しているかを明確に記述すること。
## 反例
「会議で取り上げられた」を「すでにリリース済み」と記述した場合――即座に不合格とし、当該段落を書き直すこと。
なぜ:エージェントは時々ファイルをプレビューすることがあります。ディレクトリは、読み込みが完了したと誤解することなく、その先に何があるかをエージェントに知らせます。
手順 3:「計画文書を作成してから実行する」という検証ループを設定する
内容:ある SKILL.md チェックボックス付きのリストを1つ追加し、中間ファイルを先に生成させるようにする。
## 確認チェックリスト(ノートが多い場合/外部への報告時に必須)
以下をコピーしてチェックを入れてください:
- [ ] ノート全体を読み、不確かな文に印をつける
- [ ] plan.mdを作成する:「どの節に書くか/どのノートを根拠とするか/未決定か」を各項目ごとに記載する
- [ ] 自己チェック:捏造がないか、議論を完了事項として記述していないか
- [ ] 承認を得てから最終週報を作成する
- [ ] 最終稿で禁止語を再チェック
### plan.md 最小テンプレート
# plan
| ノート原文の要約 | 対象セクション | 信頼度 | 備考 |
| --- | --- | --- | --- |
| 修了・支払いコールバック | 今週完了 | 高 | リリース済みか確認必要 |
| ログイン画面リニューアル会議・未決定 | 重要決定 / ブロック | 中 | 「未決定」と明記し、決定済みとして記述しないこと
実際のリクエストを一度実行してみる:「これらのメモを上司への週報としてまとめる」+ わざと矛盾する情報を2つ盛り込む。注目すべきは文章の書き方ではなく、それだ。まず plan.md を提出しましたか?、また、矛盾が「巧妙に覆い隠された」のではなく、「未解決」としてマークされているかどうか。

手順 4:「ファイルを解凍すると効果がある」ことを、対照実験を用いて証明する
内容:同じ長いメモを2回実行――
- 胖
SKILL.md(tone/examples/stakeholder をすべて本文に貼り戻す); - 本文を細く + 参照。
記録:依然としてトリガーされているか、最終稿が5段構成に従っているか、ステークホルダーのマッピングを不必要に参照していないか。私自身の経験では、通常の週報は2回目はそもそも開かないことが多い。 stakeholder-map.md――これこそが、段階的な開示の真価であり、目次が立派だからというわけではない。

手順 5:このセクションの自己チェックシートを1枚提出する
| ユースケース | 期待 | 実際 | 変更 |
|---|---|---|---|
| メモ → 社内週報 | トリガー;planは省略可;stakeholderは極力参照しない | ||
| >15件のメモ → 対外週報 | まず plan.md を作成し、その後最終稿を仕上げる | ||
| メモに矛盾がある | plan/最終稿の基準が未定のため、統一見解をでっち上げない | ||
| コードのみのエラー(逆テスト) | このスキルを発動させない |
よくあるエラー(3件以上)
1. 「reference/」ディレクトリを作成したが、プロキシは一度も起動しない。
たいていの場合、本文には「詳細は参考資料を参照」といった空虚な言葉しか書かれていない。「Xが発生した場合は、読み込む」と書くべきだ。 reference/foo.md」――トリガー条件付きのハードリンク。
2. 参考文献の中にさらに参考文献が入れ子になっており、詳細が読み取れない。
公式には、深いネストは推奨されていないことが明確にされています。すべて SKILL.md 1階層外へ。私が試した方法:禁止語を advanced.md → details.md、ところが、代理人は「advanced」をざっと目を通しただけで、書き始めてしまった。
3. 「検証ループ」を「まずはよく考えてから」と書き換えても、意味がないのと同じだ。
中間生成物を必ず明記しなければならない(plan.md / changes.json)と「合格しなければ続行しない」。ファイル名がない場合、代理人は頭の中で「少し考えて」から、そのまま最終稿を提出する。
4. ファイルを分解した後、description の幅を狭めるのを忘れていた/トリガーフレーズを追加し忘れた。
構造が変わっても、発見の仕組みは依然として「description」に依存しています。「対外報告」のプロセスを重視する場合は、ユーザーが使うであろう言葉(週報/週次進捗/対外共有)を「description」に残しておくことを忘れないでください。そうしないと、第1課でテストしたトリガーが再び機能しなくなる可能性があります。

宿題
- 第1課のSkillを少なくとも2つのreferenceファイルに分割し、すべてが
SKILL.md直接リンク。 - 「高リスク」のパスにプランファイルのテンプレートを追加し、Mâu Lôu Notesを使って「まず計画を立て、その後最終稿を作成する」というプロセスを一度実行してみる。
- 意図的に反例を作成する。Skill:reference を2階層にネストし、読み取り漏れがないか確認する――その後、1階層に戻す。
次回の予告
第3課:スクリプト付きスキルとセキュリティ監査。検証ルーチンを「手動チェックリスト」から実行可能なスクリプト(例:フィールドや形式の検証)へと移行し、信頼できるソースのみをインストールすること、scripts/ ディレクトリや依存関係、外部リンクの指示を精査することを盛り込んだセキュリティチェックリストを確認する。第2課の plan.md それでも残りますが、ただ「スクリプトがOKと判定して初めて先に進める」というゲートが一つ増えるだけです。
本シリーズの目次
- 第1課:30分で、自動的にトリガーされる最初のClaude Agent Skillを作成する(公開済み)
- 第2課:Skillに参照を追加する/「まず計画文書を作成してから実行する」という検証ループ(本文)
- 第3課:スクリプト付きスキルとセキュリティ監査(予告)
- 第4課:実際の失敗事例を用いたdescriptionの反復(予告)
シリーズ名:Claude Agent Skill 実践編。公式の概念確認については、Anthropic / Claude Docs の現在のページを基準とします。製品へのアクセス方法に変更があった場合は、ご利用のクライアントのドキュメントを基準としてください。


评论列表 (0条):
加载更多评论 読み込み中...