gh-expert
Guides coding agents through the standard workflow for working on GitHub issues and moving them to completed pull requests using the 'gh' CLI.
SKILL.mdskills/gh-expert/SKILL.md
GitHubGitHub Expert Workflow
This skill provides a structured process for contributing to projects via GitHub Issues and Pull Requests. It ensures clear communication, visibility, and high-quality contributions by following a strict sequential workflow.
Quick Reference
For detailed command usage and flag options, refer to:
- workflow.md - Project-specific workflow rules.
- gh_help.md - GitHub CLI command reference.
1. Discovery and Claiming
All work must begin with an existing GitHub Issue.
- Find an issue: Use
gh issue listto find tasks. - Review details: Use
gh issue view <number>to understand requirements. - Claim it: Use
gh issue edit <number> --add-label "claimed"before starting work.
2. Branching and PR Initialization
Never work directly on main. Create a draft PR early to signal active work.
- Create branch:
git checkout -b <branch-name>(use descriptive names likefeature/orfix/). - Initial commit:
git commit --allow-empty -m "Initial commit for issue #<number>" - Push branch:
git push -u origin <branch-name> - Create Draft PR:
gh pr create --title "Work on #<number>: <description>" --body "Closes #<number>" --draft
3. Planning with TODO.md
Create a TODO.md file in the root directory to track granular tasks. This file is the primary source of truth for the branch's progress.
- Define tasks: List specific, actionable steps with Markdown checkboxes (
- [ ]). - Commit plan:
git add TODO.md && git commit -m "Add implementation plan (TODO.md)" && git push
4. Implementation (In Progress)
Transition the issue and start coding.
- Mark in-progress:
gh issue edit <number> --add-label "in-progress" - Iterate:
- Work on tasks.
- Update
TODO.md(check off completed items). - Commit frequently with clear messages.
- Push to remote regularly.
5. Completion and Review
Finalize the work and request a review.
- Validate: Run all project tests and ensure they pass.
- Document: Update the Pull Request description with a detailed summary of changes, implementation details, and test results.
gh pr edit --body "## Summary Brief description of changes. ## Changes - Detail 1 - Detail 2 ## Testing - [x] Unit tests passed - [x] Integration tests passed" - Clean up: Remove
TODO.mdbefore merging.rm TODO.md git add TODO.md git commit -m "Remove TODO.md before PR review" git push - Mark Ready:
gh pr ready - Request Review:
gh pr edit --add-reviewer <username>(if applicable).
Best Practices
- Atomic Commits: Keep commits focused and descriptive.
- Stay Updated: Regularly pull from the base branch to avoid conflicts.
- Close Issues: Ensure the PR body contains "Closes #<number>" to automate issue closure.