Gh Issues
Fetch GitHub issues, select candidates, spawn background fix agents, open PRs, and optionally process PR review comments.
Get the complete skill folder, including its scripts and reference files.
When to use this skill
Use Gh Issues when an AI agent needs a reusable SKILL.md workflow for this job: Fetch GitHub issues, select candidates, spawn background fix agents, open PRs, and optionally process PR review comments.
When not to use it
Skip Gh Issues when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.
How to install
Where will you use it?
mkdir -p ~/.claude/skills/gh-issues # Save SKILL.md to ~/.claude/skills/gh-issues/SKILL.md
- Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/gh-issues/SKILL.md. For a shared project, commit the folder at .claude/skills/gh-issues/ instead.
- Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
- For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.
Full install guide for Claude, Cursor, and Codex →
Try a starter prompt
After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.
Use the Gh Issues skill for this task: Use Gh Issues when this documented workflow matches the task. Confirm any required inputs or files before making changes.
What supports this recommendation?
69/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.
- Documentation
- 72/100
- Practical detail
- 68/100
- Source evidence
- 63/100
- Source signals
- 70/100
Model compatibility evidence
- claudeuntested
No model-specific signal or recorded compatibility test was found.
- chatgptuntested
No model-specific signal or recorded compatibility test was found.
- geminiuntested
No model-specific signal or recorded compatibility test was found.
- copilotuntested
No model-specific signal or recorded compatibility test was found.
- llamauntested
No model-specific signal or recorded compatibility test was found.
- perplexityuntested
No model-specific signal or recorded compatibility test was found.
- mistraluntested
No model-specific signal or recorded compatibility test was found.
- grokuntested
No model-specific signal or recorded compatibility test was found.
Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.
What this skill does
# gh-issues
Use for issue-to-PR automation. Prefer `gh` CLI; fall back to `gh api` only when a high-level command lacks the needed field.
## Arguments
- positional `owner/repo`: optional; else infer from `git remote get-url origin`. - `--label <label>`: filter. - `--limit <n>`: default 10. - `--milestone <title>`: filter. - `--assignee <login|@me>`: filter. - `--state open|closed|all`: default open. - `--fork <owner/repo>`: push branches to fork, PR to source. - `--watch`: poll issues + reviews. - `--interval <minutes>`: default 5. - `--dry-run`: list only. - `--yes`: no confirmation. - `--reviews-only`: skip issue fixing; handle PR reviews. - `--cron`: spawn and exit; implies `--yes`. - `--model <id>`: pass to workers when supported. - `--notify-channel <id>`: optional final notification target.
## Phase 1: resolve repo
```bash git remote get-url origin if [ -z "${GH_TOKEN:-}" ]; then CONFIG_PATH="${OPENCLAW_CONFIG_PATH:-${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/openclaw.json}" GH_TOKEN=$(jq -r '.skills.entries["gh-issues"].apiKey // empty' "$CONFIG_PATH" 2>/dev/null || true) if [ -n "$GH_TOKEN" ]; then export GH_TOKEN; fi fi gh auth status gh repo view OWNER/REPO --json nameWithOwner,defaultBranchRef ```
If `gh auth status` fails and `GH_TOKEN` is missing, stop and ask for GitHub auth/config.
Derived:
- `SOURCE_REPO`: issue repo. - `PUSH_REPO`: fork if set, else source. - `BASE_BRANCH`: source default branch unless user says otherwise. - `PUSH_REMOTE`: `fork` in fork mode, else `origin`.
Stop on dirty worktree unless user confirms that workers should ignore uncommitted changes.
In fork mode, do not mutate remotes before confirmation or during `--dry-run`.
Verify auth/read access only:
```bash gh auth token >/dev/null || test -n "${GH_TOKEN:-}" gh repo view "$PUSH_REPO" --json nameWithOwner git ls-remote --exit-code origin HEAD ```
## Phase 2: fetch issues
Build filters and fetch:
```bash gh issue list --repo "$SOURCE_REPO" --state open --limit 10 --json number,title,labels,url,body,assignees,milestone ```
Add `--label`, `--milestone`, `--assignee`, `--state`, `--limit` as requested. `gh issue list` already excludes PRs.
If none found: report no matches. If `--dry-run`: show compact list and stop.
## Phase 3: avoid duplicate work
For each candidate:
```bash gh pr list --repo "$SOURCE_REPO" --search "$SOURCE_REPO#<n>" --state open --json number,url,title,headRefName gh pr list --repo "$SOURCE_REPO" --head "fix/issue-<n>" --state open --json number,url gh api "repos/$PUSH_REPO/branches/fix/issue-<n>" >/dev/null ```
Skip candidates with an open PR, existing branch, or active local claim.
Claim file:
```text ${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/gh-issues-<owner>-<repo>.json ```
Expire claims older than 2 hours. Create the parent directory before writing.
## Phase 4: confirm
Unless `--yes` or `--cron`, ask user to choose:
- `all` - comma-separated issue numbers - `cancel`
After confirmation, in fork mode, configure the push remote before handing work to agents:
```bash gh auth setup-git git remote get-url fork || git remote add fork "https://github.com/$PUSH_REPO.git" git remote set-url fork "https://github.com/$PUSH_REPO.git" git ls-remote --exit-code fork HEAD ```
## Phase 5: spawn workers
Launch up to 8 background workers. Do not block on each worker when `--cron`.
Before each spawn, write a claim for `SOURCE_REPO#<n>` with the current ISO timestamp. After a worker reports PR/failure, remove or update the claim. This prevents watch/cron overlap before a branch or PR exists.
Worker prompt must include:
- issue URL, title, body, labels. - `SOURCE_REPO`, `PUSH_REPO`, `BASE_BRANCH`, `PUSH_REMOTE`, fork mode. - target branch `fix/issue-<n>`. - required proof and PR body. - notification route.
Worker instructions:
```text Use gh and git. Do not handwave. Checkout/create fix/issue-<n> from BASE_BRANCH. Implement minimal fix. Run relevant tests. Commit with conventional message. Push to PUSH_REMOTE. Open PR against SOURCE_REPO BASE_BRANCH. PR body: What Problem This Solves + Why This Change Was Made + User Impact + Evidence + visible Fixes SOURCE_REPO#<n>. Report PR URL or failure reason. Send completion/failure with openclaw message send if route provided. ```
Use `coding-agent` launch rules when available.
## Phase 6: collect
Poll workers with `process` or task registry. Report:
- issue number + title. - status: PR opened, skipped, failed, timed out. - PR URL or reason.
Notify channel only with final compact summary.
## Reviews-only / watch reviews
Discover open PRs:
```bash gh pr list --repo "$SOURCE_REPO" --state open --json number,title,url,headRefName,reviewDecision \ --jq '[.[] | select(.headRefName | startswith("fix/issue-"))]' ```
Fetch review threads/comments:
```bash gh pr view <n> --repo "$SOURCE_REPO" --json url,headRefName,comments,reviews gh api "repos/$SOURCE_REPO/pulls/<n>/comments" gh api "repos/$SOURCE_REPO/issues/<n>/comments" ```
Only process `fix/issue-*` PRs created by this workflow unless the user explicitly named PR numbers. Group actionable comments by PR. Ignore praise, status, duplicates, and already-addressed comments. Spawn one worker per selected/scoped PR, same background rules.
Review worker instructions:
```text Checkout PR branch. Read all actionable review comments. Patch minimal changes. Run relevant tests. Commit and push normally; do not force-push unless explicitly told. Reply to addressed comments with fix + commit/file reference. Report comments addressed/skipped and proof. ```
## Watch mode
Loop:
1. Fetch issues. 2. Spawn eligible issue workers. 3. Process actionable PR reviews. 4. Sleep `--interval`. 5. Stop when user says stop.
Keep cumulative summary small.
Intended uses
- Use Gh Issues when this documented workflow matches the task.
Implementation notes
- Review the source instructions and adapt inputs before running the workflow.
Try it, then tell us how it went
A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.