Skip to main content
skill CX Codex

resolve-issues — Claude Code skill: GitHub issues

resolve-issues — a skill for Claude Code handles GitHub issues with an isolated worktree and TDD. It then hands PR creation to the project’s quality and review workflow.

MIT 112 installs ★ 597 updated 2026-11-06

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add FradSer/dotclaude --skill resolve-issues -a claude-code
Open on GitHub

What resolve-issues does

resolve-issues runs on Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode. It selects an issue, creates a separate worktree, and renames the branch according to the project convention. Implementation follows a TDD loop: add a failing test, make it pass with the smallest change, then refactor.

Once the fix is ready, the branch is pushed to the remote. PR creation goes through github:create-pr, while github:review-pr owns the review flow, quality gate, and issue linkage through an auto-closing keyword. The skill explicitly forbids a direct gh pr create call, so its standard path keeps those checks in place.

Worktree cleanup happens after the PR has actually merged. If uncommitted changes remain, ExitWorktree requires confirmation before removal.

What it helps with

  • select a GitHub issue and create an isolated worktree
  • write failing tests that capture the issue criteria
  • implement the fix through the red → green → refactor cycle
  • hand the finished branch to the PR and review workflow
  • remove the worktree after the PR merges

Example prompts for the agent

  • Resolve issue #123 from its acceptance criteria in an isolated worktree.
  • Fix the GitHub issue about the auth redirect with TDD, then hand the branch to github:create-pr.
  • Work through this GitHub ticket, run the validation checks, and prepare the branch for review.

How to install resolve-issues

1Skills CLI (Vercel)

npx skills add FradSer/dotclaude --skill resolve-issues -a claude-code

2Manually: put the files in place

~/.claude/skills/resolve-issues/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/resolve-issues/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about resolve-issues

How do I install resolve-issues in Claude Code?

Run npx skills add FradSer/dotclaude --skill resolve-issues -a claude-code, then check ~/.claude/skills/resolve-issues/SKILL.md.

What does resolve-issues do?

The skill resolves a GitHub issue in an isolated worktree using a TDD cycle. It then delegates PR creation to github:create-pr and review to github:review-pr.

Why does resolve-issues avoid gh pr create?

github:create-pr is the skill’s required PR path. It preserves the quality gate, issue linkage, and handoff to github:review-pr.

Source text

SKILL.md · MIT
---
name: resolve-issues
allowed-tools: Bash(gh:*), Bash(git:*), EnterWorktree, ExitWorktree, Task, Skill
description: Resolves GitHub issues using isolated worktrees and test-driven development, then delegates PR creation to /github:create-pr so the quality gate and the /github:review-pr loop always run. This skill should be used when the user asks to "resolve an issue", "fix issue #123", or needs to implement a solution for a specific GitHub ticket using a structured workflow.
argument-hint: [issue number or description]
user-invocable: true
---

# Resolve GitHub Issues

Execute issue resolution workflow using isolated worktrees, TDD methodology, and agent collaboration.

## Context

- Current git status: !`git status`
- Current branch: !`git branch --show-current`
- Existing worktrees: !`git worktree list`
- Open issues: !`gh issue list --state open --limit 10`
- GitHub authentication: !`gh auth status`

## Requirements Summary

Use isolated worktrees to avoid disrupting main development. Follow TDD cycle (red → green → refactor) with agent support. Reference issues in commits using auto-closing keywords. See `references/requirements.md` for protected PR workflow and commit standards.

## Phase 1: Issue Selection and Worktree Setup

**Goal**: Select target issue and prepare isolated development environment.

**Actions**:
1. Review open issues from context and select based on priority and `$ARGUMENTS`
2. Check existing worktrees to determine if reuse is possible
3. Use the EnterWorktree tool with a descriptive name (e.g., `fix-456-auth-redirect`) to create an isolated session
4. Rename the auto-generated branch to match conventions: run `git branch -m <type>/<issue>-<description>` (see `references/workflow-details.md` for naming)
5. Verify issue acceptance criteria and dependencies

## Phase 2: TDD Implementation

**Goal**: Implement fix using test-driven development with agent collaboration.

**Actions**:
1. Plan implementation approach and assess architectural impact
2. Write failing tests that verify issue is resolved (RED phase)
3. Implement minimal code to make tests pass (GREEN phase)
4. Refactor while keeping tests green (REFACTOR phase)
5. Run quality validation commands to keep the TDD cycle honest (see `references/workflow-details.md` for project-specific checks). `/github:create-pr` re-runs the full gate in Phase 3 and is the authoritative pre-PR check.

## Phase 3: PR Creation and Cleanup

**Goal**: Hand PR creation to `/github:create-pr` so the quality gate and the review loop run. Cleanup happens only after the merge, which may be many turns later.

**Actions**:
1. Push branch to remote with `git push -u origin <branch-name>`
2. **CRITICAL: Do NOT call `gh pr create` here.** Invoke `Skill("github:create-pr", "<issue reference>")` — e.g. `Skill("github:create-pr", "Closes #456")`. It is the plugin's only PR-creating path and owns the quality/security gate, the auto-closing-keyword linkage, the non-default-branch warning, and the mandatory `/github:review-pr` handoff. See `references/pr-creation-handoff.md` for the full contract. Creating the PR directly skips all of it.
   - Append `--draft` to the arguments if the fix requires further feedback before review
   - Append `--no-monitor` only when the user explicitly opts out of the review loop
3. **This skill does not resume here.** `/github:create-pr` reports the PR URL, and `/github:review-pr` then owns the PR for the rest of its life: a persistent Monitor spanning turns, the triage/fix/push rounds, and the merge decision it asks the user to make. Do NOT wait inline, do NOT re-report the URL, and do NOT run Phase 4 speculatively.

## Phase 4: Post-Merge Cleanup (later turn, fallback)

**Trigger**: The PR from Phase 3 has actually merged — normally a later turn, after `/github:review-pr` completed its merge decision. **`/github:review-pr`'s closeout now owns the post-merge cleanup** (worktree removal via `ExitWorktree action:"remove"`, switch to `main`, sync with origin), so this Phase runs only as a **fallback** when that cleanup was skipped: the user chose "Don't merge", an interrupt left the worktree behind, or this is a fresh session that cannot `ExitWorktree` the worktree created by an earlier session. Never assume the worktree is gone — verify first.

**Actions**:
1. Verify the merge with `gh pr view <PR#> --json state -q .state` returning `MERGED`; never assume.
2. Check `git worktree list` whether the issue worktree still exists. If `/github:review-pr` already removed it, skip straight to `git fetch --prune`.
3. If it persists: **CRITICAL: confirm still on the issue branch** before `ExitWorktree action:"remove"`. If checkout drifted onto `main`/`develop`, stop — removing would delete a long-lived branch. Remote head may already be gone; that is fine.
4. Use the ExitWorktree tool with action "remove" to clean up worktree and branch.
   - If uncommitted changes exist, ExitWorktree refuses; confirm with the user before setting `discard_changes: true`
5. `git fetch --prune` to sync remote-tracking branches.
6. Document resolution and any follow-up tasks

## References

- **Requirements**: `references/requirements.md` - Worktree setup, TDD, and commit standards
- **PR Creation Handoff**: `references/pr-creation-handoff.md` - Why PRs delegate to /github:create-pr
- **Workflow Details**: `references/workflow-details.md` - Issue selection, TDD cycle, agent collaboration
- **Quality Validation**: `references/quality-validation.md` - Node.js/Python validation commands (shared)
- **Examples**: `references/examples.md` - Commit message examples

© FradSer · MIT · FradSer/dotclaude

Similar skills

All skills for Git and GitHub →

From the same set16

The whole set →
plugin-best-practices plugin-best-practices validates Claude Code plugin structure, manifests, and architecture against framework standards. Ensures your plugin meets requirements before marketplace submission. CX Codex +1 121installs commit This skill creates atomic conventional commits through git-agent. Use it when a short intent should become a focused Git commit. CX Codex +1 121installs optimize-plugin optimize-plugin validates Claude plugin structure, runs Python sanity checks, and fixes issues via a subagent. Useful when auditing or refactoring plugin manifests and components. CX Codex +1 117installs create-prd The create-prd skill turns product ideas into a structured PRD through a guided interview, then saves it as Markdown or creates a Feishu document. CX Codex +1 117installs create-issues create-issues automates GitHub issue creation with TDD principles, proper labeling, and auto-closing keywords. Detects repository templates, applies conventions, and links issues to epics or related tasks. CX Codex +1 116installs best-practices best-practices enforces language-specific standards and framework rules for TypeScript, Python, Go, Swift, and React. CX Codex +1 115installs refactor Runs automated code refactoring on specified files, directories, or recent git modifications. CX Codex +1 113installs create-pr The create-pr skill opens GitHub pull requests after quality and security checks, then hands them to CI monitoring and reviewer-comment triage. CX Codex +1 109installs

Project sponsors

Companies that keep this analytics open