Back to Workflow & Productivity
gh-issue-fix-flow
GitHubgh CLIissue managementbug fixworkflow automationgit commandsdevelopmentXcodeBuildMCP
Install this skill
npx skills add dimillian/skillsWorks across Claude Code, Cursor, Codex, Copilot & Antigravity
The gh-issue-fix-flow skill provides a structured method for resolving GitHub issues within Apple-centric development environments. It orchestrates the entire lifecycle of a bug fix, starting with retrieving remote issue details via the GitHub CLI and concluding with a version-controlled push. By integrating git operations with the XcodeBuildMCP protocol, the skill ensures that changes remain consistent with project conventions while validating fixes through targeted simulator or macOS builds. This workflow enforces discipline by requiring specific commit syntax that closes remote issues automatically and mandates clear reporting of test outcomes. It is intended for developers who require a repeatable, systematic approach to incident remediation without deviating from standard repository patterns or failing to document the impact of their modifications to the codebase.
When to Use This Skill
- •Resolving documented bug reports in an iOS or macOS codebase
- •Addressing maintenance requests flagged in GitHub issues
- •Performing surgical code edits verified by local unit tests
- •Automating the transition from issue intake to verified commit
How to Invoke This Skill
Example prompts that trigger this skill in Claude Code, Cursor, or Antigravity:
- “Follow the issue fix workflow for issue #123
- “Start the gh-issue-fix-flow to resolve ticket 45
- “Guide me through fixing the reported issue in this repo
- “Execute the full issue fix procedure for the current bug
- “Help me fix this issue using the standard issue-fix flow
Pro Tips
- 💡Before starting, ensure your local `gh` CLI is authenticated and configured for the target repository.
- 💡Prioritize adding minimal, focused tests specifically for the bug fix or new behavior.
- 💡Use the `gh pr create --issue <id>` command after pushing your fix to automatically link your branch to the issue.
What this skill does
- •Fetches issue descriptions and comment history directly from GitHub
- •Navigates local codebases using ripgrep for precise file targeting
- •Executes project builds and test suites using XcodeBuildMCP sessions
- •Validates fixes via targeted simulator or macOS-native test schemes
- •Generates standardized git commits linked to issue identifiers
When not to use it
- ✕When working in non-Apple development environments lacking Xcode projects
- ✕For massive architectural refactors that extend beyond single issue resolution
- ✕If the repository prohibits CLI-based issue modification or automated pushes
Example workflow
- Run gh issue view to pull context and requirements
- Search for the relevant code area using rg
- Apply the minimal code changes required for the fix
- Run mcp__XcodeBuildMCP__test_sim to verify the behavior
- Stage files, commit with 'Fix ... (closes #ID)', and push
Prerequisites
- –GitHub CLI (gh) installed and authenticated
- –XcodeBuildMCP configured for the project
- –Repository access with git write permissions
Pitfalls & limitations
- !Deployment target mismatches between local env and project requirements
- !Including unrelated file changes in the final commit
- !Neglecting to report test failures or warnings in the final summary
FAQ
Do I need to manually configure XcodeBuildMCP every time?
No, you only need to run the session-set-defaults once per project environment.
What happens if my macOS tests fail?
The workflow directs you to try iOS simulator tests as an alternative to check for deployment target mismatches.
Can I use this for features or only bug fixes?
While intended for issues, the flow is applicable to any task-based development that requires tracking and verification.
How it compares
Unlike a generic prompt that might suggest disparate commands, this skill enforces a specific sequence that links GitHub issue states to verified local builds, ensuring consistency in every commit.
📄 Full skill instructions — original source: dimillian/skills
# Gh Issue Fix Flow
## Overview
Resolve a GitHub issue from intake through fix, validation, and push using gh, local edits, XcodeBuildMCP, and git.
## Workflow
### 1) Intake and issue context
1. Use
2. If the repo is unclear, run
3. Capture reproduction steps, expected behavior, and any maintainer notes.
### 2) Locate the code path
1. Use
2. Read the relevant code paths with
3. Follow repo-specific conventions (AGENTS/CLAUDE instructions).
### 3) Implement the fix
1. Edit the minimal set of files.
2. Keep changes aligned with existing architecture and style.
3. Add tests when behavior changes and test coverage is practical.
### 4) Build and test
1. Use XcodeBuildMCP for required builds/tests:
- Set defaults once:
- Build:
- Tests: prefer targeted schemes (e.g.,
2. If macOS tests fail due to deployment target mismatches, run the equivalent iOS simulator tests.
3. Report warnings or failures; do not hide them.
### 5) Commit and push
1. Check for unrelated changes with
2. Stage only the fix (exclude unrelated files).
3. Commit with a closing message:
4. Push with
### 6) Report back
1. Summarize what changed and where.
2. Provide test results (including failures).
3. Note any follow-ups or blocked items.
## Overview
Resolve a GitHub issue from intake through fix, validation, and push using gh, local edits, XcodeBuildMCP, and git.
## Workflow
### 1) Intake and issue context
1. Use
gh issue view <id> --repo <owner/repo> --comments to get the full issue context.2. If the repo is unclear, run
gh repo view --json nameWithOwner to confirm.3. Capture reproduction steps, expected behavior, and any maintainer notes.
### 2) Locate the code path
1. Use
rg -n to locate likely files and entry points.2. Read the relevant code paths with
sed -n or rg -n context.3. Follow repo-specific conventions (AGENTS/CLAUDE instructions).
### 3) Implement the fix
1. Edit the minimal set of files.
2. Keep changes aligned with existing architecture and style.
3. Add tests when behavior changes and test coverage is practical.
### 4) Build and test
1. Use XcodeBuildMCP for required builds/tests:
- Set defaults once:
mcp__XcodeBuildMCP__session-set-defaults.- Build:
mcp__XcodeBuildMCP__build_macos or mcp__XcodeBuildMCP__build_sim.- Tests: prefer targeted schemes (e.g.,
mcp__XcodeBuildMCP__test_sim).2. If macOS tests fail due to deployment target mismatches, run the equivalent iOS simulator tests.
3. Report warnings or failures; do not hide them.
### 5) Commit and push
1. Check for unrelated changes with
git status --short.2. Stage only the fix (exclude unrelated files).
3. Commit with a closing message:
Fix … (closes #<issue>).4. Push with
git push.### 6) Report back
1. Summarize what changed and where.
2. Provide test results (including failures).
3. Note any follow-ups or blocked items.
How to Use This Skill Unit
Option A: Project-Specific (Recommended)
- Click "Download" above
- In your project, create the directory:
.agent/skills/gh-issue-fix-flow/ - Save the file as
SKILL.md - The agent will automatically discover the skill based on its description.
Option B: Global Installation (All Agents)
Save the file to these locations to make it available across all projects:
- Claude Code:
~/.claude/skills/dimillian/skills/gh-issue-fix-flow/SKILL.md - Cursor:
~/.cursor/skills/dimillian/skills/gh-issue-fix-flow/SKILL.md - Antigravity:
~/.gemini/antigravity/skills/dimillian/skills/gh-issue-fix-flow/SKILL.md
🚀 Install with CLI:npx skills add dimillian/skills
Recommended Rules
View more rules →Python AI/ML Development Expert
PythonAIMachine Learning
You are an expert in Python, AI, and Machine Learning development. Key Principles: - Write clean, efficient, and well-documented code - Follow PEP 8 ...
Python Backend Development with FastAPI
PythonFastAPIBackend
You are an expert in Python backend development with FastAPI. Key Principles: - Write async code when possible - Use Pydantic for data validation - I...
Python REST API Development Expert
PythonREST APIFastAPI
You are an expert in Python REST API development with FastAPI, Flask, and Django REST Framework. Key Principles: - Follow RESTful design principles -...
Recommended Workflows
View more workflows →Create GitHub PR Template
GitGitHubTeam
--- description: Standardize pull request descriptions for better code reviews --- 1. **Create Template Directory**: - GitHub looks for templates ...
Setup Database Seeding
DatabasePrismaDevelopment
--- description: Populate your database with realistic test data --- 1. **Install Faker**: - Generate realistic fake data. // turbo - Run `n...
Automatic commit message generator
GitAIAutomation
--- description: Automatic commit message generator and fast AI-powered commit for all current changes --- // turbo-all This workflow automatically ...
