実際の知見から始める
一般知識だけでスキルを書くと、抽象的で汎用的すぎる手順になりがちです。価値が出るのは、実案件で効いた API パターン、落とし穴、プロジェクト固有の慣習を取り込んだ時です。
有効な作り方は主に 2 つあります。
実タスクから抽出する
実際の作業をエージェントと進め、その途中で与えた修正や判断基準をスキルへ落とし込みます。
- うまくいった手順
- 修正したポイント
- 入出力の形式
- プロジェクト固有の前提
既存資産から合成する
runbook、社内ドキュメント、設定ファイル、レビューコメント、障害対応記録などを材料にしてスキル化します。重要なのは一般論ではなく、あなたの環境固有の情報です。
実行しながら磨く
初稿のスキルは、ほぼ確実に調整が必要です。実タスクで回し、成功例も失敗例も含めて見直します。
最終出力だけでなく、実行トレースも見てください。無駄な試行が多いなら、手順が曖昧か、選択肢が多すぎる可能性があります。
コンテキストを節約する
SKILL.md に載せるべきなのは、エージェントが素の状態では知らない情報です。
- プロジェクト固有の規約
- ドメイン固有の手順
- 非自明なエッジケース
- 使うべきツールや API の明示
不要なのは、一般的な背景説明です。
一貫した単位で切る
スキルの粒度は関数設計に近いです。狭すぎると複数スキルを同時に読む必要が出て、広すぎると発火精度が落ちます。
大きい内容は分割する
毎回不要な詳細情報は references/ に逃がし、いつそのファイルを読むかを本文で指定します。
Read `references/api-errors.md` if the API returns a non-200 status code.
制御の強さを調整する
複数の進め方が許容される部分では自由度を持たせ、順番やコマンドが重要な箇所だけ厳密にします。
メニューではなくデフォルトを示す
複数案を横並びで出すより、まず標準手段を 1 つ示し、例外時だけ代替案を書く方が安定します。
宣言より手順を書く
特定ケースの答えそのものより、どう考えて進めるかの手順を書く方が再利用性があります。
効果的なパターン
Gotchas
Agent が自然には気づけない落とし穴を置きます。
## Gotchas
- `users` テーブルは soft delete を使うので `deleted_at IS NULL` が必要
- 認証系の `uid` と課金系の `accountId` は同じ値を指す
出力テンプレート
出力形式が重要なら、文章で説明するよりテンプレートを提示します。
チェックリストと検証ループ
多段ワークフローでは、進捗チェックと再検証の手順を明示すると安定します。
次のステップ