| name | trim-agent-doc |
| description | ユーザーが指定したMarkdownドキュメントから、AIエージェントにとって自明・冗長な記述を削って簡潔にする。 |
| license | MIT |
| disable-model-invocation | true |
AIエージェント向けドキュメントの簡潔化
起動方法と引数
このスキルはユーザーが明示的にコマンド実行したときのみ動作します。引数として対象ドキュメントのパスを受け取る:
/trim-agent-doc doc/agent/models.md
/trim-agent-doc doc/agent/general.md 200行以内に
- 第1引数を対象ファイルのパスとして解釈する
- 続く語に「N行以内」などの行数上限が含まれていれば、それを制約として扱う
- 引数にパスが含まれていない場合は、対象ファイルをユーザーに確認してから進める
このスキルの目的
AIエージェント向けの開発ガイドラインや指示書は、書き足されるうちに冗長になりがちです。人間向けドキュメントなら丁寧な反復説明が親切ですが、読み手が高い理解力を持つAIエージェントの場合、自明な説明や同じことの言い換えは context を圧迫するだけで価値を生みません。
このスキルは、情報(=エージェントの判断や実装に効く内容)を一切失わずに、冗長な表現だけを削るためのものです。ユーザーが指定したドキュメントを対象に作業します。
基本方針
簡潔化は「内容を削る」のではなく「同じ内容をより少ない語数で表す」作業だと考えてください。判断基準は一つ — その記述を消したとき、エージェントの振る舞いが変わるか? 変わらないなら冗長、変わるなら情報です。
セクション見出しやコマンド名・固有名詞的なテキストは書き換えない。表現の短縮は本文・箇条書きの本体に限る。
削ってよいもの(冗長)
- NG例と推奨例の両方が並ぶ箇所 — 多くの場合どちらか一方で足りる。特にNG例が「言われなくてもやらない」レベルなら削る。推奨例だけ残すのが基本
- 「利点」「メリット」の箇条書き — 結論(何をすべきか)が明確なら、その理由を3点も列挙する必要はない。本文に1行で吸収するか、判断に効かないものは消す
- 当たり前すぎる前置き・説明文 — 「〜することが重要です」「以下に説明します」のような中身のない文
- エージェントには自明なアンチパターンのコード例 — エージェントが既に知っていて避けるものを「悪い例」としてわざわざ実演しているもの
残すもの(情報)
削りすぎは簡潔化ではなく劣化です。次のものは自明に見えても残す:
- 「やり方」を示す具体的なコード例 — そのプロジェクト固有の書き方(推奨APIの呼び出し方、設定ファイルの構造、独自ヘルパーの使い方など)。これは「知識」であって冗長ではない
- 判断に効く理由 — 「なぜそうするのか」がエージェントの選択を変えるもの。例:「指定しないと結果の順序が保証されない」「定義側を変更したときに不整合を検出できる」。逆に、結論を繰り返すだけの理由は削ってよい
- プロジェクト固有の制約・慣習 — 一般論では導けない、このリポジトリ特有のルール
判断に迷ったら残す。「これは自明だから消す」と「これは知識だから残す」の線引きが、このスキルの核心です。
進め方
- 対象ファイルを Read する。行数上限の指定があれば把握する(例: 200行以内)
- セクションごとに「削れる冗長/残す情報」を仕分けする
- Edit で順に簡潔化する。NG/推奨の重複を畳む、箇条書きの理由を本文化する、自明な前置きを消す
wc -l で行数を確認する。上限指定があれば収まっているか検証する
- 完了報告では、何を削り・何を意図的に残したか(とその理由)を必ず伝える。ユーザーが情報の欠落を心配せずに済むようにするため
行数上限への対応
- ユーザーが「N行以内」と指定したら、それを満たすまで簡潔化する
- 指定がなければ行数目標は設けず、冗長さの削減だけを行う
- もし冗長な部分をすべて削っても上限に収まらない場合は、情報を削って無理に詰め込まず、その旨をユーザーに伝える。「これ以上は情報を失う」というラインを越えないことが、削減ノルマより優先される
簡潔化の例
Before(NG/推奨の両方+理由3点で約18行):
### 外部APIの呼び出しにはリトライを入れる
外部APIを呼び出すときはリトライ処理を入れる必要があります。
**NG例**(リトライなしで一度きり呼び出す):
\```
result = call_external_api()
\```
**理由**:
- ネットワークは一時的に失敗することがある
- リトライがないとエラーになりやすい
- 安定性が向上する
**推奨**:
\```
result = with_retry(max_attempts: 3) { call_external_api() }
\```
After(結論+プロジェクト固有のやり方のみ、1段落):
外部APIの呼び出しは `with_retry(max_attempts: 3) { ... }` で囲む。一時的なネットワーク障害を吸収するため。
NG例(自明)と利点の列挙(結論の繰り返し)を削り、「やり方」(このプロジェクトの with_retry ヘルパーの呼び出し方)は残しています。