skill-cleaner

スキルの整理

単一のスキルに絞って編集を行います。目指すのは、人間にとっても、それを実行するエージェントにとっても読みやすく、流れがよく、互いに矛盾する指示がないバージョンです。同時に、十分な詳しさを保ち、あらゆる振る舞いを損なわないようにします。多くの場合、文章量は減りますが、必ずしもそうとは限りません。本当に重要な情報を含むために長くなっているスキルは、そのままの長さを保つべきです。敵なのは長さではなく、混乱です。冗長な箇所を引き締め、順序が不自然な構成を直し、セクション間で競合する指示を調整することは、すべてこの目標にかなっています。行数を純粋に減らすことは副次的な結果であり、目的ではありません。

スキルには時間とともに内容が積み重なっていきます。問題が起こるたびに一文が追加され、修正のたびに但し書きが増え、新たな例外が加わるたびに段落が増えます。こうした積み重ねを繰り返すうちに、スキルはモデルが作業メモリーにすべてを保持できる範囲を超え、皮肉にも元の草稿よりも正しく実行されなくなります。このスキルはその歯止めとなるものです。すべての行について「今も役割を果たしているか」と問いかける、誠実な見直しを行います。

積み重ねは矛盾も生み出します。後半の手順に追加された修正が、前半の手順向けに書かれたルールとひそかに競合したり、「スキル X を参照／手順 Y を参照」という指示が、そこへ導いた指示を損なう内容へ誘導したりすることがあります。こうした欠陥は、残しておくと最も大きな問題になります。どの指示を優先すべきかエージェントが判断できず、推測することになり、その推測がそのまま提供されるからです。こうした問題を見つけて解決することは、余分な記述を削るのと同じくらい重要です。

このスキルが対象としないこと

• 文体の刷新ではありません。 異なる文体を押し付けたり、新しい慣例を導入したり、違う印象にするためだけに文章を書き換えたりしないでください。ユーザーの語り口はそのまま保ちます。構成の変更は対象に含まれますが、実際の問題を解決する場合に限ります。たとえば、前提条件の説明が遅すぎる場合に順序を入れ替える、重複または矛盾するセクションを統合する、不自然なつなぎを滑らかにする、といった変更です。判断基準は、好みではなく、実際の読みやすさや一貫性の問題を解決するために構成を変更することです。
• 機能変更ではありません。 新しい指示を追加したり、スキルの対象範囲を広げたり狭めたり、見つけたワークフロー上の問題（単に誤っている指示）を修正したりしないでください。そうした問題はレポートに記載してください。既存の2つの指示の矛盾を解決することは別であり、対象に含まれます。スキルの動作を変えるのではなく、対立する2つの内容を1つにまとめるためです。正しい解決策が本当に不明確な場合（どちらの指示にも意図があるように見える場合）は、推測しないでください。スキルの目的に沿う解釈を選び、ユーザーが確認できるようレポートに記載してください。
• 過度な編集ではありません。 判断に迷ったら、その行を残してください。過剰に削った場合の代償（数か月後に誰も原因を追えない回帰）は、少し冗長な段落を残す代償よりはるかに大きいものです。

入力

ユーザー（または呼び出し元のスキル）が対象スキルを指定します。通常はパス（skills/<name>/SKILL.md）または短い名前（ship、ticket など）で指定します。短い名前のみが指定された場合は、リポジトリのルートにある skills/ の下から探します。複数のスキルが指定された場合は、1つずつ整理し、スキルごとにレポートを1つ作成します。

対象が .agents/skills/ または .claude/skills/ にある場合は、作業を止めてユーザーに伝えてください。これらは npx skills update でインストールされた外部のメタスキルであり、編集しても次回の更新時に上書きされます。対象範囲外です。

セルフクリーンアップはサポートされており、想定されています。 skills/skill-cleaner/SKILL.md は、ユーザー所有の他のスキルと同じように有効な対象です。ユーザーから自分自身の整理を依頼された場合、または skill-improver のクリーンアップモード（skill-improver のステップ 4b を参照）でこのスキルが候補に選ばれた場合は、同じワークフローを実行してください。注意点は、指示を読んでいるファイル自体を編集することです。最初の編集を行う前にファイル全体をコンテキストに読み込み、編集が数回を超える場合は、該当セクションを再読してください。それ以外の手順は同じです。ステップ 0 も引き続き適用されます（skill-creator を参照）。同じ削減・維持の基準を適用し、レポートも同様にユーザー（または呼び出し元）に返します。セルフクリーンアップは特に効果が大きい作業です。リポジトリ内の他のすべてのスキルがこの基準に基づいて評価されるため、このスキル自体を簡潔に保つことが、今後のあらゆるクリーンアップに直接影響します。

作業手順

ステップ 0 — skill-creator に照らして「良い状態」の基準を確認する

対象スキルを評価する前に、.agents/skills/skill-creator/SKILL.md を読みます。特に「Skill Writing Guide」と「Writing Style」のセクションを確認してください。これは、このリポジトリのスキルが従うべきスタイルです。指示の背後にある 理由 を説明し、MUST／NEVER の羅列を避け、プロンプトを簡潔に保ち、強い制約を課すよりも見方を変える表現を優先し、大規模な参照ファイルには段階的な開示を用います。これらの原則こそ、ここで適用する基準です。最新の内容を把握していないと、詰め込みに見える理由の説明まで削りすぎたり、「権威がありそう」という理由で MUST の羅列をそのまま残したりしてしまいます。

このリポジトリに .agents/skills/skill-creator/ がない場合は、ユーザーが説明するスタイルを基準にします。ただし、レポートには、公式の参照資料なしで作業したことを明記してください。

ステップ 1 — スキル全体を読む

SKILL.md を最初から最後まで読み、そこから参照されている scripts/、references/、assets/ も確認します。スキル本体と補助ファイルに書かれている内容を把握しないと、段落が冗長かどうか判断できません。次の点に注意してください。

• フロントマターの description は、スキルの起動条件を決める重要な情報であり、短縮すべきでないことがほとんどです。
• 他のスキル、スクリプト、ファイルへの相互参照は、参照先が引き続き機能するよう維持する必要があります。
• 必要に応じて、スキルのコミット履歴（git log -p -- skills/<name>/SKILL.md）を確認します。最近追加された内容は、特定の問題への予防策であることが多く、その背景にある 理由 を削らないようにしてください。

ステップ 2 — クリーンアップ基準に照らして各セクションを分類する

スキルの各部分を確認し、どのような見立てになるか考えます。以下の分類を参考にしてください。内容を記録しますが、まだ変更は加えません。 削除・短縮の候補（通常は安全に削除または短縮できます）：

• 完全な重複。 同じ指示が2か所に書かれています。最も自然な位置にある方を残し、もう一方を削除します。
• 自明な内容の言い換え。 次の段落ですでに説明されていることや、適切な見出しがすでに伝えている内容を改めて説明する文です。
• 過剰な防御的記述。 MUST／NEVER／ALWAYS を重ねる代わりに、「理由」を添えた1文で同じ効果が得られます。（skill-creator の文体ガイドを参照してください。強引な MUST の多用は注意のサインです。）
• 冗長な語調。 「注目すべき点として……」「ご注意ください……」「前述のとおり……」「一般に……」などや、新しい情報を加えない締めくくりの要約段落です。
• 形骸化した例外ケース。 ほとんど起きず、誤った対処による影響も小さいシナリオについて、段落全体を割いています。例外ケースがまれでも、データ損失や force push など深刻な結果につながる場合は残してください。
• 必要性の低い例。 前の説明を繰り返すだけで、説明だけでは伝えられない内容を示していない例です。（説明だけでは伝えにくい複雑なケースを示す例は価値があるため、残してください。）
• 古くなった参照先。 すでに存在しない、または移動したファイル、スクリプト、外部システムへの参照です。

矛盾と流れの問題（見つけて修正する価値が最も高い項目です）：

• 指示の矛盾。 あるセクションで X をするよう指示し、別のセクションで禁止していたり、反対の意味に受け取れる内容になっていたりします。どちらの指示を優先すべきかエージェントが判断できず、推測することになります。正しいルールを特定し、該当するすべての箇所に適用して、すべての記述を一致させてください。2つの指示が本当に異なる状況に適用される場合は、両方の箇所でその境界を明確に示してください（例：「スタックが未送信の間は X を実行します。送信後は決して X を実行しません」）。適用範囲が示されていないと、実際には矛盾していなくても、矛盾しているように読めます。
• 誤解を招く参照先。 「X スキルを参照」や「ステップ Y を参照」という案内先が、案内元の指示と矛盾したり、それを弱めたりしています。参照先を修正するか、案内箇所で明示的に上書きし、読者が相反する指示を受け取らないようにしてください。
• 同じ指示の不一致な記述。 単なる重複ではなく、細部が実際に異なる2つの指示です。正しい方を選び、両方を一致させてください。記述の不一致は、気づかれないまま矛盾につながります。
• 順序の問題。 前提条件が、それを必要とする手順より後に示されていたり、後で定義される内容を先に参照していたり、セクション間のつながりが唐突だったりします。並べ替えるか、1文のつなぎを加えて、上から順に自然に読めるようにしてください。

再構成の候補 — ここでは構成を大きく変更してかまいません。スキルを読みやすく、またはエージェントが実行しやすくするために役立つなら、セクションの移動や統合、分割も対象です。既知の流れの問題を、現状の順序を保つためだけに放置しないでください。次の点を確認してください。

• 参照または必要とされるセクションが、その箇所より後にある — 読者が実際に必要とする順序で読めるよう、前に移動します。
• それに依存する手順より後に、設定、前提条件、コンテキストが置かれている。
• 関連する内容を扱う2つのセクションは、統合した方が読みやすい。または、1つのセクションに実際には2つのテーマが含まれており、分割した方が読みやすい。
• 長く一様なリストに、実際には自然な分類が2つある。
• 読者やエージェントが、情報が必要になるまで複数のセクションにわたって記憶しておかなければならない順序になっている — 各情報が使われる箇所に配置されるよう、順序を入れ替えます。

読みやすさや実行順序が明らかに改善する場合は、移動してください。その際、次の2点を守ってください。すべての相互参照が引き続き機能するようにします（「ステップ N を参照」や名前で参照されているセクションが、移動後も正しく参照できるよう、必要に応じて参照元と参照先の両方を修正します）。また、単なる好みではなく、読解や理解が実際に改善する場合に限って順序を変更してください。すでに問題のないセクションをただ並べ替えるだけでは、無駄な変更になります。 変更してはいけないもの：

• frontmatter の name: フィールド。
• description: フィールド。ただし、明らかに誤っている場合や古い参照が含まれている場合は除きます。トリガーの正確さはここにかかっており、短くすると通常はトリガーの精度が下がり、上がることはありません。
• 「なぜ」という説明。段落で指示が重要な理由を説明している場合は、そのまま残してください。これは、モデルがパターンマッチングに頼らず、エッジケースに対処するための重要な背景情報です。
• 破壊的または取り消せない操作（強制プッシュ、ハードリセット、作業内容の削除、外部へのメッセージ送信）を許可するもの。
• 既知の過去の失敗に対処するもの。通常はコミットメッセージ（「fix: X に対するガードを追加」）や説明文（「X をしてはいけません。前回それが原因で Y が起きました」）で確認できます。
• トリガーに役立つ、説明フィールド内の具体例。

ステップ 3 — 編集する

トリミング内容を SKILL.md（該当する場合はバンドルされたファイルも）に直接反映します。Write ではなく Edit ツールを使い、変更対象以外はすべて保持してください。

編集時のガイドライン：

• 削除よりも簡潔化を優先してください。6 行の段落を削除するより、2 行に書き直すほうが意図を多く保てます。
• 同じ文体を維持してください。スキルが命令形（「プーラーを実行します。出力を読みます。」）を使っているなら、説明的な文体（「プーラーが実行され、その後出力が読まれます。」）に書き換えないでください。
• 不確かなトリミングがある場合は、複数のトリミングを 1 回の Edit にまとめないでください。小さく個別に編集するほうが、確認や取り消しが簡単です。
• 編集のたびに、そのセクションを読み直してください。文を削除した結果、次の段落に「つまり……」だけが残ることがあります。

ステップ 4 — 最終確認

報告する前に差分を確認し、次の点を確認します。

1. 元のスキルの各指示が引き続き残っているか、意図的にトリミングされていて（レポートに記載されているか）。
2. 内部参照が壊れていないか（参照先のセクション名が残っているか、他の箇所で参照されているステップ番号を振り直していないか、移動した項目が参照元すべてから引き続き正しく参照できるか）。
3. frontmatter がそのまま保たれているか。
4. スキルを最初から最後まで読んで、流れに不自然な点がないか。「ステップ 4 で説明したように」とあるのに、そのセクションが削除されている、といったことがないか。

問題があれば、レポートを書く前に修正してください。

レポート

編集後にレポートを作成してください。簡潔でありながら具体的にし、ユーザーがざっと目を通すだけで異議のある箇所を見つけ、元に戻せるようにしてください。次の形式を使います。

## Cleaned: skills/<name>/SKILL.md

**Reads better because:** <one-line summary of the net effect on flow, clarity, and consistency — this is the headline>
**Size:** <before> → <after> words/lines (secondary — note it, don't lead with it; "no net reduction, and that's fine" is a valid line)

### Conflicts resolved
- <the contradiction or astray-pointer you found, with the two sections involved> — <how you reconciled it, and which rule won>
(omit this section entirely if none were found)

### What got tightened
- <one-line description of the change> — <one-line why>
- ...

### What got removed
- <what was cut, with a short verbatim snippet or section name> — <why it wasn't pulling its weight>
- ...
(omit this section entirely if nothing was removed)

### What got restructured
- <what moved or merged> — <why it reads better this way>
(omit this section entirely if nothing was restructured)

### Left alone on purpose
- <anything you considered trimming but decided to keep> — <why>
(use this for non-obvious calls — don't list every untouched paragraph; the point is to show the user where you exercised restraint so they trust the calls you did make)

### Notes
- <anything you noticed but didn't act on — e.g. a workflow bug, an outdated reference, a section that might be a candidate for promotion to a separate skill>
(omit if nothing to flag)

「意図的に残したもの」セクションは、信頼を築くうえでレポートの最も重要な部分です。安全確認の理由を説明しているために段落を削除せずに残した場合は、そのことを記載してください。そうすることで、単なる機械的な文字数削減ではなく、注意深く読み、意図的に判断したことがユーザーに伝わります。

別のスキルから呼び出された場合

skill-improver（または他の自動化）から呼び出され、人間から直接呼び出されたのではない場合：

• 同じワークフローとレポートを使います。レポートは、呼び出し元が出力するもの（例：PR の本文）に含めるため、呼び出し元に返します。
• 自分でコミット、ブランチ作成、PR の作成をしないでください。周辺のワークフローを管理し、この整理が他の編集とどう関係するかを把握しているのは呼び出し元です。
• 意味のある整理対象がないと判断した場合は、レポートにその旨を明記してください（「変更なし — スキルはすでに簡潔です」）。呼び出し元が曖昧さなく判断できるようにする必要があります。

調整

良い実行では、通常、次のようになります。

• セクション間の矛盾が解消され、スキルを上から下までよりスムーズに読めるようになります。行数ではなく、これが主な評価基準です。
• 情報を損なわずにできる場合は冗長な箇所を簡潔にし、情報量の多いセクションはそのまま十分な長さに保ちます。
• 変更の大半は小規模で独立したものにしつつ、スキルをより明確に読める、または実行できるようになる場合は、セクションを自由に移動、統合、分割します。
• スキルの意図、語り口、発動条件は変えません。

悪い実行では、次のようになります。

• スキルに必要な情報を削って行数を減らそうとします。長さを短くすることは、そもそも目標ではありません。
• 余計なものに見えるという理由で、「なぜ」の説明を削除します。
• 「より簡潔にする」ために説明フィールドの具体性を取り除き、発動性を損ないます。
• すでに問題のないセクションを並べ替えたり、再構成すること自体を目的にしたりします。
• スキルならすでに理解しているはずだという理由で、安全策を取り除きます。
• 矛盾の解消は「機能変更」に思えるという理由で、実際の矛盾を放置します。矛盾する指示の整合は整理作業であり、対象範囲に含まれます。
• 変更ごとの理由を示さず、行数だけを列挙したレポートを作成します。

対象のスキルに本当に問題がなければ、それも実行の成功です。その旨を伝えて終了してください。