GitHub Issue Management Skill Skill

GitHub Issue Management Skill

This skill provides a structured approach to writing GitHub issues that communicate context, scope, and direction clearly.

Title Format (Required)

Issue titles must follow conventional commit format:

<type>(<scope>): <description>

Valid types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert

Examples:

feat(auth): add OAuth2 login support
fix(api): resolve race condition in request handler
chore(deps): update dependencies to latest versions
docs(readme): add installation instructions

The script validates this format automatically. Use --skip-validation only if the repository uses a different convention.

The Why/What/How Framework

Every issue should answer three questions for the reader:

Why does this matter?
What exactly needs to happen?
How should it be approached?

This framework ensures issues are actionable and provide enough context for anyone picking them up.

Issue Template

Why

Explain the background and motivation:

Current state: What exists today? How does it work?
Bottleneck/Problem: What specific issue or limitation was identified?
Value: Why is solving this valuable? What insights, metrics, or improvements does it unlock?

## Why

Currently, [describe current state/behavior].

This causes [specific problem or bottleneck], which [impact on users/system/workflow].

Addressing this will [concrete benefit - improved metrics, unlocked capabilities, better UX].

What

Define the scope concretely:

Specific deliverable: What exactly needs to be built, fixed, or changed?
Boundaries: What is explicitly out of scope?
Success criteria: How do we know when this is done?

## What

[Verb] [specific thing] to [achieve outcome].

Scope:
- [In scope item 1]
- [In scope item 2]

Out of scope:
- [Explicitly excluded item]

How

Provide implementation direction:

Approach: High-level strategy or pattern to follow
Key files/components: Where changes will likely occur
Architecture sketch: Skeleton of the solution structure (not implementation details)

## How

Approach: [brief strategy - e.g., "Extend existing X pattern", "Add new Y component"]

Key areas:
1. [Component/file] - [what changes here]
2. [Component/file] - [what changes here]

Skeleton:
- [High-level step 1]
- [High-level step 2]
- [Integration point]

Acceptance Criteria

Keep acceptance criteria focused on integration and observable behavior:

## Acceptance Criteria

- [ ] [Observable behavior or state that confirms completion]
- [ ] [Integration with existing system works as expected]
- [ ] [Edge case or error condition handled]

Tips:

Write criteria that can be verified by running the system
Focus on "what" not "how" - avoid implementation details
Include integration points with existing functionality

Testing Plan

Keep testing plans succinct and focused on verification:

## Testing Plan

- [ ] [How to manually verify the change]
- [ ] [Key integration scenario to test]
- [ ] [Regression check if applicable]

Tips:

Tests added should integrate within existing test architeture
Prioritize integration testing over isolated unit tests
Include the command or steps to run verification
Note any existing tests that should continue passing

Scripts Reference

This skill includes Python scripts in scripts/ that wrap GitHub API operations. Run them with uv:

Available Commands

| Command | Description | |---------|-------------| | create | Create a new issue | | create-sub | Create a sub-issue linked to a parent | | edit | Edit an existing issue's title or body | | view | View issue details | | list | List issues in a repository | | link | Link two issues (parent/child relationship) | | close | Close an issue | | comment | Add a comment to an issue | | labels | Manage issue labels | | init | Initialize an issue body file with template |

Usage Examples

# Initialize a template file
uv run scripts/gh_issue.py init --template default
uv run scripts/gh_issue.py init --template bug
uv run scripts/gh_issue.py init --template feature

# Create an issue from a body file
uv run scripts/gh_issue.py create owner/repo \
  --title "Brief, descriptive title" \
  --body-file /tmp/issue-body.md

# Create with labels and assignees
uv run scripts/gh_issue.py create owner/repo \
  --title "Add caching layer" \
  --body-file /tmp/issue-body.md \
  --labels "enhancement,performance" \
  --assignees "@me"

# Create a sub-issue linked to parent
uv run scripts/gh_issue.py create-sub owner/repo \
  --parent 10 \
  --title "Implement caching middleware" \
  --body-file /tmp/sub-issue.md

# Edit an issue's body
uv run scripts/gh_issue.py edit owner/repo 123 \
  --body-file /tmp/updated-body.md

# Edit an issue's title
uv run scripts/gh_issue.py edit owner/repo 123 \
  --title "feat(api): updated title"

# View an issue
uv run scripts/gh_issue.py view owner/repo 123

# List open issues
uv run scripts/gh_issue.py list owner/repo

# List issues by label
uv run scripts/gh_issue.py list owner/repo --labels "bug"

# Link existing issues
uv run scripts/gh_issue.py link owner/repo --parent 10 --child 42

# Add a comment
uv run scripts/gh_issue.py comment owner/repo 123 "Progress update: ..."

# Close an issue
uv run scripts/gh_issue.py close owner/repo 123 --reason completed

Creating Issues

Preview Before Creation

By default, the script shows a preview and asks for confirmation before creating:

============================================================
ISSUE PREVIEW
============================================================

Repository: owner/repo
Title: feat(api): add caching to API responses
Labels: enhancement, performance

Body:
----------------------------------------
## Why
...
----------------------------------------

Create this issue?
  y = create issue
  n = cancel
  e = edit (saves to /tmp/issue-body.md for editing)

Press y to create the issue
Press n to cancel
Press e to save body to /tmp/issue-body.md for editing, then re-run

Use --yes or -y to skip confirmation (for automation).

Basic Creation

# Initialize template
uv run scripts/gh_issue.py init --output /tmp/issue-body.md

# Edit the template with your content
# ... edit /tmp/issue-body.md ...

# Create the issue (will show preview first)
uv run scripts/gh_issue.py create owner/repo \
  --title "feat(api): add caching layer" \
  --body-file /tmp/issue-body.md

With Labels and Assignment

uv run scripts/gh_issue.py create owner/repo \
  --title "feat(api): add caching layer to API responses" \
  --body-file /tmp/issue-body.md \
  --labels "enhancement,performance" \
  --assignees "@me" \
  --milestone "v2.0"

Adding to a Project

uv run scripts/gh_issue.py create owner/repo \
  --title "Issue title" \
  --body-file /tmp/issue-body.md \
  --project "Project Name"

Linking Issues

Create a Sub-issue

# Create a new issue linked to parent #10
uv run scripts/gh_issue.py create-sub owner/repo \
  --parent 10 \
  --title "feat(cache): implement caching middleware" \
  --body "## Why
Part of the caching initiative (#10).

## What
Implement the middleware layer for request caching."

Link Existing Issues

# Link issue #42 as a sub-issue of #10
uv run scripts/gh_issue.py link owner/repo --parent 10 --child 42

Close Issue via Commit

Reference the issue number in a commit message to auto-close:

git commit -m "Add caching middleware

Fixes #42"

Keywords that close issues: fixes, closes, resolves (followed by #issue_number)

Quick Reference

| Task | Command | |------|---------| | Init template | uv run scripts/gh_issue.py init | | Init bug template | uv run scripts/gh_issue.py init --template bug | | Create issue | uv run scripts/gh_issue.py create owner/repo --title "feat(scope): description" --body-file /tmp/issue.md | | Create (skip preview) | uv run scripts/gh_issue.py create owner/repo --title "..." --body-file ... --yes | | Create sub-issue | uv run scripts/gh_issue.py create-sub owner/repo --parent 10 --title "feat(scope): ..." | | Edit issue body | uv run scripts/gh_issue.py edit owner/repo 123 --body-file /tmp/updated.md | | Edit issue title | uv run scripts/gh_issue.py edit owner/repo 123 --title "feat(scope): new title" | | View issue | uv run scripts/gh_issue.py view owner/repo 123 | | List issues | uv run scripts/gh_issue.py list owner/repo | | Link issues | uv run scripts/gh_issue.py link owner/repo --parent 10 --child 42 | | Add comment | uv run scripts/gh_issue.py comment owner/repo 123 "message" | | Add labels | uv run scripts/gh_issue.py labels owner/repo 123 --add "bug,urgent" | | Close issue | uv run scripts/gh_issue.py close owner/repo 123 |

Agent Skills: GitHub Issue Management Skill

Skill Files