GitHub CLI
This skill is coordination-exempt: skip the ai-coord gate for its declared work.
Routing
Use yeet to author or update a pull request, issue, issue comment, or discussion. yeet owns semantic analysis,
repository templates, Paul's writing voice, idempotency, and direct posting. Route repository renames through
repo-rename so GitHub and local continuity change together.
Authority
- Read and inspect without confirmation.
- Execute reversible or ordinary GitHub writes only when the user explicitly requested that outcome.
- Never delete repositories, releases/assets, workflow runs/caches, secrets/variables, keys, codespaces, extensions, or gists.
- Label deletion is the sole destructive exception: show the target repo, exact labels, commands, and issue/PR impact,
then require approval in a subsequent message before
gh label delete ... --yes.
Workflow
Resolve the repository explicitly when cwd is ambiguous. Let the first required read-only command validate authentication. Run
gh auth statusonly for auth diagnosis.Use installed
gh <command> <subcommand> --helpto resolve flags, JSON fields, and command behavior. CLI JSON field names can differ from API fields. Prefer--jsonwith--jqfor structured output.Preview broad writes with the repository, exact targets, commands, and issue/PR impact. An already requested ordinary write does not require a second approval.
GitHub Status
GitHub incidents produce symptoms that look like a local defect. Examples: a run stays queued for minutes with no
runner, gh run cancel reports a run as completed while gh run view still shows it queued, the API returns 5xx
errors, or a push succeeds while Actions does not start.
Before you tell the user that an error, a stall, or an inconsistent result comes from their setup, workflow, or credentials, check GitHub's status page:
curl -fsS https://www.githubstatus.com/api/v2/summary.json | jq '{status: .status.description,
incidents: [.incidents[] | {name, status, impact, updated_at}],
degraded: [.components[] | select(.status != "operational") | {name, status}]}'If an incident is open or an affected component is not operational, report the incident name, the affected components,
and the latest update time. Attribute the symptom to the incident. Do not change the user's workflow, configuration, or
credentials to work around it. Wait for mitigation, then retry. If the status page shows no incident, continue with
local diagnosis.
CI Failure Triage
Use this workflow when the user asks why CI fails or asks to fix a failing run. Keep each command output bounded.
Find the failing runs for the branch or the commit:
gh run list --branch <branch> --status failure --limit 5 gh run list --commit <sha> --status failure --limit 5Extract only the failed-step lines. Never print the raw log.
gh run view <run-id> --log-failed | rg --no-config -n 'error|FAIL|panic|✗' | head -80Check toolchain drift before you change code. Compare the versions pinned in
.github/workflows/*.ymlwith the local--versionoutput. Common cases are Foundry (forge), Bun (bun), Node.js (node), and Rust (rustc).If the user requested a fix, fix the cause and push the commit.
Get the new run ID with
gh run list --commit <new-sha> --limit 5. Then watch that run:gh run watch <run-id> --exit-status --compactReport the run URL from
gh run view <run-id> --json url --jq .urland the final run status.
Notable Flags (gh 2.98+)
gh pr checkout --worktree <path>andgh issue develop --checkout --worktree <path>check out into a linked git worktree instead of switching the current branch.gh search issues --search-type semantic|hybridranks by relevance: issues only, one page, no--sort/--order, not on GitHub Enterprise Server.gh config set api_host <gateway> --host <host>routes that host's API traffic through a gateway. The feature is experimental and is not a security boundary.gh auth loginandgh auth refreshcopy OAuth device codes to the clipboard by default (2.101+). To opt out, rungh config set clipboard disabled.gh auth login --expiring(2.103+) prefers expiring OAuth tokens thatghrefreshes. To prefer them on every sign-in, rungh config set expiring_credentials enabled. Rungh auth tokeneach time you need a token. Never cache its output.GH_TOKENandGITHUB_TOKENvalues never refresh.gh auth statusrefreshes an expired or near-expiry refreshable token unless you pass--no-refresh. With that flag, 2.103.3+ reports the token as expired, not invalid. To renew it, run the command without the flag. Do not rungh auth refreshfor this case.- In 2.104.0+,
gh auth statusprints the underlying rate-limit, server, or network error. Use that error to decide between a GitHub incident and a credential problem.ghskips token refresh when its state directory is not writable. --attach '<file>#<alt>'on issue/PR create, edit, and comment uploads images or videos. Route those writes throughyeet. Since 2.103.2, GitHub App installation tokens can attach, and the upload endpoint decides permission.
Completion
Complete when command output verifies the requested GitHub data or state. After a write, fetch the resulting resource. On a partial or ambiguous failure, check whether it changed before retrying. Report the verified state and URL or stable identifier. Include the concrete error and next action when incomplete, and distinguish an unknown result from a confirmed failure.