gh-create-issue

GitHub Issue の作成

ユーザーが Issue の作成を依頼したときにこのスキルを使用します。リポジトリの Issue テンプレート形式に従う必要があります。

ワークフロー

ステップ 1: テンプレート種別の判定

ユーザーのリクエストを分析して Issue の種別を判定します:

• ユーザーが問題、エラー、クラッシュ、または動作しないことを説明している場合 -> Bug Report
• ユーザーが新機能、機能強化、または追加サポートを希望している場合 -> Feature Request
• ユーザーが質問をしている、または何かの支援を必要としている場合 -> Questions & Discussion
• ユーザーがユーザー向けの動作変更を伴わないエンジニアリング作業（プルリクエストから先送りされたフォローアップ、技術的負債、リファクタリング、ツールまたは CI の作業）を説明している場合 -> Engineering Task
• それ以外 -> Others

Engineering Task は GitHub の Issue フォームではなく、一般ユーザーには提供されません。リクエストが内部的なエンジニアリング作業を明確に説明している場合にのみ選択してください。

不明な場合は、どのテンプレートを使用するかをユーザーに尋ねてください。独自の判断で「Others」を既定にしないでください。

適格性チェック（Engineering Task のみ）

Engineering Task は、書き込みアクセス権を持つメンテナーとコラボレーターを対象としています。これはリクエストであり、 アクセス制御ではありません。誰かが gh issue create を直接呼び出すことを妨げるものではなく、この スキルもそれを試みません。以下のチェックは、書き込みアクセス権を持たないコントリビューターが そのことを早期に把握し、より適切な場所へ案内されるようにするためにあります。

情報を収集する前に、認証されたユーザーの権限レベルを読み取ってください:

repo="$(gh repo view --json nameWithOwner --jq .nameWithOwner)"
user="$(gh api user --jq .login)"
permission="$(gh api "repos/$repo/collaborators/$user/permission" --jq .permission 2>/dev/null)"
case "$permission" in
  admin | write) echo "eligible" ;;
  *) echo "not eligible" ;;
esac

admin と write のみが適格です（maintain は write として報告されます）。常に返された 値を比較してください。パブリックリポジトリでは、このエンドポイントはコラボレーターでない ユーザーを含むあらゆるユーザーに対して read を返すため、呼び出しの成功だけでは何も証明 できません。ここで repos/{owner}/{repo}/collaborators/{user} を使用しないでください。これは read および triage のみのコラボレーターに対して 204 を返しますが、彼らはこのテンプレート の対象者ではありません。

結果がそれ以外の場合は、このテンプレートを使用しないでください。これは書き込みアクセス権を 持つメンテナー向けであることを説明し、コントリビューターに代わりに公開テンプレートのいずれかを 使用するよう丁寧に依頼し、そこで起票するのを手伝うことを申し出てください。彼らの報告は歓迎 されますが、このテンプレートの下ではそうではありません。Engineering Task のラベルや Issue タイプを保持したまま、黙ってテンプレートを切り替えないでください。

ステップ 2: 選択したテンプレートの読み取り

1. .github/ISSUE_TEMPLATE/ ディレクトリから対応するテンプレートファイルを読み取ります。
2. 必須フィールド（validations.required: true）、タイトルプレフィックス（title）、ラベル（labels、存在する場合）、および Issue タイプ（type、存在する場合）を特定します。

Engineering Task の場合は、代わりに references/engineering-task.md を読み取ってください。これは意図的に .github/ISSUE_TEMPLATE/ の外にあり、独自のタイトルプレフィックス、ラベル、Issue タイプ、および本文構造を持っています。

ステップ 3: 情報の収集

選択したテンプレートに基づいて、必須情報のみをユーザーに尋ねてください。テンプレートの必須フィールドと選択肢の制約（たとえば、Platform と Priority の選択肢）に従ってください。

ステップ 4: Issue 内容の構築とプレビュー

一時ファイルを作成し、Issue の内容を書き込みます:

• issue_body_file="$(mktemp /tmp/gh-issue-body-XXXXXX).md" を使用します。
• 選択したテンプレートの正確なタイトルプレフィックスを使用します。
• テンプレートの本文構造とセクションの順序に従って内容を記入します。
• テンプレートで定義されたとおりにラベルを正確に適用します。
• ラベルが複数ある場合は、すべてのラベルを保持します。
• テンプレートにラベルがない場合は、独自のラベルを追加しないでください。
• テンプレートの type フィールドで定義されたとおりに Issue タイプを正確に適用します。

一時ファイルの内容をプレビューします。ファイルパス（例: /tmp/gh-issue-body-XXXXXX.md）を表示し、作成前に確認を求めてください。ユーザーがプレビューや確認が不要であることを明示的に示した場合（たとえば、自動化ワークフロー）は、このステップをスキップしてください。

ステップ 5: Issue を作成する

gh issue create コマンドを使用して Issue を作成します。

本文用に一意の一時ファイルを使用します:

issue_body_file="$(mktemp /tmp/gh-issue-body-XXXXXX).md"
cat > "$issue_body_file" <<'EOF'
...issue body built from selected template...
EOF

選択したテンプレートの値を使用して Issue を作成します:

gh issue create --title "<title_with_template_prefix>" --body-file "$issue_body_file"

選択したテンプレートにラベルが含まれている場合は、ラベルごとに --label を 1 つずつ追加します:

gh issue create --title "<title_with_template_prefix>" --body-file "$issue_body_file" --label "<label_1_from_template>" --label "<label_2_from_template>"

選択したテンプレートにラベルがない場合は、--label を渡さないでください。

選択したテンプレートが type を宣言している場合は、それも渡してください。--body-file だけでは Issue タイプは引き継がれないため、これを省略すると Issue はタイプなしのままになります:

gh issue create --title "<title_with_template_prefix>" --body-file "$issue_body_file" --type "<type_from_template>"

--template と --web はデフォルトブランチの .github/ISSUE_TEMPLATE/ を基準に解決されるため、どちらも Engineering Task では機能しません。Engineering Task 用の本文はローカルで構築してください。

その他のテンプレートでは、出発点として --template を使用できます（リポジトリの正確なテンプレート名を使用してください）:

gh issue create --template "<template_name>"

複雑なフォーマットが必要な場合は、--web フラグを使用して作成ページをブラウザーで開きます:

gh issue create --web

作成後に一時ファイルをクリーンアップします:

rm -f "$issue_body_file"

注意事項

• 正しいフォーマットに従っていることを確認するため、.github/ISSUE_TEMPLATE/ 配下のテンプレートファイル（Engineering Task の場合は references/）を必ず読んでください。
• テンプレートファイルを唯一の信頼できる情報源として扱ってください。このスキル内でタイトルのプレフィックス、ラベル、Issue タイプをハードコードしないでください。
• タイトルは明確かつ簡潔にし、「a suggestion」や「stuck」のような曖昧な表現は避けてください。
• 開発者が Issue を理解して解決できるよう、できるだけ詳細な情報を提供してください。
• ユーザーがテンプレートタイプを指定しない場合は、まず選択するよう依頼してください。