AgentSkillsCN

github-issue-improver

自动分析 GitHub Issue，并将其转化为结构化内容进行优化。通过 AI 自动补全与修正，将杂乱无章或信息不足的 Issue 转化为便于处理的格式。包括标题标准化、正文结构化、合理添加标签、提示缺失信息。适用于“请优化这个 Issue”、“请整理 Issue 内容”等需求。

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

GitHub Issue Improver

Overview

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

Quick Start

基本的な使い方

bash
# 単一の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ファイルを使用（推奨）

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

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

方法2: 環境変数

bash
export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

方法3: 直接指定

bash
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スタイルのプレフィックス付与
code
元: login fails
改善: Fix: Login fails with invalid credentials

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

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

バグ報告の例:

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

## Steps to Reproduce
1.
2.
3.

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

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

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

機能要望の例:

markdown
## 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に改善提案をコメントとして追加
  • •元の内容を保持しながら提案を提示
  • •チームメンバーが改善内容を確認して適用可能
bash
python scripts/issue_improver.py --repo owner/repo --issue 123 --mode comment

Updateモード

  • •Issueを直接更新
  • •即座に改善が適用される
  • •注意：元の内容が変更されます
bash
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を一括処理：

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

Scripts Usage

issue_improver.py

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

bash
# 基本構文
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内容を分析し、改善案を生成。

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

github_client.py

GitHub APIとの連携処理。

bash
# 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ファイルからの改善適用とテンプレート生成。

bash
# 改善テンプレートを生成
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読み込み機能のテスト。

bash
# トークン読み込みのテスト
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の品質向上

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

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

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

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

bash
# 特定のプロジェクトで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での自動実行例：

yaml
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番号を確認

トラブルシューティング

bash
# デバッグ用詳細出力
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処理の前処理として最適です。