writing-for-agents (mattpocock/skills)

レビュー

専用の Windows テスト PC 上で Codex CLI 0.166（gpt-6-astra、低推論）、実行ごとに新規の一時プロジェクトと一時 HOME/TMPDIR/キャッシュを使用、スキルをインストール（スキルあり群）、スキルなし（対照群）、またはスキルの中核要件をプロンプト末尾に付けた一文に圧縮（一文プロンプト群）、タスクごとに各群 2 実行、ネットワーク無効、/tmp への書き込みはブロック。プロンプトはスキル名に一切言及しません（以下で注記する表現を除く）。writing-skills と同じ 3 つのタスク：4 つのルールからコミットメッセージ用スキルを作成、肥大化した AGENTS.md を本質を失わずに削減（水増し、重複、古い参照に埋もれた本物のルール 5 件）、バグトリアージ用スキルの作成。対照群にはタスクのみを与えます。一文プロンプトはスキルの主要ルールを一文で与えます。生成された SKILL.md ファイルは、writing-skills と同じ 7 項目のチェックリストで採点され、そこでは「Use when ...」形式の説明が求められます。このスキル自身のアドバイスは「trigger first」であり、その字句通りではありません。

3群の比較

Codex CLI で 18 実行を計測し、LLM 判定なしのルールベースのチェックで採点。合計 24.9 / 30、判定は 状況次第。

判定：状況次第（24.9 / 30）。 出典：mattpocock/skills、skills/productivity/writing-for-agents、コミット 4ae2317 に固定。インストール：npx skills@latest add mattpocock/skills --skill writing-for-agents。ライセンス： MIT（リポジトリの LICENSE）。

概要

writing-for-agents スキル（mattpocock/skills）：エージェントが読む指示を書くためのガイダンスです。説明ではトリガーを最初に置き、区別すべき分岐ごとに 1 つのトリガーを持たせる、各意味を単一の真実の源に保つ、モデルがすでに従っている無意味な指示や環境を言い換えるだけの行（スクリプト、設定）を削除する、各ステップを検証可能な完了基準で終える、ファイルを短く保つ。

テスト方法

専用の Windows テスト PC 上で Codex CLI 0.166（gpt-6-astra、低推論）、実行ごとに新規の一時プロジェクトと一時 HOME/TMPDIR/キャッシュを使用、スキルをインストール（スキルあり群）、スキルなし（対照群）、またはスキルの中核要件をプロンプト末尾に付けた一文に圧縮（一文プロンプト群）、タスクごとに各群 2 実行、ネットワーク無効、/tmp への書き込みはブロック。プロンプトはスキル名に一切言及しません（以下で注記する表現を除く）。

writing-skills と同じ 3 つのタスク：4 つのルールからコミットメッセージスキルを書く、肥大化した AGENTS.md を本質を失わずに引き締める（埋もれた 5 つの実ルール、水増し、重複、古いポインタ）、バグトリアージスキルを書く。対照群にはタスクだけが与えられます。一文プロンプトはスキルの主要ルールを 1 文で与えます。生成された SKILL.md ファイルは writing-skills と同じ 7 点チェックリストで採点され、これは「Use when ...」形式の説明を期待します。このスキル自身の助言は「トリガーを先に」であり、その文字通りの表現ではありません。

1. コミットメッセージスキルの作成 — skills/commit-writer/SKILL.md にスキル（SKILL.md）を書いてください。コーディングエージェントに以下のルールでコミットメッセージを書かせるものです：件名は命令形で、50 文字未満、末尾のピリオドなし。次に空行を挟み、本文は 72 文字で折り返し…
2. AGENTS.md の引き締め — AGENTS.md は誰も読まなくなるほど肥大化しました。エージェントが実際に必要とするものを失わずに、できる限り短くなるようその場で書き直してください。
3. バグトリアージスキルの作成 — skills/bug-triage/SKILL.md にスキル（SKILL.md）を書いてください。エージェントが入ってくるバグ報告を S1（データ損失または停止）、S2（主要機能が壊れているが回避策がある）、S3（軽微または見た目）に分類し、不足している再現手順を尋ねる…

採点はプログラム的（隠しテスト／仕込み問題の検出／制約チェック／該当する場合はレンダリング+OCR）で、実行ごとに 0〜5 点。スコアはどの LLM 判定者も決めていません。

結果

第 3 群に与えた一文プロンプト：「エージェント向けに書く：説明ではトリガーを先頭に置き、区別すべき分岐ごとに 1 つのトリガーを持たせる。各意味を単一の真実の源に保つ。モデルがすでに従っている無意味な指示や、環境を言い換えるだけの行（スクリプト、設定）は削除する。各ステップを検証可能な完了基準で終え、ファイルは短く保つ。」

平均スコア：スキルなし 4.17 に対しスキルあり 4.52（差 +0.35）。1実行あたりのトークン：70k 対 88k（1.27x）。時間：39s 対 37s。一文プロンプト群：4.63（一文プロンプトに対するスキルの上積み：-0.11。一文プロンプト自身のスキルなしに対する上積み：+0.46）。一文プロンプトのトークンは 1実行あたり 76k なので、スキルは一文プロンプトの 1.17 倍のコストになります。

何が起きたか

• 平均：スキル 4.52、一文プロンプト 4.63、対照群 4.17（各 n=6）。明確な勝ちは AGENTS.md タスクです：スキルは両実行とも 5.00（5 つの必須ルールをすべて保持、水増しを削除、古いポインタを修正、重複を統合）で、対照群 4.29、一文プロンプト 4.71 を上回りました。一文プロンプトの両実行は引き締め中に「マイグレーションは追記のみ」ルールを削除しましたが、スキルの実行はそれを保持しました。
• 2 つのスキル作成タスクでは、スキルは対照群を上回りません（4.18〜4.59 対 4.06〜4.18）：それらのタスクの 4 つのスキルあり実行すべてで、説明はワークフローの要約であるか、いつスキルを使うかを述べていませんでした（'Triage incoming bug reports by requesting missing reproduction steps and classifying severity...'、対照群と同一）。そのため 7 点チェックリストは対照群と同じく 5/7 か 6/7 になりました。一文プロンプトの実行はトリガー形式の説明を書きました（'When an incoming bug report lacks reproduction steps, request them first...'）。
• 対照群はコミットスキルの両実行で「本文は 72 で折り返し、理由を説明する」ルールを省きました（4 ルール中 3）。スキルと一文プロンプトは 4 つすべてを保持しました。
• コスト：スキルは 1実行あたり 88k トークン。対照群 70k、一文プロンプト 76k（1.26x、1.16x）。スキルあり群の実行は 1実行あたり 4 ファイルをプロジェクトにコピーします。
• AGENTS.md 内で言い換えられた package.json スクリプトを数えるチェックは、ここでは対照群の 2 実行だけで不合格になりました（3 件一致）。スキルの「環境を言い換えない」ルールと整合的です。

評価項目スコア

このテストの限界

• ルールベースのチェックで、一部は writing-skills テストから借用。7 点のスキルチェックリストは、このスキルが要求しない「Use when」表現を評価するため、2 つのスキル作成タスクでこのスキルを過小評価します。
• 書かれたスキルや引き締められた AGENTS.md が実際にエージェントの挙動を変えるかは誰もテストしていません。
• セルごとに n=2。
• タスクごとに各群 n=2。約 1 点未満の差はノイズです。
• ルールベースの採点はチェックが見られるものだけを測ります。好みや、結果が可能な限り最善かどうかは判断できません。

セキュリティ

security.md を参照。スキャン：CRITICAL 0 / HIGH 0 / MEDIUM 0。判定：実行しても安全（ネットワーク無効のサンドボックス）。クリーンなスキャン結果はスキルの安全性を証明しません。

結論

指示ファイルの圧縮には価値があります（一文プロンプトが落とした実ルールをすべて保持しました）。それ以外、新しいスキルを書くことではベースモデルを上回らず、トークンは 1.26x です。