Agent-Skills.md

Agent Skills: pr-description

|

UncategorizedID: goldeneggg/dotfiles/pr-description

Repository

goldeneggg/dotfiles
goldeneggg
1

Install this agent skill to your local

pnpm dlx add-skill https://github.com/goldeneggg/dotfiles/tree/HEAD/ai-linux/.claude/skills/pr-description

Skill Files

Browse the full folder contents for pr-description.

Download Skill

Loading file tree…

ai-linux/.claude/skills/pr-description/SKILL.md

Skill Metadata

Name
pr-description
Description
|

pr-description

セッション内の会話コンテキストとgit diffの情報を元に、ユーザーが指定したフォーマットでPR説明文を生成し、mdファイルとして出力する。 あわせて、PRタイトルの推奨案を会話内に提示する。

ユーザーとのやり取りはすべて日本語で行う。

スコープの境界

  • このスキルはPR説明文のファイル出力と、PRタイトルの会話内提示に特化している
  • PRを「レビュー」する場合は pr-reviewer スキルを使い、このスキルは使わない
  • gh pr create でPRを直接作成する依頼とも異なる（タイトル案を作る点で似ているが、本スキルは作成までは行わない）

Degrees of Freedom

  • フォーマット解釈: Low freedom — テンプレート指定時はテンプレートの構造を厳守する。デフォルトフォーマットのセクション構成も変更しない
  • 情報の取捨選択: Medium freedom — 会話コンテキストとgit diffから何を抽出し、どの粒度で記述するかは対象の変更規模や性質に応じて判断してよい
  • 文体・表現: Low freedom — 日本語で記述、簡潔かつ技術的に正確に。コード・技術用語は原語のまま
  • PRタイトル: Low freedom — Conventional Commits形式・72文字以内・3案提示・最初の案を推奨。種別(feat/fix/refactor/docs/chore/test/perf/build/ci/style/revert)とscopeは変更内容に基づいて選定

引数

pr-description スキル（<出力先パス> [--base <ブランチ>] [--template <テンプレートパス>] [--format <インラインフォーマット指示>] を指定）
  • <出力先パス> (必須): 出力するmdファイルのパス（例: docs/pr-description.md）
  • --base <ブランチ> (任意): 比較対象のベースブランチ（デフォルト: main → master の順で自動検出）
  • --template <パス> (任意): テンプレートファイルのパス
  • --format <指示> (任意): インラインでフォーマットを指示するテキスト

テンプレートもフォーマット指示もない場合は、リポジトリの .github/pull_request_template.md（大文字・小文字を区別せず存在チェック）を探し、あればそれをテンプレートとして使用する。無ければデフォルトフォーマットを使用する。

実行フロー

Step 1: 引数のパース

スキル呼び出し時の引数を解析する。

  • 出力先パスが未指定の場合 → 推奨案を含む複数の選択肢を提示してユーザーに確認
  • テンプレートとフォーマット指示が両方指定された場合 → テンプレートを優先

Step 2: テンプレートの取得

テンプレートパスが指定された場合:

  • Readツールでテンプレートファイルを読み込む
  • プレースホルダ（{{summary}}, {{changes}}, {{test_plan}} など）を認識する

フォーマット指示が指定された場合:

  • インラインのテキスト指示に従ってフォーマットを構築する
  • ただし、フォーマット指示の内容に関わらず「概要」と「変更内容」は最低限含める

どちらもない場合:

  1. リポジトリ内の .github/pull_request_template.md を大文字・小文字を区別せず存在チェックする 
    # 大文字・小文字を問わず該当ファイルを検出
find .github -maxdepth 1 -iname 'pull_request_template.md' 2>/dev/null
  2. 見つかった場合 → そのファイルをReadツールで読み込み、テンプレートとして使用する（プレースホルダの有無は問わない。後述「テンプレートのプレースホルダ」の方針に従う）
  3. 見つからない場合 → デフォルトフォーマット（後述）を使用する

Step 3: 情報収集

以下の2つの情報源からPR説明文に必要な情報を収集する。

会話コンテキスト:

  • セッション内でどのような作業を行ったか
  • ユーザーの意図・目的
  • 議論された設計判断やトレードオフ
  • 発生した問題とその解決方法

git diff:

ベースブランチの決定順序:

  1. --base 引数で指定されたブランチ
  2. 未指定の場合: main → master の順で自動検出
  3. いずれも存在しない場合: ユーザーにベースブランチを確認
git diff <ベースブランチ>...HEAD

追加で、変更の全体像を把握するため:

git log <ベースブランチ>..HEAD --oneline

差分が大きい場合（目安: 500行超）:

  1. まず git diff <ベースブランチ>...HEAD --stat で変更ファイルと行数の概要を把握
  2. 重要なファイル（新規追加、大幅変更）を選別してdiffを確認
  3. 全diffの詳細読み込みは避け、会話コンテキストとstatで全体像を構成する

Step 4: PR説明文の生成

収集した情報をテンプレート/フォーマットに当てはめて説明文を生成する。

生成時の方針:

  • 会話コンテキストを主な情報源とする。ユーザーが何を意図して何をしたかが最も重要
  • git diffは裏付けと補完に使う。会話に現れない細かい変更点をカバー
  • 変更の「なぜ」を重視。コードの差分は読めばわかるので、背景や動機を中心に書く
  • 技術的に正確に記述。推測ではなく、実際の変更内容に基づく
  • 簡潔だが十分な情報量を保つ
  • 人間が読みやすく理解しやすい、自然で具体的な表現を使う
  • 独自の造語、社内だけで通じる略語、意味が曖昧な抽象表現を避ける。一般的な用語に言い換え、避けられない専門用語や略語は初出時に補足する
  • 一文を短くし、主語と動作を明確にする。変更内容・目的・影響が読み手に伝わるかを、専門知識のないレビュアーの視点で確認する
  • 「レビューして欲しい観点」は会話中に現れた迷いや設計判断のトレードオフから抽出する。セッション中にユーザーが悩んだ箇所、代替案を検討した箇所、自信がない部分などがあれば重点的に記載する
  • ローカル限定の作業管理情報を持ち込まない（下記「ローカル限定情報の除外」を厳守）

ローカル限定情報の除外

PR説明文を読むのは、対応者のローカル環境を持たない第三者（レビュアー・将来の開発者）である。 会話コンテキストにはタスク管理用の情報がしばしば登場するが、その多くは対応者のローカルにしか存在せず、読み手には何を指すのか分からない。 したがって、以下のようなローカル限定の参照は、たとえ会話に登場していてもPR説明文に書かない。

除外すべきもの（例）:

  • タスクドキュメントのパス（例: todos/001-setup/README.md, docs/tasks/..., .personal/...）
  • TODO番号・タスク番号への参照（例: 「タスク 001」「TODO #3 の対応」「タスク003の受け入れ条件」）
  • ローカルの作業メモ・指示書・スクラッチファイルへの言及

書いてよいもの（読み手が辿れる共有情報）:

  • GitHub の issue / PR リンク（例: #123, owner/repo#45）
  • 共有リポジトリにコミット済みのドキュメントへのパス

判断基準: 「この参照は、リポジトリをクローンしただけの第三者が辿れるか？」 辿れないものは書かない。 タスクの背景や目的そのものは有用なので、ローカル限定の参照を取り除いた上で、変更の動機・背景として一般化して記述する（「タスク001対応」ではなく「〇〇を実現するため」と書く）。

Step 5: PRタイトル候補の生成

PR説明文と同じ情報源（会話コンテキスト・git diff・git log）から、PRタイトル候補を3案生成する。

形式（Conventional Commits 準拠）:

<type>(<scope>): <subject>
  • <type>: feat / fix / refactor / docs / chore / test / perf / build / ci / style / revert から選定
  • <scope> (任意): 変更範囲（モジュール名・パッケージ名・機能名など）。明確に絞れる場合のみ付ける
  • <subject>: 変更内容の簡潔な要約（命令形・小文字始まり推奨、句点なし）

制約:

  • 全体で 72文字以内（GitHub UIで省略表示されないことを優先）
  • 日本語subjectも可（プロジェクトの慣習に合わせる）。git log の傾向から既存スタイルを推定する
  • 破壊的変更を含む場合、<type>(<scope>)!: のように ! を付与する

候補選定の方針:

  • 第1案（推奨案）: 変更の中心を最も的確に表現するもの
  • 第2-3案: scopeの粒度違い、type違い（例: feat と refactor どちらにも解釈可能な場合）、表現違いなど、ユーザーが選びやすい多様性を持たせる
  • 単一の自明な変更で複数案を出すのが不自然な場合は、3案にこだわらず1-2案でよい

git log の参照: 直近のコミット履歴を git log <ベースブランチ>..HEAD --oneline 等で確認済みの情報から、プロジェクトのコミットメッセージ慣習（日本語/英語、scopeの使い方など）を推定し、それに沿った候補にする。

Step 6: 出力

Writeツールで指定パスにmdファイルを出力する（PR説明文のみ。タイトル候補はファイルに含めない）。

出力前:

  • 出力先に既存ファイルがある場合 → 推奨案を含む複数の選択肢を提示して上書き確認を行う。ユーザーが拒否した場合は別のパスを確認する

出力後、以下を会話内で提示する:

  • ファイルパスをユーザーに報告
  • PR説明文のサマリー
  • PRタイトル候補（3案・推奨案を明示）
  • 修正・差し替えが必要か確認

会話内でのタイトル提示フォーマット例:

## PRタイトル候補

推奨案: `feat(pr-description): PRタイトルの推奨案出力機能を追加`

その他の候補:
- `feat(skills): pr-descriptionにPRタイトル提案を追加`
- `refactor(pr-description): タイトル提案フローを統合`

デフォルトフォーマット

テンプレート・フォーマット指示がない場合の解決順序:

  1. リポジトリの .github/pull_request_template.md（大文字・小文字を区別しない）が存在すれば、それをテンプレートとして使用する
  2. 存在しなければ、references/default-template.md の構造で生成する

references/default-template.md は6セクション構成: 概要、変更内容、技術的な詳細、テスト、レビューして欲しい観点、関連情報。

テンプレートのプレースホルダ

テンプレートファイルで使用できるプレースホルダ:

| プレースホルダ | 内容 | |---|---| | {{summary}} | 変更の概要（1-3文） | | {{changes}} | 主要な変更点（箇条書き） | | {{details}} | 技術的な詳細 | | {{test_plan}} | テスト計画・実施内容 | | {{breaking_changes}} | 破壊的変更（あれば） | | {{related_issues}} | 関連issue | | {{review_points}} | レビューして欲しい観点 | | {{files_changed}} | 変更ファイル一覧 |

プレースホルダがないテンプレートの場合は、テンプレートの構造（見出し、セクション）を読み取り、各セクションに適切な内容を埋める。

エラーハンドリング

git diffが取得できない場合

  • gitリポジトリでない → 会話コンテキストのみで生成し、その旨を注記
  • ベースブランチが不明 → ユーザーに確認

テンプレートファイルが見つからない場合

  • パスの存在を確認し、見つからなければエラーを報告
  • デフォルトフォーマットへのフォールバックを提案

出力先ディレクトリが存在しない場合

  • 親ディレクトリを作成してから出力

会話コンテキストが不足している場合

  • git diffとgit logから可能な限り情報を抽出
  • 不明な点はユーザーに確認

ガイドライン

  • 出力は必ず日本語（コード・技術用語は原語のまま）
  • テンプレートの構造は厳密に守る。余計なセクションを追加しない
  • git diffの生の差分をそのまま貼り付けない。変更の意味を説明する
  • 1つのPRに含まれる変更が多い場合でも、核心を簡潔にまとめる
  • 推測で書かない。不明点はユーザーに確認する
  • ローカル限定の参照（タスクドキュメントのパス・TODO/タスク番号など）を混入させない。第三者が辿れない情報は書かず、背景は一般化して記述する（詳細はStep 4「ローカル限定情報の除外」）
  • 独自の造語や読み手を限定する表現を混入させない。一般的で具体的な言葉に置き換え、必要な専門用語には短い説明を添える
  • PRタイトル候補はファイルには書き込まず、会話内のみで提示する（誤ってPR本文に混入することを防ぐ）
  • PRタイトルはConventional Commits形式・72文字以内を厳守する。推奨案を1つ明示し、計3案を提示する