writing-skills (obra/superpowers)

レビュー

専用の Windows テスト PC 上で Codex CLI 0.166（gpt-6-astra、低推論）、実行ごとに新規の一時プロジェクトと一時 HOME/TMPDIR/キャッシュを使用、スキルをインストール（スキルあり群）、スキルなし（対照群）、またはスキルの中核要件をプロンプト末尾に付けた一文に圧縮（一文プロンプト群）、タスクごとに各群 2 実行、ネットワーク無効、/tmp への書き込みはブロック。プロンプトはスキル名に一切言及しません（以下で注記する表現を除く）。3 つのタスク：4 つのルールからコミットメッセージ用スキルを作成、肥大化した AGENTS.md を本質を失わずに削減、バグトリアージ用スキルの作成（S1/S2/S3 と「不足している再現手順を先に尋ねる」）。対照群にはタスクのみを与えます。一文プロンプトは、説明ルール、短い SKILL.md、1 つの具体的な例を述べる一文を追加します。

3群の比較

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

判定：状況次第（17.6 / 30）。 出典：obra/superpowers、skills/writing-skills、コミット 2ce8aa1 に固定。インストール：npx skills@latest add obra/superpowers --skill writing-skills。ライセンス： MIT（リポジトリの LICENSE）。

概要

obra/superpowers の writing-skills スキル：エージェントスキルを書くためのガイドで、テスト駆動の書き方（失敗をベースライン化し、最小限のスキルを書き、抜け穴を塞ぐ）を中心にしています。frontmatter の説明文（トリガー条件のみ、'Use when' で始める、ワークフローを要約しない）、ファイル構造、トークン効率、相互参照に関するルールを定めます。render-graphs.js ヘルパーと長い参照ファイルが同梱されています。

テスト方法

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

3 つのタスク：4 つのルールからコミットメッセージのスキルを書く、肥大化した AGENTS.md を要点を失わずに絞る、バグトリアージのスキルを書く（S1/S2/S3 と「まず欠けている再現手順を尋ねる」）。対照群にはタスクだけを与えます。一文プロンプトは、説明文のルール、短い SKILL.md、具体的な例 1 つを述べる一文を追加します。

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 群に与えた一文プロンプト："スキルの説明文には、いつ使うかだけを書く（トリガー条件、'Use when' で始め、約 400 文字未満、ワークフローは要約しない）。SKILL.md は短く命令形に保ち、かさばる参照は外に出し、説明ではなく具体的な例を 1 つ含める。"

平均スコア：スキルなし 4.43 vs スキルあり 4.88（差分 +0.45）。1 実行あたりのトークン：64k vs 163k（2.56 倍）。時間：34s vs 52s。一文プロンプト群：4.71（一文プロンプトに対するスキルの上乗せ：+0.17。一文プロンプト自身のスキルなしに対する上乗せ：+0.29）。一文プロンプトのトークンは 1 実行あたり 66k、つまりスキルのコストは一文プロンプトの 2.45 倍。

何が起きたか

• スキルあり 4.88、一文プロンプト 4.71、対照群 4.43（各 n=6）。効果は説明文にあります：対照群の説明文はワークフローを要約し（「欠けている再現手順を要求し、重大度を S1、S2、S3 に分類してバグ報告をトリアージする」）、これはスキルが警告するアンチパターンです。対照群の 2 つのバグトリアージスキルは品質チェック（「いつ使うか」の表現と具体的な例）で 5/7 でした。スキル群と一文プロンプト群は 'Use when ...' の説明文を書き、トリアージとコミットメッセージの 4 実行すべてで 7/7 を記録しました。
• コスト：スキルは 1 実行あたり 163k トークン（対照群 64k、一文プロンプト 66k、2.5 倍）。コミットスキルのタスクでは、スキルありの 2 実行が長い参照ファイルを読むのに 243〜255k トークン（トリアージでは最大 229k）を費やしました。スキルとは無関係の AGENTS.md 絞り込みタスクでは 68〜85k でした。
• コミットメッセージのスキルでは、対照群は両方の実行で「理由を説明し、72 文字で折り返す」ルールを省きました（4 ルール中 3）。スキルありと一文プロンプトは 4 つすべてを維持しました。
• AGENTS.md の絞り込み（タスク 2）は全群で同じ 4.64 でした。ただし一文プロンプトの 1 実行が 3.64 でした（「マイグレーションは追記のみ」のルールを落とし、古いドキュメントへのポインタを残した）。ここではスキルが絞り込み後のファイルを良くすることはありませんでした。AGENTS.md に再掲された package.json コマンドを数えるチェックは 18 実行すべてで失敗するため、欠陥チェックとして無視しました。
• そのヘルパー（render-graphs.js、execFileSync 経由で dot を実行）は実行しませんでした。

評価項目別スコア

このテストの限界

• 生成された SKILL.md ファイル（frontmatter、説明文の表現、長さ）に対するルールベースのチェックとルールの再現。書いたスキルが実際にエージェントの振る舞いを変えるかはテストしておらず、これはスキル自身の手法が求めることです。
• 1 つのチェック（AGENTS.md 内の package.json コマンド）は欠陥があり、どこでも失敗します。
• セルごとに n=2。
• タスク・群ごとに n=2。約 1 ポイント未満の差はノイズです。
• ルールベースの採点はチェックが捉えられる範囲を測るもので、センスや、その結果が最善かどうかは判定できません。

セキュリティ

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

結論

トリガーで最も重要な 1 つのルール（何をするかではなく、いつ使うかを書く説明文）を教え、より整ったスキルファイルを生みます。ただしトークンは 2.5 倍で、一文でもそのほぼすべてが得られます。ガイドを読んでください。小さなスキル編集のたびに読み込む必要はありません。