Agent Skills の Tip というか、仕様としてフロントマターの description には「何をするか」と「いつ使うか」を書く、というものがある。特に後者の「いつ使うか」が見落とされがちに見えている。
Agent Skills の仕様の What are skills? には、description: When to use this skill と記述されています。
Specification のページでは、description は「そのスキルが何をするか」と「いつ使うか」の両方を書くべきとされています。
The required
descriptionfield:
- Must be 1-1024 characters
- Should describe both what the skill does and when to use it
- Should include specific keywords that help agents identify relevant tasks
スキルは、Agent がまず name と description を見て関連しそうなものだけをロードする仕組みになっています。そのため、「何をするか」だけでなく「いつ使うか」を明示しておくことが、適切なタイミングで発動されやすくする上で重要でしょう。
Optimizing skill descriptions の Writing effective descriptions には、さらに「何をするか」よりも「いつ使うか」を、明確に書くべきとあります。
Use imperative phrasing. Frame the description as an instruction to the agent: “Use this skill when…” rather than “This skill does…” The agent is deciding whether to act, so tell it when to act.
なお仕様書自体も、仕様書のサンプルの description に when の記載がないという不整合があったのを訂正したのが以下のパッチ。
このPRでは、サンプルの description が「何をするか」しか書いていなかった箇所を、仕様が求める「何をするか」と「いつ使うか」の両方を満たす形に修正しています。マージされたことで、この解釈の根拠はより明確になったと思います。
--- name: pdf-processing -description: Extract text and tables from PDF files, fill forms, merge documents. +description: Extract PDF text, fill forms, merge files. Use when handling PDFs. ---
description に「何をするか」しか書かれておらず、「いつ使うか」が書かれていない SKILL.md を度々見かけるので、Agent Skills の仕様としてはこの点がもう少し知られてよいと思い書いておきました。
