agentleFS
k3forxk3forx/skills/summarize-go-issue/SKILL.md

summarize-go-issue

Skill1 starsChanged 4 months agoApache-2.0View on GitHub

Go (またはGoエコシステム) のGitHub Issue URLを受け取り、issue本文・全コメント・関連PR/Issueを `gh` CLIで取得して、導入の背景・目的・解消方法・議論点・ドラフト実装を日本語でまとめた HTML を作成・保存する。「このissueまとめて」「Goのissue要約して」「golang/go の #NNN を読んで」「proposalを整理して」のようなリクエスト、または `github.com/*/issues/NNN` URL が含まれるプロンプト(特に golang/go やGo関連リポジトリ)で必ず起動する。「詳しく」「深掘り」「噛み砕いて」「初学者向け」「丁寧に」などの語が一緒に指定された場合は deep モードで起動し、議論のタイムライン・用語集・初学者向け補足を追加する。学習・あとから見返すための個人メモ用。

  • Installs packages

The file

Files
SKILL.md

Go Issue要約スキル

Go言語(golang/go)やGoエコシステムのリポジトリの GitHub Issue を読み、学習用に構造化された日本語サマリーをHTMLで保存する。issueは長大なproposal議論になりがちなので、本文だけでなくコメント欄の議論の流れとドラフト実装(提案されているコード例)まで抜き出す。

入力

ユーザー入力: $ARGUMENTS

  • GitHub Issue URL(例: https://github.com/golang/go/issues/12345)が必須。
  • URLが含まれていない場合は、以下を表示して終了:
    ❌ GitHub Issue の URL を指定してください。
    使い方: /summarize-go-issue <URL>
    例: /summarize-go-issue https://github.com/golang/go/issues/12345
  • 複数URLが渡された場合は1つずつ順番に処理する。
  • PR URL(/pull/NNN)が渡された場合は「このスキルは Issue 要約用です。PR要約用には別のスキルを使ってください」と表示して終了する(PRは扱わない)。

詳細モード (detail) の判定

URL とフラグの順序は不問。以下のいずれかに該当すれば detail=deep、それ以外は detail=standard (既存挙動と完全同一)。

  • $ARGUMENTS に --deep または --深掘り フラグが含まれる
  • URL 以外のユーザー発話に「深掘り」「詳しく」「噛み砕いて」「初学者向け」「丁寧に」のいずれかが含まれる

detail=deep のときのみ、後段の step 5.5 / 5.6 を実行し、HTML テンプレートに「用語集」(最上部・「概要」の前)・「議論のタイムライン」・「初学者向け補足」を追加する。standard モードでは現行の出力構造を完全に維持する。

実行フロー

0. 詳細モード判定

「詳細モード (detail) の判定」セクションに従って detail を standard か deep に決定する。決定値は step 5.5 / 5.6 / 6 / 7 で参照する。

1. URLをパース

URLから owner, repo, issue_number を抽出する。正規表現: https://github\.com/([^/]+)/([^/]+)/issues/(\d+)

2. 今日の日付を取得

Bash: date +%Y-%m-%d を実行してシステム日付を取得(会話コンテキストの日付ではなく実行時点の日付を使う)。

3. Issue本文とコメントを取得

gh CLI でissueとコメントを一括取得する:

gh issue view <URL> --json title,body,author,createdAt,updatedAt,labels,state,stateReason,number,url,comments,milestone,assignees,closedAt

取得失敗時(gh auth status が未認証、issueが非公開、404など)は以下を表示して終了:

❌ Issue の取得に失敗しました: {URL}
   原因: {gh のエラーメッセージ}

4. 関連issue/PRを収集

issue本文と全コメントのテキストから、以下のパターンを抽出する:

  • 同一リポジトリ参照: #(\d+)(例: #12345)
  • 絶対URL参照: https://github\.com/([^/]+)/([^/]+)/(issues|pull)/(\d+)
  • 他リポジトリ参照: ([\w-]+)/([\w-]+)#(\d+)(例: golang/tools#999)

重複を排除し、各参照について gh issue view <URL> --json title,state,url または gh pr view <URL> --json title,state,url でタイトルと状態を取得する(失敗したらスキップ、エラー時はリストから除外)。参照が20件を超える場合は「本文で言及されているもの」を優先し、コメントでの言及は件数上位10件に絞る。

5. コード例(ドラフト実装)を抽出

issue本文と全コメントから ```go / ```diff / ```shell などの言語指定つきコードブロックを抽出する。各コードブロックについて以下をメタデータとして保持:

  • 出典(issue本文 or コメント者とそのURL)
  • 言語タグ
  • コード内容
  • 直前・直後の2〜3文(「何のための提案か」の文脈)

言語タグなしのコードブロックでも、 func / package / import ( などのGoシンタックスらしきものが含まれていれば go 扱いとして抽出する。短すぎる(3行未満)コードはエラーメッセージや抜粋の可能性が高いのでスキップする。

5.5. 時系列イベントの抽出(detail=deep のときのみ)

コメント全体から「議論の転換点となったコメント」を 8〜15 件選び、{時刻 (YYYY-MM-DD), 著者 (@username), 一行サマリ (日本語), 種別} のリストにする。種別は次の 5 つから 1 つ選ぶ:

  • proposal(新提案・修正案の提示)
  • objection(反対・懸念表明)
  • agree(賛成・合意)
  • decision(採用・却下・延期などの結論)
  • note(補足・参考情報)

選定方針:

  • +1 / LGTM / 絵文字のみ、といった情報量の少ないコメントは除外
  • maintainer (Goチームメンバー、@ianlancetaylor, @rsc など) の発言、設計判断、提案の修正・撤回は優先採用
  • コメントが多い issue (50件超) では、上記方針で重要度上位 15 件までに絞る
  • 時系列順 (古い→新しい) で並べる

5.6. 用語集候補の抽出(detail=deep のときのみ)

issue 本文・コメントで 2 回以上出現し、かつ説明なしで使われている Go / 標準ライブラリ固有の語(関数名・型名・パッケージ名・仕様用語・コンセプト名)を抽出する。最大 8 語。

各語について次の優先順位で簡易説明を付ける:

  1. issue 本文・コメント内で説明されている: その説明を引用ベース(出典付き)でまとめる
  2. issue 内に説明がない場合: Go の公式仕様・標準ライブラリドキュメントから 1〜2 文の 事実ベース の補足を 補足: 明示で添える(推測・評価は禁止)

抽出対象になりやすい例: iota, unsafe.Pointer, runtime.GOMAXPROCS, errors.Is, ジェネリクス制約 (comparable), GC barriers, escape analysis などの用語。一般的すぎる語(func, package, error 単体など)はノイズになるので除外する。

6. HTMLを生成・保存

保存先: ~/Documents/go-issue-summaries/{YYYY-MM-DD}-{owner}-{repo}-{issue_number}/index.html

  • mkdir -p ~/Documents/go-issue-summaries/{YYYY-MM-DD}-{owner}-{repo}-{issue_number}/ を実行
  • 既存ディレクトリがあれば index.html を上書き
  • 「HTMLテンプレート」に従って生成

7. ユーザー向け出力

✅ Go Issue の要約を作成しました!
📝 [{owner}/{repo}#{issue_number}] {issue_title}
📁 ~/Documents/go-issue-summaries/{YYYY-MM-DD}-{owner}-{repo}-{issue_number}/
💬 コメント: {コメント数} 件 / 関連: {関連issue/PR数} 件 / コード例: {抽出したコード数} 個

detail=deep のときは最終行に以下を追加する:

🔍 詳細モード (タイムライン: {N}件 / 用語集: {M}語 / 初学者向け補足: {K}箇所)

該当セクションを省略した場合は件数 0 と表示する。

生成後に open コマンドでブラウザを開かないこと(ユーザーが自分で開く)。

要約の品質ガイドライン

要約の正確さと議論の全体像が最重要。以下に従うこと。

引用ベース

  • 要約は必ず issue 本文・コメントに書かれていることに基づいて書く。取得したテキストにない情報は書かない。
  • 特に重要な記述(問題提起、設計判断、代替案の却下理由など)は <blockquote> で直接引用し、「by @{username}」と出典を明記する。
  • 英語はすべて日本語に翻訳する。技術用語は初出時に原語を括弧で併記する(例: 「ジェネリクス(generics)」)。固有名詞(製品名、人名、企業名、関数名、型名)は原語のまま。

背景・目的セクションの書き方

「なぜこのissueが立てられたのか」「どんな問題を解こうとしているのか」を読み取る。typically issue本文の冒頭か「Problem」「Background」「Motivation」といった見出しに書かれている。

  • 現状どんな不便・不整合があるのか
  • ユースケース・使用例
  • 既存の回避策とその限界

解消方法・提案セクションの書き方

issue本文の「Proposal」「Proposed solution」「Suggested fix」部分を中心にまとめる。

  • 具体的にどう変更するか
  • API変更の場合、変更前後のシグネチャを対比
  • 既存機能との互換性への影響

議論点セクションの書き方

コメント欄の議論をテーマごとに整理する。時系列順に全コメントを列挙するのではなく、論点ごとにまとめて賛否両論を並べる。以下のような論点が典型:

  • 代替案(「こうした方が良いのでは」)
  • API設計の細部(命名、引数順、型)
  • 実装上の懸念(パフォーマンス、互換性、複雑さ)
  • ユースケースの妥当性(「この提案はX的なケースで困る」)
  • 却下された過去提案との比較

重要コメントは <blockquote> で引用+出典。maintainer(Goチームメンバー、 @ianlancetaylor @rsc など)のコメントは特に優先的に引用する。

コメントが200件を超える場合は「議論が長大なので主要論点のみ抜粋」と冒頭に明記する。全コメントの機械的な要約はしない。

ドラフト実装セクションの書き方

issue本文・コメントから抽出したコード例を <pre><code> で埋め込む。各コードブロックについて:

  • 「誰が提案したか」(本文 or コメント者名)
  • そのコードが何を示しているか(2-3文)
  • 出典へのリンク

コードは翻訳せずそのまま。コメント部分が英語でも原文のまま(技術的にはコードの一部なので)。

混入させてはいけないもの

  • issue/コメントに書かれていない背景知識や補足
  • issue内容に対するあなた自身の評価・意見
  • 推測で埋めた内容(「おそらく〜」)
  • Go言語の一般論的な解説(そのissue固有の議論でないもの)

detail=deep モードでの追加許容範囲

detail=deep のときに限り、上記の禁止事項を以下の範囲で部分的に緩める。引用ベース・推測禁止・意見禁止の三原則は引き続き厳守する。

  • 用語集セクション: issue 内に説明がない用語については、Go の公式仕様・標準ライブラリドキュメントを根拠とした 事実ベース の補足を 1〜2 文に限り許可する。文頭に 補足: を付けて出所が一般知識であることを明示し、推測語(「おそらく」「たぶん」「〜と思われる」)は使わない。
  • 初学者向け補足 (beginner-aid): 議論点セクションの各 <h3> 配下に、issue 内で言及された前提知識を初学者向けに再説明するブロックを追加できる。issue が触れていない一般論を新たに持ち込むことは禁止。あくまで issue 内の議論を読み解くのに必要な範囲に限る。
  • 議論のタイムライン: コメントの著者・時刻・一行サマリ・種別ラベルを並べるのみで、新規解釈・意見の追加は禁止。サマリは中立的な事実記述に留める。

不完全な情報の扱い

  • 参照先のタイトル取得が失敗した場合は「(取得失敗)」と書いて続行、リンクだけは残す
  • クローズされたissue/mergedされたPRもそのまま表示
  • 不明な項目は「不明」と書く。推測しない。

HTMLテンプレート

プレーンHTMLのみ(外部CSS/JSなし)。読みやすさのために最小限のインラインスタイルを使用する。

<!DOCTYPE html>
<html lang="ja">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>[{owner}/{repo}#{number}] {title} - 要約</title>
  <style>
    body { font-family: -apple-system, BlinkMacSystemFont, "Hiragino Sans", sans-serif; max-width: 860px; margin: 2rem auto; padding: 0 1rem; line-height: 1.8; color: #333; }
    h1 { border-bottom: 2px solid #333; padding-bottom: 0.5rem; font-size: 1.5rem; }
    h2 { margin-top: 2.5rem; color: #555; border-left: 4px solid #0066cc; padding-left: 0.6rem; }
    h3 { margin-top: 1.5rem; color: #444; }
    table { border-collapse: collapse; margin: 1rem 0; width: 100%; }
    th, td { border: 1px solid #ccc; padding: 0.5rem 1rem; text-align: left; vertical-align: top; }
    th { background: #f5f5f5; white-space: nowrap; }
    a { color: #0066cc; text-decoration: none; }
    a:hover { text-decoration: underline; }
    blockquote { border-left: 3px solid #ccc; margin: 1rem 0; padding: 0.5rem 1rem; color: #555; background: #fafafa; }
    blockquote .by { display: block; font-size: 0.85rem; color: #888; margin-top: 0.3rem; }
    ul { padding-left: 1.5rem; }
    .labels { display: inline-block; }
    .label { display: inline-block; background: #eef; color: #336; padding: 0.1rem 0.5rem; border-radius: 3px; font-size: 0.8rem; margin-right: 0.3rem; }
    .state-open { color: #22863a; font-weight: bold; }
    .state-closed { color: #cb2431; font-weight: bold; }
    pre { background: #f6f8fa; border: 1px solid #ddd; border-radius: 4px; padding: 0.8rem 1rem; overflow-x: auto; font-size: 0.88rem; line-height: 1.5; }
    code { font-family: "SF Mono", Menlo, Consolas, monospace; }
    p code { background: #f0f0f0; padding: 0.1rem 0.3rem; border-radius: 3px; }
    .code-meta { font-size: 0.85rem; color: #888; margin-top: -0.6rem; margin-bottom: 0.4rem; }
    .memo { border: 1px dashed #ccc; padding: 1rem; margin-top: 1rem; min-height: 100px; color: #999; }
    /* deep モード時のみ使用 */
    .timeline { border-left: 2px dashed #bbb; padding-left: 1rem; margin: 1rem 0; list-style: none; }
    .timeline-item { margin: 0.6rem 0; }
    .timeline-item .when { color: #888; font-size: 0.85rem; margin-right: 0.4rem; }
    .timeline-item .kind { display: inline-block; padding: 0 0.4rem; border-radius: 3px; font-size: 0.75rem; margin-right: 0.4rem; }
    .kind-proposal { background:#e0ecff; }
    .kind-objection { background:#ffe0e0; }
    .kind-agree { background:#e0ffe0; }
    .kind-decision { background:#ffe9c2; }
    .kind-note { background:#f0f0f0; }
    dl.glossary dt { font-weight: bold; margin-top: 0.6rem; }
    dl.glossary dd { margin-left: 1.2rem; color: #444; }
    dl.glossary .note { color: #888; font-size: 0.85rem; }
    .beginner-aid { background: #f7fbff; border-left: 3px solid #cfe2f3; padding: 0.6rem 1rem; margin: 0.6rem 0; font-size: 0.95rem; }
    .beginner-aid::before { content: "初学者向け補足: "; font-weight: bold; color: #336; }
  </style>
</head>
<body>

<h1>[{owner}/{repo}#{number}] {title}</h1>

<table>
  <tr><th>Issue</th><td><a href="{URL}">{URL}</a></td></tr>
  <tr><th>状態</th><td><span class="state-{open|closed}">{OPEN|CLOSED}</span> {stateReason があれば 括弧内に}</td></tr>
  <tr><th>作成者</th><td>@{author.login}</td></tr>
  <tr><th>作成日</th><td>{createdAt YYYY-MM-DD}</td></tr>
  <tr><th>最終更新</th><td>{updatedAt YYYY-MM-DD}</td></tr>
  <tr><th>ラベル</th><td><span class="labels">{各ラベルを <span class="label">name</span> で}</span></td></tr>
  <tr><th>コメント数</th><td>{コメント数} 件</td></tr>
  <tr><th>要約作成日</th><td>{今日の日付}</td></tr>
</table>

<!-- ===== deep モードのときだけ挿入: 用語集を最上部(概要の前)に置く ===== -->
<h2>用語集</h2>
<p>{この issue で前提とされている用語のうち、初学者が引っかかりやすいものを最大8語まで}</p>
<dl class="glossary">
  <dt>{用語1(原語のまま)}</dt>
  <dd>{issue 本文・コメント内の説明を引用ベースで1〜2文。出典が issue 内ならそのまま。}<span class="by"> — 出典: <a href="{URL}">issue本文</a></span></dd>

  <dt>{用語2}</dt>
  <dd><span class="note">補足:</span> {issue 内に説明がない場合、Go の公式仕様・標準ライブラリドキュメントに基づく1〜2文の事実ベース解説。推測語は使わない。}</dd>
</dl>
<!-- ===== deep モードここまで ===== -->

<h2>概要</h2>
<p>{このissueで何が提案・報告されているかを2-3文で要約}</p>

<h2>背景・目的</h2>
<p>{なぜこのissueが立てられたのか、どんな問題を解こうとしているのかを段落形式で}</p>
<p>{必要に応じて複数段落。ユースケース、既存の回避策、過去の経緯なども}</p>

<h2>解消方法・提案</h2>
<p>{issue本文で提案されている解決方針を段落形式で}</p>
<p>{API変更の場合、変更前後を対比}</p>

<!-- ===== deep モードのときだけ挿入 ===== -->
<h2>議論のタイムライン</h2>
<p>{議論が時系列でどう推移したかを1〜2文で俯瞰}</p>
<ul class="timeline">
  <li class="timeline-item">
    <span class="when">{YYYY-MM-DD}</span>
    <span class="kind kind-proposal">提案</span>
    <strong>@{username}</strong>: {一行サマリ}
    (<a href="{comment URL}">link</a>)
  </li>
  <li class="timeline-item">
    <span class="when">{YYYY-MM-DD}</span>
    <span class="kind kind-objection">反対</span>
    <strong>@{username}</strong>: {一行サマリ}
    (<a href="{comment URL}">link</a>)
  </li>
  <!-- kind は proposal / objection / agree / decision / note の5種類 -->
  <!-- 8〜15 件、時系列順 -->
</ul>
<!-- ===== deep モードここまで ===== -->

<h2>議論点</h2>
<p>{議論全体の俯瞰を1段落。「主にXとYが論点」のような}</p>

<h3>{論点1の見出し}</h3>
<p>{論点1についての賛否と論拠}</p>
<blockquote>
  {重要コメントの引用}
  <span class="by">— by @{username} (<a href="{comment URL}">link</a>)</span>
</blockquote>
<!-- deep モード時、issueで言及されている前提知識のうち初学者がつまずきそうなものを再説明 -->
<div class="beginner-aid">{issue 内に登場した前提知識を初学者向けに再説明する1〜3文。issueに無い一般論は書かない}</div>

<h3>{論点2の見出し}</h3>
<p>{論点2についての議論}</p>

<!-- 論点数に応じて繰り返す -->

<h2>ドラフト実装</h2>
<p>{このセクションに出てくるコードは議論の中で提案されたものであり、必ずしも採用されたわけではない旨の1文}</p>

<h3>{コード例1のタイトル、例: 「初期提案のAPIシグネチャ」}</h3>
<p class="code-meta">提案者: @{username} | 出典: <a href="{URL}">issue本文</a> or <a href="{comment URL}">コメント</a></p>
<p>{このコードが何を示しているかの2-3文の説明}</p>
<pre><code>{コード内容をそのまま}</code></pre>

<h3>{コード例2のタイトル}</h3>
<!-- 以下同様 -->

<h2>関連Issue / PR</h2>
<ul>
  <li><a href="{URL}">{owner}/{repo}#{number}</a> — {title} <span class="state-{open|closed}">({state})</span></li>
  <!-- 参照された順または本文→コメントの順で列挙 -->
</ul>

<h2>メモ</h2>
<div class="memo">(個人メモ用の空欄)</div>

</body>
</html>

エスケープ

  • HTMLに埋め込む際、ユーザー生成テキスト(タイトル、body、コメント、ユーザー名)は &, <, >, ", ' をエスケープする
  • コードブロックの中身も <code> に入れる際はエスケープする(ただし元のインデント・改行は保持)
  • URLは href 属性内ではクォートエスケープのみで良い

コードブロックなし・関連リンクなしの場合

  • コード例が1つも抽出できなかった場合は「ドラフト実装」セクション自体を省略する(見出しも出さない)
  • 関連issue/PRが0件の場合は「関連Issue / PR」セクションを省略する

standard / deep モードの構造差

  • standard モード: 上記テンプレートのうち「議論のタイムライン」「beginner-aid 補足」「用語集」の3要素は 一切出力しない。現行 (v0) と HTML 構造を完全互換に保つ。
  • deep モード: 上記3要素を追加で出力する。
    • 「用語集」は最上部に置く。メタデータ表の直後・「概要」の前に配置し、本文を読む前に前提用語を確認できるようにする(「議論のタイムライン」は従来どおり「解消方法・提案」の後)。
    • 時系列で抽出できる転換点が3件未満の場合は「議論のタイムライン」セクション自体を省略する(無理に水増ししない)
    • 用語集候補が0件の場合は「用語集」セクション自体を省略する
    • beginner-aid は該当する論点にのみ付ける(全論点に強制的に付けない)

エラーハンドリング

ケース対応
URLが提供されない使い方を表示して終了
URLがPR (/pull/NNN)「PRではなくIssue用」のエラーを表示して終了
URLのパースに失敗(GitHub以外、形式不正)❌ GitHub の Issue URL として認識できません: {URL}
gh コマンドが無い❌ gh CLI (GitHub CLI) が必要です。 brew install gh でインストールしてください。
gh auth status が未認証❌ gh CLI が未認証です。gh auth login を実行してください。
issue取得が404❌ Issue が見つかりません (404): {URL}
関連issue/PRの個別取得が失敗スキップして続行、リストにはURLのみ記載
issue本文が空bodyは空として扱い、「背景・目的」「解消方法」は「(本文に記載なし)」と書いてコメント欄から拾う

実装時の注意

  • gh issue view --json comments で取得されるコメントは API の body (Markdown) なので、HTMLに埋め込む前にMarkdownをプレーンテキストまたは簡易HTMLに変換する。複雑な変換は不要で、コードブロック( ``` )を <pre><code> に、インラインコード( ` )を <code> に、リンク [text](url) を <a> に変換できれば十分。
  • gh の出力JSONは巨大になりうるので、一時ファイル(/tmp/gh-issue-{number}.json)に保存してから jq でパースすると扱いやすい。
  • コメントが多い issue (100件超) では gh の出力が長大になる。jq で必要なフィールドだけ取り出してから処理する。
  • 議論要約は機械的に全コメントを列挙せず、論点ごとに合意・相違をまとめる。この時点では thinking をしっかり使う(どのコメントが本質的な論点で、どれが 「+1」 / 「LGTM」 といった情報量の少ないコメントかを選別する)。

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.