name	github-issue-improver
description	自動的にGitHub Issueを分析し、構造化された内容に改善するスキル。雑なIssueや情報不足のIssueをAIが作業しやすい形式に自動補完・加筆訂正する。タイトルの標準化、本文の構造化、適切なラベル付与、不足情報の指摘を行う。「このIssueを改善して」「Issue内容を整えて」といった依頼で使用。

GitHub Issue Improver

Overview

このスキルはGitHub Issueの品質を自動的に改善します。雑な記述のIssueを分析し、構造化されたAIが作業しやすい形式に変換します。Issueの種類を自動分類し、適切なテンプレートを適用して不足情報を指摘します。

Quick Start

基本的な使い方

# 単一のIssueを改善（コメントとして提案を追加）
python scripts/issue_improver.py --repo owner/repo --issue 123

# Issueを直接更新
python scripts/issue_improver.py --repo owner/repo --issue 123 --mode update --update-title --update-body --update-labels

# 複数のIssueを一括改善
python scripts/issue_improver.py --repo owner/repo --issues 123 124 125 --mode comment

# どのような改善がされるか確認（実際には変更しない）
python scripts/issue_improver.py --repo owner/repo --issue 123 --dry-run

# JSONファイルから一括適用
python scripts/apply_improvements.py --repo owner/repo apply --improvements-file improvements.json

# JSONファイルから適用内容をプレビュー
python scripts/apply_improvements.py --repo owner/repo --dry-run apply --improvements-file improvements.json

環境設定

方法1: .envファイルを使用（推奨）

# .envファイルを作成
echo "GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxx" >> .env

# .envファイルは自動的に読み込まれます

方法2: 環境変数

export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

方法3: 直接指定

python scripts/issue_improver.py --repo owner/repo --issue 123 --token your_token

🆕 新機能

1. 自動.envファイル読み込み

.envファイルを複数の場所から自動検出
スクリプト実行ディレクトリ、カレントディレクトリ、プロジェクトルート
python-dotenvがなくても動作（推奨）

2. 完全なDry-runモード

--dry-runで完全にオフラインで動作
GitHub APIコールなしで改善案を生成
Token不要でテスト可能

3. JSONベースの一括改善

apply_improvements.pyでJSONファイルから改善を適用
改善テンプレートの生成機能
レビューと承認ワークフローに対応

Core Capabilities

1. Issue自動分析

種類分類: bug, feature, documentation, test, refactorなどを自動判定
重要度評価: critical, high, medium, lowの優先度を自動設定
コンポーネント抽出: frontend, backend, apiなどの関連コンポーネントを特定
品質スコアリング: Issueの品質を0-1のスコアで評価

2. 標準化されたタイトル生成

Coventional Commitsスタイルのプレフィックス付与

元: login fails
改善: Fix: Login fails with invalid credentials

3. 構造化された本文生成

種類に応じたテンプレート自動適用
不足情報の指摘と入力枠の追加
マークダウン形式での整形

バグ報告の例:

## Bug Description
[自動生成された説明]

## Steps to Reproduce
1.
2.
3.

## Expected Behavior
[ここに期待される動作を記述]

## Actual Behavior
[ここに実際の動作を記述]

## Environment
- OS:
- Browser:
- Version:

機能要望の例:

## Feature Description
[自動生成された説明]

## Use Case
[ユーザーストーリーを記述]

## Acceptance Criteria
- [ ]
- [ ]
- [ ]

## Proposed Solution
[解決策の提案]

4. 適切なラベル付与

種類ラベル: bug, feature, documentation
優先度ラベル: priority: critical, priority: high
エリアラベル: area: frontend, area: backend

5. 不足情報の指摘

再現手順の欠如
期待する動作の記述漏れ
環境情報の不足
受け入れ条件の未設定

Workflow Decision Tree

1. 改善モードの選択

Commentモード（推奨）

Issueに改善提案をコメントとして追加
元の内容を保持しながら提案を提示
チームメンバーが改善内容を確認して適用可能

python scripts/issue_improver.py --repo owner/repo --issue 123 --mode comment

Updateモード

Issueを直接更新
即座に改善が適用される
注意：元の内容が変更されます

python scripts/issue_improver.py --repo owner/repo --issue 123 --mode update --update-title --update-body

2. 更新対象の選択

--update-title: タイトルを標準化
--update-body: 本文を構造化
--update-labels: ラベルを適切に設定
何も指定しない場合: 分析結果のみを表示

3. バッチ処理

複数のIssueを一括処理：

python scripts/issue_improver.py --repo owner/repo --issues 123 124 125 --mode comment

Scripts Usage

issue_improver.py

メインの改善スクリプト。GitHub API連携とIssue分析の統括。

# 基本構文
python scripts/issue_improver.py --repo OWNER/REPO --issue NUMBER [OPTIONS]

# 主なオプション
--mode {update,comment}    # 改善適用モード（デフォルト: comment）
--update-title            # タイトルを更新
--update-body             # 本文を更新
--update-labels           # ラベルを更新
--dry-run                 # 適用せずに改善内容を確認
--output {json,text}      # 出力形式（デフォルト: text）

issue_analyzer.py

Issue内容を分析し、改善案を生成。

# Issue分析テスト
python scripts/issue_analyzer.py --title "bug found" --body "login is broken" --output json

github_client.py

GitHub APIとの連携処理。

# Issue取得テスト
python scripts/github_client.py --repo owner/repo --issue 123 --action get

# コメント追加テスト
python scripts/github_client.py --repo owner/repo --issue 123 --action comment --message "Test comment"

apply_improvements.py 🆕

JSONファイルからの改善適用とテンプレート生成。

# 改善テンプレートを生成
python scripts/apply_improvements.py --repo owner/repo template --issues 123 124 125

# JSONファイルから改善を適用
python scripts/apply_improvements.py --repo owner/repo apply --improvements-file improvements.json

# プレビュー（dry-run）
python scripts/apply_improvements.py --repo owner/repo --dry-run apply --improvements-file improvements.json

テスト用スクリプト

test_token_loading.py 🆕

Token読み込み機能のテスト。

# トークン読み込みのテスト
python test_token_loading.py

References

references/issue_templates.md

Issue種類ごとのテンプレートと品質ガイドライン。

バグ報告、機能要望、ドキュメント更新のテンプレート
タイトル命名規則
ラベル付けガイドライン
品質チェックリスト

references/api_reference.md

GitHub Issues APIの詳細なリファレンス。

認証方法と必要な権限
主要なAPIエンドポイントと使用例
レート制限とエラーハンドリング
ベストプラクティス

Integration with Miyabi Framework

このスキルはMiyabiフレームワークの識学理論65ラベル体系と連携可能：

自動ラベル分類

IssueAgentのラベル体系準拠
type:*, priority:*, state:* ラベルの自動付与
カテゴリー別自動分類：frontend, backend, infra

Agent連携

IssueAgent: Issue作成時の自動分析とラベル付与
CodeGenAgent: 改善されたIssueからのコード生成
PRAgent: Issue改善履歴を含むPR自動生成

Use Cases

1. 新規Issueの品質向上

# 新しく作られた雑なIssueを改善
python scripts/issue_improver.py --repo myorg/myrepo --issue 456 --mode update --update-title --update-body

2. バックログの一括整理

# 古い未整理Issueを一括改善
python scripts/issue_improver.py --repo myorg/myrepo --issues 100 101 102 103 --mode comment

3. Issueテンプレートの適用

# 特定のプロジェクトでIssue標準化を実施
for issue in $(gh issue list --repo myorg/myrepo --state open --limit 20 --json number | jq -r '.[].number'); do
  python scripts/issue_improver.py --repo myorg/myrepo --issue $issue --mode update --update-labels
done

4. CI/CD連携

GitHub Actionsでの自動実行例：

name: Improve New Issues
on:
  issues:
    types: [opened]

jobs:
  improve-issue:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Set up Python
        uses: actions/setup-python@v2
        with:
          python-version: '3.9'
      - name: Improve issue
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          python scripts/issue_improver.py --repo ${{ github.repository }} --issue ${{ github.event.issue.number }} --mode comment

Error Handling

共通エラーと対策

401 Unauthorized

原因: GITHUB_TOKENが無効または期限切れ
対策: 新しいPATを生成して設定

403 Rate Limit Exceeded

原因: APIレート制限超過
対策: 1時間待機するか、認証済みトークンを使用

404 Not Found

原因: リポジトリまたはIssueが存在しない
対策: リポジトリ名とIssue番号を確認

トラブルシューティング

# デバッグ用詳細出力
python scripts/issue_improver.py --repo owner/repo --issue 123 --output json

# 接続テスト
python scripts/github_client.py --repo owner/repo --issue 123 --action get

このスキルを使うことで、GitHub Issueの品質が大幅に向上し、開発チームの作業効率が改善されます。特にAIによるIssue処理の前処理として最適です。

Install Skill

SKILL.md