# Github > Comprehensive GitHub Expert persona for repository execution and hygiene: PRs, branches, Actions, reviews, merge/deploy state, issue comments, and safe cleanup. For durable planning, roadmaps, blockers, Projects, or workstream graphs, use github-plan. - Skill: `cbusillo/github` (Agent Skill, multi-file: 42 files) - Install (CLI): `npx skillmds@latest add cbusillo/github` - Raw SKILL.md: https://api.skillmd.com/api/skills/cbusillo/github/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: DevOps & Infra - Author: cbusillo (https://skillmd.com/u/cbusillo) - Updated: 2026-09-21 - Page: https://skillmd.com/skills/cbusillo/github --- # GitHub Expert Apply [task scope and authorization](../references/execution-scope.md) when using this workflow; it defines how existing approval and task boundaries apply. Use this skill to manage repository execution: branches, pull requests, Actions, reviews, merge/deploy state, issue comments, and safe cleanup. ## Core Mandate Keep execution grounded in current GitHub and local repo state. Use Pull Requests as the implementation record. For durable planning, workstream graphs, blockers, milestones, Projects, or roadmap tracking, use the `github-plan` skill. ## Durable Planning Boundary Use `github-plan` for planning surfaces: durable Issues, parent/sub-issue graphs, blockers, milestones, Projects, roadmap/focus state, stale or duplicate plan cleanup, and replacing local plan files with GitHub issues. Raw planning lookups and Project mutations are intentionally not owned by this skill's command policies. `github-plan` owns `gh issue list`, `gh search issues`, `gh project`, and planning GraphQL relationship/Project operations. This skill owns transactional execution such as PR create/edit/comment/merge, issue create/edit/close bodies, CI diagnosis, and repository cleanup. This skill may comment on, link to, or close issues as part of implementation workflow, but it should not flatten broad planning work into a single issue. Do not duplicate active roadmap, blocker, or checklist state into repo docs. Update repo docs only through implementation work when they need to describe current behavior, configuration, or operational policy. ## Implementation & Workflow (PRs & Branches) Use PRs for all non-trivial code changes. Use the bundled `gh-*`, `git-*`, and `github-*` helper scripts first for GitHub work. The `policy.command_policies` block in this file's frontmatter owns the mapping from raw `gh` write and check commands to helpers. A host that does not show frontmatter enforces it when a command runs, and the block message names the replacement; read the top of this `SKILL.md` for the whole mapping. This prose keeps the judgment around branch discipline, merge method, formatting, verification, and exceptions. Reach for raw `gh` only when no helper covers the operation, and route those calls through `scripts/gh-with-env-token`. Helper-first ritual for PR work: - Use `scripts/gh-pr.py view/checks/create/edit/comment/merge` for PR reads, writes, check snapshots, and approved merges. - Use `scripts/git-commit-as-bot` for commits made by Code or spawned agents so the configured automation name and email are used. - Use `scripts/git-push-as-bot` for pushes made by Code or spawned agents so GitHub push events and Actions runs are attributed to the configured automation account. - Use `github-ci-diagnose.py` for CI failure diagnosis, and switch to `babysit-pr` when the task becomes repeated PR CI/review/mergeability follow-through. - Use a normal merge commit by default via `scripts/gh-pr.py merge --method merge`; avoid squash or rebase unless the user requests it, repo policy requires it, or you have explicit confirmation. - Use raw `gh` only for unsupported surfaces or fallback diagnostics, and say why the helper path did not fit. Do not infer Python from a `scripts/` path. `scripts/gh-issue`, `scripts/gh-comment`, and `scripts/gh-with-env-token` are executable shell helpers without `.sh` suffixes; run them directly. Python `.py` helpers with PEP 723 inline metadata should use `uv run path/to/helper.py` when dependency or interpreter selection matters. See `references/cli-reference.md` for the helper invocation rules. - **Branch Discipline**: Protect default, shared, release, and production branches. Create focused task branches before editing when currently on a protected branch. - **Merges & Stacks**: For GitHub-backed repositories, merging implementation work means merging a Pull Request through GitHub. When the user approves a merge and does not specify the method, state that you are using a normal merge commit and run `scripts/gh-pr.py merge --method merge` for GitHub helper-backed merge execution. Do not locally merge a task branch into a protected, default, shared, release, or production branch as an implementation shortcut. Local branch integration is only appropriate for explicit local synchronization or stack maintenance, and the resulting implementation still lands through a PR. Do not use `--squash` or `--rebase` unless the user explicitly asks, repo policy requires it, or you ask and receive confirmation. For stacked PRs, consider a rollup branch when merging each layer would rerun expensive checks or create avoidable conflict churn, unless repo metadata or task context says Launchplane owns the merge train. In Launchplane-managed trains, do not hand-collapse stacks in GitHub; delegate stack handling to the `launchplane` workflow. - **Runtime-Bound Checkout Reconciliation**: After GitHub confirms a merge, keep the remote merge result separate from local runtime reconciliation. If the repository is bound into the active skills runtime, invoke the landed repo-local `scripts/reconcile-runtime-checkout.py` helper with the source worktree and full landing SHA. Use `merge.sha` from a successful direct merge or `mergeCommitOid` from a fresh merged-PR view; never substitute the PR head SHA. The helper may only fast-forward the resolved runtime checkout when it is clean, already on the configured default branch, and shares Git identity with the merged worktree. A blocked or failed local reconciliation never changes a confirmed remote merge into a failed merge and must never cause the merge to be retried. Report both outcomes and treat stale runtime-dependent evidence as unavailable until reconciliation or explicit source-revision verification succeeds. - **Local Default-Branch Freshness**: After every confirmed merge, inspect the repository's unique local default-branch worktree when one exists. Before evaluating or executing its refresh, read [post-merge checkouts](references/post-merge-checkouts.md), including the exact landing-SHA proofs and any explicitly requested untracked-only exception. If it is already the active checkout, assess it once. Apply refresh gates in this order: a runtime-bound checkout uses only the landed reconciler and stops; any tracked dirt or active Git operation is report-only and stops; only then may the explicitly requested untracked-only exception be considered. Runtime binding is absolute: explicit user intent and untracked-only dirt never make a runtime-bound checkout eligible for that exception. Never reset, stash, clean, or overwrite an unsafe checkout. If the reference's safety proofs fail, leave it untouched and report: `Local default checkout remains stale; fast-forward it before default-branch work or audits.` The active task worktree remains the authoritative agent source; a local refresh never silently replaces it with the default branch or a remote ref. - **Auto-Review Signals**: Before declaring a PR green, ready to merge, merged, releasable, or otherwise clean, check background auto-review evidence when it is available in the session context or repo tooling. First match each review target to the active branch/PR head SHA, for example `git rev-parse HEAD` for the active checkout or `gh pr view --json headRefOid` for a PR. Treat blocking findings against that current target as review feedback to address, explicitly defer, or decline with a recorded reason under `../references/model-review.md`; do not merge or release solely on CI-green when relevant current-target findings are still in-flight or unresolved. Findings whose branch/path points at a detached generated `auto-review-` worktree are still current-target findings when their snapshot SHA matches the active target. Detached generated auto-review findings whose snapshot SHA differs from the active target are external proposal history until verified against current `HEAD`. Detached auto-review worktrees remain external review context and should not be treated as dirty active worktree state. Use `../references/background-review-reporting.md` for point-in-time state and durable wording. If no matching lifecycle evidence is visible before a possible post-turn trigger, report `not yet observable`; never infer `skipped`, `not emitted`, or another terminal outcome from absence. Do not delay a final response solely waiting for that trigger. When later terminal evidence is observed, preserve the original point-in-time summary and add a follow-up. - **Accidental Local Default-Branch Merge Recovery**: If implementation work is accidentally merged into a protected/default/shared branch locally, preserve the commit or branch if needed, restore the local protected branch to the remote tip, push or update the task branch, and continue through the PR flow. Do not push the accidental local protected-branch merge. - **Cross-Repo PRs**: When creating a PR for a repository other than the current working directory, run `scripts/gh-with-env-token pr create` from that repository or pass both `--repo OWNER/REPO` and an explicit `--head` branch. - **Pre-Push Quality**: For code changes, use `jetbrains-inspection` to run targeted JetBrains inspections on changed files or touched directories before pushing a branch or updating a PR whenever the repo has an IDE project available. If `.github/github.json` defines `qualityGate.inspection`, PR creation/update, ready-to-merge claims, and merges must carry JetBrains evidence from the delegated helper or an explicit not-run reason. If that inspection config is blank, missing, contradictory, or surprising, do not silently invent repo policy: use a safe one-off `changed_files` check only when the helper can infer the correct route, and ask the user before changing durable config or treating a suspicious value as authoritative. If unavailable, record the not-run reason before pushing. - **Verification**: After merge, verify Actions and relevant security/quality signals before closing related planning state. - **Labels**: Use `github-plan` labels only for durable planning issues. For PR execution state, follow the repo workflow taxonomy in `references/repo-workflow.md`: `preview-ready` means a preview is available for review, `awaiting-qa` is an optional repo-local QA handoff label, and `ready-to-merge` is a configured merge readiness signal that still requires a fresh readiness check and merge authorization as defined in `../references/execution-scope.md`. - **Refs Closeout**: Treat `Refs #...` as intentionally non-closing. After the canonical PR merges, sweep referenced issues and close only those whose finish line is conclusively satisfied; otherwise comment/update durable state and leave them open. - **Human Comment Gate**: Before a merge or close settles an issue or PR, run `uv run ../github-work-rollup/scripts/github_unanswered_comments.py --thread OWNER/REPO#NUMBER`. Any attention result or degraded coverage requires a response or explicit handoff before the thread is settled; a bot response never proves owner acknowledgement. - **Handoffs**: For GitHub-backed work, put recovery-critical handoff content in the owning issue or PR comment. Local handoff files are scratch unless they are intentionally committed docs. - **Formatting**: From this repository root, use `github/scripts/gh-issue` for issue create/edit bodies and issue close comments, for example `github/scripts/gh-issue create "Issue title" --repo OWNER/REPO < body.md`. From inside this skill directory, use `scripts/gh-pr.py create --body-file` and `scripts/gh-pr.py edit --body-file` for PR bodies, `scripts/gh-pr.py comment --body-file` or `scripts/gh-comment pr` for PR timeline comments, and `scripts/gh-with-env-token pr review --body-file` for PR review feedback when no review helper exists. Avoid unquoted heredocs for Markdown bodies because shell command substitution runs inside backticks. Follow `../references/every-code-formatting.md` when writing durable PR, issue, review, or closeout text. - **PR Body Quality**: Preserve important existing PR body content, especially screenshots, images, and links that the author may not be able to recover. Explain why the change is being made before listing what changed. Describe the net change of the PR, not abandoned implementation attempts. Include purposeful verification evidence, but avoid padding the body with routine CI steps. Avoid absolute local paths; use repo-relative paths or GitHub links. Mention related issues or PRs when useful, and avoid self-references to the PR being edited. - **Bot Ownership**: Work performed by Code or spawned agents should be owned by the configured automation account in GitHub. Use `scripts/git-commit-as-bot` for commits, `scripts/git-push-as-bot` for pushes, helper-backed PR/issue/comment/merge flows for GitHub writes, and `scripts/gh-with-env-token` for unsupported raw `gh` surfaces such as API, review, workflow, release, and Actions commands. Do not let write actions fall back to the active human `gh` account unless the user explicitly approves that one-off and you set `GH_WITH_ENV_TOKEN_ALLOW_ACTIVE_AUTH_FALLBACK=1` for that command. - **Authentication**: The helpers own token selection, fallback behavior, consistent warnings, and parseable output. `scripts/gh-with-env-token` loads automation auth and fails closed without changing actor when bot auth is unavailable, rejected, or rate-limited. Active local `gh` auth is used only when the user explicitly approves the one-off and `GH_WITH_ENV_TOKEN_ALLOW_ACTIVE_AUTH_FALLBACK=1` is set. Use `scripts/gh-with-env-token --print-auth-account ...` when the acting account should be visible; it writes the account receipt to stderr so JSON stdout remains parseable. Security-sensitive automation-only helpers pass the wrapper prefix `--require-automation-auth`; shell callers may use the equivalent `GH_WITH_ENV_TOKEN_REQUIRE_AUTOMATION_AUTH=1`. Both take precedence over fallback settings loaded from the local env file. Configure the portable automation role with `CODEX_AUTOMATION_LOGIN` and `CODEX_AUTOMATION_EMAIL` in the ignored `local.env`; optionally set a quoted `CODEX_AUTOMATION_BOT_LOGINS` list for additional bot classification. The selected local env file is loaded after ambient variables and therefore wins when the same identity key is present in both places. - **Workflow Detail**: See `references/repo-workflow.md` for orientation, PR/check/review handling, and cleanup guardrails. - **PR Follow-through**: When PR diagnosis or an update/rebase/rerun/review-fix push leaves an open PR needing repeated CI, review, mergeability, or merged/closed polling, hand off to `babysit-pr` instead of continuing ad hoc polling in this skill. Use a `babysit-pr --once` snapshot for already merged/closed PR closeout evidence. - **Superseded PRs**: When multiple PRs target the same issue or workstream, pick a canonical PR, ensure stale PRs use `Refs` instead of closing keywords, comment with the winning PR, and close superseded PRs with `scripts/gh-pr.py supersede` when appropriate. Clean up unused remote task branches and local worker/review worktrees only under the shared repository cleanup policy after confirming the exact work disposition and that no active issue, PR, owner, or runtime still depends on them. ## Diagnostics & Hygiene - **CI Failure**: Use the `github-ci-diagnose.py` helper to classify and fix failures when available. Raw `gh run view` / `gh api` log commands are fallback diagnostics or watcher-specific probes, not the preferred path. - **Hygiene**: Use `github-repo-snapshot.sh` for situational snapshots. For ordinary task branch/worktree cleanup, an explicit bulk cleanup audit, or repository retirement, read [repository cleanup and preservation](../references/repo-cleanup.md) and apply its evidence, disposition, preservation, authorization, and reporting contract. ## Tools & Scripts Use the bundled scripts and the `commands` entries in this file's frontmatter (read the top of this `SKILL.md` if your host did not show them) for state, authentication, and writes. For an operation's arguments, transport, or response contract, read the relevant section of [CLI reference](references/cli-reference.md). Do not load unrelated command recipes or rebuild helper behavior in ad hoc code. Retry behavior is owned by `scripts/github_api.py` and `references/operation-matrix.toml`. Do not add ad hoc helper loops. A matrix row marked `safe` or `conditional` may retry only when the shared failure contract permits it; an absent or `manual` row performs one remote call and fails closed. Primary exhaustion waits for the reported reset plus bounded jitter, secondary throttling honors `Retry-After`, and all waits honor the earlier of the configured maximum and inherited request deadline. Concurrent helpers share `$CODE_HOME/state/github-retry` cooldowns by host, actor, and bucket. That same deadline bounds subprocesses, cooldown-lock acquisition, and reconciliation reads. Progress stays on stderr, provider bucket evidence is validated, actor changes require explicit authorization and begin a distinct retry context, and unknown non-idempotent outcomes must reconcile by operation marker plus a pre-write candidate snapshot. Create markers are unique per invocation and provider-visible in hidden HTML comments, so concurrent identical writes cannot claim one another; a unique new match is recovered and every other unknown outcome fails closed without replay. Legacy GraphQL failures lacking reset metadata use one bounded quota probe before waiting. ## Workflow Loop 1. **Orient**: Run `github-repo-snapshot.sh`; use `github-plan` if planning state matters. 2. **Plan**: Delegate durable planning to `github-plan`. 3. **Act**: Create a task branch, commit, and open a PR. 4. **Verify**: Address CI and review feedback using `github-ci-diagnose.py`. 5. **Close**: Merge, verify post-merge signals, use `github-plan` to sweep stale/duplicate/related planning issues, close or relabel reconciled issues, and clean up.