github-ops

GitHub Ops スキル

gh api と gh search を使ったリポジトリ調査のための体系的なガイダンスを提供します。

概要

エージェントによるファイルパスの推測や、大きなファイルをむやみに取得することで、リポジトリの調査は失敗しがちです。このスキルでは、GitHub CLI を使った「マップ → 特定 → 取得」の順序を徹底し、トークンの浪費を抑え、信頼性を高めます。

⚡ 調査に必須のコマンド

コンテンツを取得する前に、これらのコマンドでリポジトリの構造を確認してください。

1. リポジトリのルートを一覧表示する

gh api repos/{owner}/{repo}/contents --jq '.[].name'

2. 特定のディレクトリを一覧表示する

gh api repos/{owner}/{repo}/contents/{path} --jq '.[].name'

3. ファイルの内容を取得する（Base64 デコード済み）

gh api repos/{owner}/{repo}/contents/{path} --jq '.content' | base64 -d

4. リポジトリ内のパターンを検索する

gh search code "{pattern}" --repo {owner}/{repo}

5. リポジトリのメタデータを取得する

gh repo view {owner}/{repo} --json description,stargazerCount,updatedAt

🔄 トークン効率の高いワークフロー

1. ツリーをマップする：ルートと主要なディレクトリ（commands、src、docs）を一覧表示します。
2. エントリーポイントを特定する：README.md、gemini-extension.json、package.json、またはSKILL.mdを探します。
3. 対象を絞って取得する：まずエントリーポイントだけをダウンロードします。
4. 詳細を調査する：すべてのファイルを読むのではなく、gh search codeを使ってロジックのパターンを見つけます。

🛡️ プラットフォームの安全性（Windows）

• base64 -dを使う場合、出力が大きければWriteツールを使ってファイルにリダイレクトしてください。
• 複雑なパイプでは、Linux 形式の/dev/stdinパターンを避けてください。
• ローカルストレージにはネイティブのパスを使用してください。

絶対遵守事項

1. ファイルを読む前に、必ずマップ → 特定 → 取得の順序に従ってください。パスを推測してファイルをむやみに取得すると、トークンを浪費し、404 エラーを引き起こし、リポジトリ構造の幻覚を生みます。
2. 親ディレクトリを先に一覧表示するか、gh apiでファイルの存在を確認せずに、ファイルを取得してはいけません。不要な大きなファイルの取得は、コンテキストウィンドウを使い果たすおそれがあります。
3. gh apiの JSON 出力は、必要なフィールドだけに絞り込むため、必ず--jqを使ってください。フィルターなしの API レスポンスには無関係なフィールドが何百個も含まれ、トークン使用量が膨らみます。
4. スコープ修飾子（リポジトリ、組織、またはパス）なしでgh search codeを使ってはいけません。スコープを指定しないコード検索は GitHub 全体から結果を返すため、無関係な情報が大量に含まれます。
5. リポジトリのメタデータが必要な場合は、リポジトリのファイルを直接読むより、必ずgh apiの構造化クエリを優先してください。API クエリは高速かつ構造化されており、公開リポジトリでは認証コンテキストも必要ありません。

反パターン

反パターン	失敗する理由	正しい方法
ファイルパスを推測して直接取得する	404 が頻発し、存在しないパスにトークンを浪費する	まずルートツリーをマップする：gh api repos/{owner}/{repo}/git/trees/HEAD --jq '.tree[].path'
1 つのフィールドを取得するためにファイル全体を取得する	大きなファイルはコンテキストを使い果たし、処理が遅く不正確になる	--jqを使って、API レスポンスから必要なフィールドだけを抽出する
スコープを指定しないgh search codeクエリ	GitHub 全体の結果が返され、ノイズが有用な情報を圧倒する	常に--repo owner/nameまたは--owner orgのスコープ修飾子を追加する
バイナリファイルや生成ファイルを読む	バイナリの内容は判読できず、生成ファイルは頻繁に変更される	まずファイルの種類を特定し、バイナリはスキップして、ソースファイルだけを読む
ファイルごとに API を順番に呼び出す	不要な往復が遅延を増やす	まとめて処理する：gh apiのツリーや検索を使って複数の対象を特定し、その後、並行して取得する

GitHub MCP サーバーの操作

公式の GitHub MCP サーバー（@modelcontextprotocol/server-github）が設定されている場合は、リポジトリ管理と自動化に、より高水準のこれらのツールを使用してください。

// settings.json configuration
"github": {
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-github"],
  "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}" }
}

PR 自動化パターン

# Create PR with auto-generated description
gh pr create \
  --title "feat: add feature X" \
  --body "$(gh api repos/{owner}/{repo}/compare/{base}...{head} --jq '.commits[].commit.message' | head -5)" \
  --base main \
  --head feature/x

# Auto-merge after CI passes
gh pr merge --auto --squash --delete-branch

Issue 管理

# List open issues by label
gh issue list --label "bug" --state open --json number,title,assignees

# Bulk-close resolved issues
gh issue list --label "stale" --json number --jq '.[].number' | \
  xargs -I{} gh issue close {} --comment "Closing as stale"

# Create issue from template
gh issue create \
  --title "Bug: [description]" \
  --body-file .github/ISSUE_TEMPLATE/bug_report.md \
  --label "bug,needs-triage"

リリース自動化

# Create release with auto-generated notes
gh release create v1.2.0 \
  --generate-notes \
  --title "v1.2.0" \
  --target main

# Upload release assets
gh release upload v1.2.0 dist/*.tar.gz dist/*.zip

ワークフロー管理

# Trigger workflow manually
gh workflow run deploy.yml --field environment=production

# Watch workflow run
gh run watch $(gh run list --workflow=deploy.yml --limit=1 --json databaseId --jq '.[0].databaseId')

# Download workflow artifacts
gh run download --name=build-artifacts --dir=./artifacts

割り当てられたエージェント

• artifact-integrator：リポジトリのオンボーディングを担当するリードエージェントです。
• developer：PR 管理と調査を担当します。

メモリプロトコル（必須）

開始前： .claude/context/memory/learnings.md を読みます。

完了後：

• 新しいパターン -> .claude/context/memory/learnings.md
• 発見した問題 -> .claude/context/memory/issues.md
• 決定事項 -> .claude/context/memory/decisions.md

中断されることを前提としてください。メモリに記録されていなければ、実行されていないものとみなします。