GitHub Issue Writing

Create well-structured, actionable GitHub issues.

When to Use This Skill

Issue Title Format

[Type] Component: Brief description

Guidelines:

• Be specific (not "Bug" but "Login fails with OAuth")
• Include component for triage
• Keep under 72 characters

Bug Report Template

## Summary
Brief description of the bug.

## Steps to Reproduce
1. Go to '...'
2. Click on '...'
3. See error

## Expected Behavior
What should happen.

## Actual Behavior
What actually happens.

## Environment
- OS: macOS 14.0
- Browser: Chrome 120
- Version: 2.1.0

Feature Request Template

## Summary
What this feature does.

## Motivation
Why this is needed. What problem does it solve?

## Proposed Solution
Description of desired behavior.

## Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Criterion 3

Issue Types

GitHub supports first-class issue types. Use --type when creating issues:

Note: Available types depend on repository/org configuration. Use gh issue create --type "Bug" to leverage them.

Body Content: Use --body-file

For any non-trivial body — anything containing backticks, code fences, or multi-line content — use --body-file <path>, never --body "<text>". This applies to all gh commands that accept a body: gh issue create, gh issue edit, gh issue comment, gh pr create, gh pr edit, gh pr comment.

When to use which

Why

Shell-quoted --body strings escape backticks (` becomes \`), breaking inline code spans and triple-backtick code fences in the rendered issue. Bash heredocs interact unpredictably with the agent's argument escaping. Writing the markdown to a file with the Write tool sidesteps shell quoting entirely — the file content is preserved byte-for-byte.

Pattern

1. Write tool → /tmp/issue-body.md   (markdown body, no shell escaping)
2. gh issue create --title "..." --body-file /tmp/issue-body.md

The same --body-file <path> form is supported by every gh command that accepts a body.

CLI Commands

# Create issue with a body file (preferred for any non-trivial body)
gh issue create --title "[Bug] Auth: Login fails" --body-file /tmp/issue-body.md

# Trivially short body — inline --body is acceptable
gh issue create --title "[Chore] Bump dep" --body "See renovate PR"

# With labels
gh issue create --title "..." --body-file /tmp/body.md --label "bug" --label "priority: high"

# With assignee
gh issue create --title "..." --body-file /tmp/body.md --assignee "@me"

# With issue type
gh issue create --title "..." --body-file /tmp/body.md --type "Bug"

# As sub-issue of a parent
gh issue create --title "..." --body-file /tmp/body.md
gh api repos/{owner}/{repo}/issues/{parent}/sub_issues -f sub_issue_id={new_id}

# Search before creating
gh issue list --search "login error" --state all

Linking Issues

Pick the mechanism that matches the relationship — GitHub surfaces each one differently and only the native APIs trigger "Blocked" badges on project boards.

Do not write Blocks #123 or Blocked by #456 in issue bodies any more — those strings used to be GitHub's workaround for missing dependency APIs, but they are no longer parsed. Call /git:issue-hierarchy (or the REST endpoints at issues/{N}/dependencies/blocked_by) so the relationship shows up in the sidebar and on project boards.

Quick Reference

Agentic Optimizations