| name | cmux-team-gh |
| description | Use when reading GitHub issues / PRs (github.com or GitHub Enterprise) from the current project. Triggers: mention of an issue/PR number (e.g. "#272", "issue 272", "PR #42"), user asks to run `gh issue`, `gh pr`, `ghe issue`, `ghe pr`, wants to see review / comment status, or asks "show me open issues / review requests / recent closed PRs". Use `cmux-team issue` / `cmux-team pr` / `cmux-team gh` instead of invoking `gh` directly for READ operations — the local SQLite cache avoids rate limit exhaustion. Writing (create / comment / close / merge / review) still goes through `gh`.
|
cmux-team-gh: GitHub issue/PR キャッシュ経由の読み取り
このスキルは cmux-team plugin に同梱される GitHub issue/PR キャッシュの
使い方リファレンスです。gh issue / gh pr の 読み取り系 は
cmux-team issue / cmux-team pr に置き換えてください。
なぜ gh を直接使わないか
gh を叩くたびに GitHub API を呼ぶため、複数 issue を走査する用途
（レビュー待ち一覧、最近 close された PR の確認等）で rate limit を
消費しやすい。cmux-team gh sync は ETag (If-None-Match) + since= による差分同期で、
変更がなければ 304 Not Modified（rate limit 消費 0）で返る。- 同一プロジェクト内で複数エージェントが同じ issue を参照する場合、
キャッシュから読むため何度でも同じコストで読める。
トリガー判定（Claude 向け）
以下のいずれかの場合にこのスキルを適用してください:
- ユーザーが issue/PR 番号に言及（
#272, issue 272, PR #42, T042 等）
- ユーザーが
gh issue list / gh pr view 等を実行したがっている
- ユーザーが
ghe ...（企業 GitHub）を実行したがっている — 同じキャッシュで読める
- 「レビュー待ち」「open な PR」「直近 closed」「自分にアサインされた issue」等、
issue/PR の問い合わせ全般
@me に割り当てられた issue を探している- 特定ラベル（
bug, help wanted 等）の絞り込みをしたい
置換表
| 代わりに | 使うもの |
|---|
gh issue list --state open --limit 20 | cmux-team issue list --state open --limit 20 |
gh issue list --assignee @me | cmux-team issue list --assignee @me |
gh issue list --label bug | cmux-team issue list --label bug |
gh issue view 272 | cmux-team issue show 272 |
gh issue view 272 --json title,body,labels | cmux-team issue show 272 --json title,body,labels |
gh pr list --state open | cmux-team pr list --state open |
gh pr view 42 | cmux-team pr show 42 |
gh pr view 42 --json state,title,reviews | cmux-team pr show 42 --json state,title,reviews |
gh search issues keyword | cmux-team issue search keyword |
JSON 出力のキー名は gh --json 互換です（author.login,
assignees[].login, labels[].name, createdAt, mergedAt など）。
既存の jq パイプラインをそのまま使えます。
cmux-team pr list --state open --json number,title,author.login
キャッシュが古いと感じたら
- 差分同期（ほぼ無料）:
cmux-team gh sync
- 前回同期以降に更新された issue/PR のみ取得
- 変更がなければ 304 Not Modified
- フル同期:
cmux-team gh sync --full
- 直近 500 件の issue/PR を最初から取得
- 初回実行 / トークン変更 / 月 1 回の運用推奨
- 削除・transfer された issue を cleanup する唯一の手段
- 状態確認:
cmux-team gh status
- 最終 sync 時刻、rate limit 残量、viewer login、issue/PR 件数
- 「最終 full sync から N 日経過」表示に注意
- 30 日を超えたら
--full 推奨
省略コマンドとしての --sync
一発で同期 + 読み取りを行いたい場合は list/show に --sync を付けられます:
cmux-team issue list --state open --sync
cmux-team issue show 272 --sync
TUI Issues タブ
cmux-team start で起動する Manager ダッシュボードには「Issues」タブが
あります（キーバインド 5 または I）。
R — incremental sync を走らせるEnter / O — 選択中 issue を markdown ビューアで開くB — 選択中 issue の GitHub URL をブラウザで開く↑ / ↓ — カーソル移動
書き込み系は gh を使う
以下の操作は本 skill の対象外です。引き続き gh を使ってください:
gh issue create — issue 作成gh issue comment / gh pr comment — コメント追加gh issue close / gh pr close — クローズgh pr merge — マージgh pr review — レビュー送信
書き込みを行った後は cmux-team gh sync でキャッシュを更新してください。
無効化される状況
以下の場合、このスキルは使えません。従来通り gh を直接使ってください:
- 起動ディレクトリが git repo でない（exit 2）
origin が GitHub / GHE でない（exit 2）- 認証トークンが無い（exit 3）
gh auth login を実行するか、GITHUB_TOKEN / GH_TOKEN を設定
rate limit 到達時（exit 4）
cmux-team gh sync が exit 4 を返した場合、しばらく待って（reset_at
表示を参照）再度実行してください。cmux-team issue list --stale-ok で
警告を抑止して古いキャッシュから読み続けることも可能です。
Exit codes
| code | 意味 |
|---|
| 0 | 成功 |
| 1 | 汎用エラー |
| 2 | 非 git / 非 GitHub origin |
| 3 | 認証欠如 |
| 4 | rate limit 到達 |
キャッシュの場所
- DB:
.team/gh-cache.db（SQLite WAL）
- 本文 / raw JSON は同 DB 内に格納（別ファイルなし）
- トークンハッシュ不一致 / 異なる repo を検出したら自動 purge
プロジェクト毎に独立したキャッシュを持つため、複数リポジトリを横断して
参照する用途には使えません（各リポジトリで個別に cmux-team start /
cmux-team gh sync を走らせてください）。
