trim-agent-doc

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の呼び出し方、設定ファイルの構造、独自ヘルパーの使い方など）。これは「知識」であって冗長ではない
• 判断に効く理由 — 「なぜそうするのか」がエージェントの選択を変えるもの。例:「指定しないと結果の順序が保証されない」「定義側を変更したときに不整合を検出できる」。逆に、結論を繰り返すだけの理由は削ってよい
• プロジェクト固有の制約・慣習 — 一般論では導けない、このリポジトリ特有のルール

判断に迷ったら残す。「これは自明だから消す」と「これは知識だから残す」の線引きが、このスキルの核心です。

進め方

1. 対象ファイルを Read する。行数上限の指定があれば把握する（例: 200行以内）
2. セクションごとに「削れる冗長／残す情報」を仕分けする
3. Edit で順に簡潔化する。NG/推奨の重複を畳む、箇条書きの理由を本文化する、自明な前置きを消す
4. wc -l で行数を確認する。上限指定があれば収まっているか検証する
5. 完了報告では、何を削り・何を意図的に残したか（とその理由）を必ず伝える。ユーザーが情報の欠落を心配せずに済むようにするため

行数上限への対応

• ユーザーが「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 ヘルパーの呼び出し方）は残しています。