SKILL.md
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 パイプラインをそのまま使えます。
# 例: open PR の author 一覧を取得
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 # 事前 incremental sync してから表示
cmux-team issue show 272 --sync # 対象 issue を同期してから表示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 を実行するか、GITHUBTOKEN / GHTOKEN を設定
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 を走らせてください）。