GitHub Issue Creation

Use this skill to create a well-defined GitHub issue with a consistent structure: clear title, problem context, explicit acceptance criteria, and out-of-scope boundaries. The issue body is crafted before calling gh , so the user can review it first.

Prerequisites

gh auth status # must be authenticated gh repo view # must be inside a git repo with a GitHub remote

If either fails, stop and tell the user what to fix before continuing.

Information to Gather

Before drafting the issue, collect the following. Ask for anything missing — do not invent it.

Field What to ask

Type Bug, feature, chore, or docs?

Title One-line summary (imperative mood: "Add …", "Fix …", "Remove …")

Problem / motivation What's broken or missing, and why does it matter?

Acceptance criteria What must be true for this issue to be closed?

Out of scope What related things will not be addressed? (optional but valuable)

Technical notes Known constraints, relevant files, dependencies (optional)

Labels Defaults suggested below; ask user to confirm or override

Assignee Leave blank unless user specifies

Milestone Leave blank unless one exists (gh milestone list )

Deriving Acceptance Criteria

If the user hasn't provided acceptance criteria, derive them from the description using these rules:

• Each criterion is independently verifiable — a reviewer can check it without interpretation.

• Write from the user/system perspective, not the implementation perspective.

• Good: "User sees an error message when submitting an empty form"

• Bad: "Add validation to the form handler"

• Cover the happy path first, then edge cases and error states.

• Include a non-regression criterion when fixing a bug: "The scenario described in this issue no longer reproduces."

• Aim for 3–7 criteria. If more are needed, the issue is probably too large — suggest splitting it.

Issue Body Template

Use this exact structure for the body:

Background

<1–3 sentences: the problem or motivation. Why does this issue exist?>

Acceptance Criteria

• <Criterion 1 — verifiable outcome>
• <Criterion 2>
• <Criterion 3>

Out of Scope

• <Item explicitly not covered by this issue>

Technical Notes

<Optional: relevant files, architecture constraints, prior art, dependencies. Omit section entirely if nothing to add.>

• Keep Background factual and concise — no implementation details.

• The Out of Scope section prevents scope creep during review and implementation.

• Omit Technical Notes entirely if there's nothing useful to add.

Label Conventions

Suggest labels from these standard sets. Create missing labels with gh label create if they don't exist.

Type (pick one):

Label Color Use for

type: feature

#0075ca

New capability

type: bug

#d73a4a

Something broken

type: chore

#e4e669

Maintenance, deps, config

type: docs

#0052cc

Documentation only

Size (pick one, based on effort estimate):

Label Color Rough effort

size: small

#c2e0c6

< 4 hours

size: medium

#fef2c0

4–16 hours

size: large

#f9d0c4

16 hours — consider splitting

Priority (optional):

Label Color Use for

priority: high

#b60205

Blocking other work

priority: medium

#fbca04

Normal queue

priority: low

#0e8a16

Nice to have

Check what labels already exist before creating new ones:

gh label list

Creating the Issue

1. Show the draft to the user

Always present the full title and body before running gh issue create . Allow the user to edit before confirming.

2. Create required labels

Example: create a label that doesn't exist yet

gh label create "type: feature" --color "0075ca" --description "New capability"

3. Create the issue

gh issue create
--title "<title>"
--body "$(cat <<'BODY'

Background

<background>

Acceptance Criteria

• <criterion>

Out of Scope

• <item> BODY )"
  --label "type: feature,size: medium"

Add --assignee "@me" if the user is self-assigning. Add --milestone "<name>" if a milestone was specified.

4. Confirm and share

After creation, gh prints the issue URL. Share it with the user.

Splitting Oversized Issues

If acceptance criteria exceed 7 items, or the issue spans multiple independent concerns, recommend splitting. A good split keeps each issue:

• Independently shippable

• Reviewable without the other issues

• Clearly titled so the relationship is obvious

Link related issues in the body using #<number> references after creation.

Common Pitfalls

• Vague titles: "Fix bug" or "Improve performance" are not useful. Titles should name the specific thing.

• Acceptance criteria that describe implementation: "Refactor the service layer" is a task, not a criterion. Rephrase as an observable outcome.

• Missing out-of-scope: Without it, reviewers assume everything related is included.

• No milestone on planned work: If a milestone exists for the current sprint/release, attach the issue to it.