Create GitHub Issue

Create GitHub Issue

Create well-structured GitHub issues from plain-language descriptions using the gh CLI. Issues conform to the target repository's YAML form templates and are automatically assigned to the correct project board.

This skill is repo-agnostic — it reads template metadata (projects, labels, required fields) from the repo's .github/ISSUE_TEMPLATE/ files at runtime rather than hardcoding them.

Prerequisites

The gh CLI must be authenticated (gh auth status). If not, prompt the user to run gh auth login.

Input

The user provides one or more of:

• Description (required) — plain-language explanation of the bug, feature, task, or epic
• Type override (optional) — explicitly request bug, feature, task, or epic
• Repo override (optional) — owner/repo when not filing against the current working directory's repo
• Labels (optional) — specific labels to apply
• Milestone (optional) — target milestone
• Assignees (optional) — GitHub usernames to assign

Workflow

Follow these steps in order. Do not skip any step.

Step 1: Determine the target repository

Detect the repo from the current working directory using gh repo view. If the user specified a repo explicitly, use that instead. Confirm the repo with the user before proceeding.

Step 2: Classify the issue type

Determine the type from context. If the user specified a type, use it. Otherwise, infer from keywords in the description:

When ambiguous, ask the user to clarify.

Step 3: Analyze the codebase (bug reports only)

For bug reports, perform a brief code analysis before drafting to help identify the root cause. This adds valuable context to the issue:

1. If the user mentions specific UI elements, file paths, or error messages, search the codebase for related code
2. Read the relevant source files to understand the current behavior
3. Summarize your findings in the bug description — include:
   • Which file(s) and function(s) are likely involved
   • What the current code does vs what the user expects
   • A brief root-cause hypothesis if one is apparent

This analysis is informational — include it in the issue body under "Additional context" or inline in the bug description. Do not fix the bug or propose code changes in the issue.

Skip this step for feature requests, tasks, and epics.

Step 4: Search for duplicates

Before drafting, search for existing issues that might cover the same topic. Present any matches to the user. If a duplicate exists, ask whether to proceed, reference the existing issue, or abandon.

Step 5: Read the repo's issue templates

Read the .github/ISSUE_TEMPLATE/ directory from the repo to identify the correct template and its metadata. Support both .yml and .yaml extensions.

Matching template to type:

1. List all template files in .github/ISSUE_TEMPLATE/
2. Read the top-level type: field from each template file
3. Select the template whose type: field matches the issue type classified in Step 2
4. If no exact match is found, ask the user which template to use

From the matching template file, extract:

• projects: — which project board(s) to assign
• labels: — which labels the template auto-applies (do not duplicate these via --label)
• type: — the GitHub issue type (handled by the template, not by labels)
• Required/optional fields — which body sections to include

See references/repo-templates.md for the shared template structure.

Step 6: Gather metadata

Labels — Fetch available labels from the repo and suggest matches based on the description. See Label Guidance below for rules on which labels to suggest. Never apply labels blindly — present suggestions and let the user confirm. Do not duplicate labels that the template already applies via its labels: field.

Milestone — Suggest the most recent open milestone unless the user specified one.

Project — Use the project(s) from the template's projects: field.

Step 7: Draft the issue — STOP and show to the user

Compose the title and body matching the template structure for the chosen type (see Issue Body Format below). Present the full draft to the user:

## Draft Issue — please review before I create it

**Repo:** <owner/repo>
**Type:** <bug|feature|task|epic>
**Title:** <title>
**Labels:** <label1, label2>
**Milestone:** <milestone>
**Project:** <project>
**Assignees:** <@user1, @user2>

**Body:**
<full markdown body>

CRITICAL: You MUST stop here and wait for the user's response. Do NOT proceed to Step 8 in the same turn. End your turn after presenting the draft. Ask the user:

• "Create this issue" — proceed to Step 8
• "Edit the draft" — ask what to change, revise, and present again
• "Abandon" — stop without creating

Never run gh issue create without the user explicitly confirming.