| name | gh-issue-creator |
| description | Create a GitHub issue in the current repo using one of the predefined issue templates (bug, feature, tech debt) or as a blank issue. Fetches available labels dynamically, maps user intent to the right template, and enforces concise problem descriptions. Use when the user mentions creating an issue, filing a bug, opening a ticket, or reporting a problem. |
GitHub Issue Creator
Create concise, well-labeled GitHub issues in the current repo using the predefined issue templates.
Critical Rules
- Clarification gate: If the user's description is vague or missing key details, STOP and use the Ask User
Questions tool to ask for specifics before drafting. Never guess what the issue is about.
- Confirmation gate: NEVER run
gh issue create without showing the full draft to the user first and receiving
explicit approval.
- Conciseness over completeness: Each section in the issue body should be 2-4 sentences max. Only include sections
the user provided content for. Prefer brevity over verbosity.
Issue Templates
Three template definitions live in the references/ folder. Read the relevant file for the chosen issue type to get
field definitions, required/optional markers, and an example body.
Blank issues (freeform) are also supported -- no template file needed.
Workflow
Step 1: Detect Repo
gh repo view --json nameWithOwner -q '.nameWithOwner'
If not inside a git repo or gh fails: Inform the user and stop. If gh is not authenticated: Show error and
suggest gh auth login. Stop.
Step 2: Determine Issue Type
If the user hasn't specified the type, use the Ask User Questions tool with these options:
- Bug Report
- Feature Request
- Tech Debt
- Blank issue (freeform)
If the type is obvious from context (e.g., "file a bug for..."), skip the picker and proceed.
Step 3: Fetch Labels and Resolve Issue Type
Fetch labels dynamically:
gh label list --limit 100
Labels: Select the best-fit labels from the available list based on the issue type and content. No labels are
hardcoded -- always pick dynamically.
Issue types: This repo uses GitHub issue types. Map the chosen template to a type name:
| Template | Issue type name |
|---|
| Bug Report | Bug |
| Feature Request | Feature |
| Tech Debt | Task |
If free form issue, define the best suited type from the issue types (Bug, Feature or Task).
Note: gh issue type list and gh issue create --type are not valid CLI commands. Issue types must be set via
the REST API after creation (see Step 8).
Step 4: Gather Issue Details
Clarification gate: If the user has not clearly stated what the issue is about, use the Ask User Questions tool
to clarify before proceeding.
Read the companion file for the chosen template type (see Issue Templates table above). Use the Fields table in that
file to determine what to gather and which fields are required vs optional. Only the first field in each template is
required -- keep it lightweight.
For blank issues, gather a freeform title and body. Keep the body to 2-4 sentences.
Step 5: Draft the Issue
- Title: A short description in imperative mood (e.g.,
Fix pagination on user list). No type prefix.
- Body: Format using markdown headers matching the template fields. Only include sections the user provided content
for. Follow the Example Body in the companion file for the correct structure.
- Labels: Best-fit labels from the dynamically fetched list.
- Type: The matched issue type from the fetch step (if available).
- Related: If the user mentions related issues or PRs, include a
## Related section with links at the end of the
body.
Step 6: Present Preview
Show the full draft using this template:
### Issue Preview
**Title:** <title>
**Type:** <issue type>
**Labels:** <label1>, <label2>
**Body:**
<full issue body>
<template name> was used to generate this issue.
Step 7: Await Approval
Confirmation gate: Wait for explicit user approval before creating. Use the Ask User Questions tool to ask the
user if they want to create the issue as-is, or if they want to make any changes.
Step 8: Create and Report
Create the issue:
gh issue create --title "<title>" --body "<body>" --label "<label1>,<label2>"
Set the issue type. Extract the issue number from the returned URL, then set the type using the REST API with the
human-readable type name from the Step 3 table:
gh api -X PATCH repos/<owner>/<repo>/issues/<number> -f type="<issue_type_name>"
After creation, display the issue URL as a clickable markdown link:
Created: [<repo>#<number> <title>](<url>)
Style Guide for Issues
- Title: imperative mood, no period at the end
- Body: problem-first framing. "X does not work when Y" or "Users need the ability to Z"
- No excessive reproduction steps. Keep it to the essentials
- Link to related PRs or issues if relevant context exists
Anti-Patterns
- Do NOT create the issue on GitHub without explicit user approval
- Do NOT skip label assignment -- always check available labels and pick the best fit
- Do NOT write walls of text in the issue body
- Do NOT include solution proposals unless the user provides one or explicitly asks
- Do NOT hardcode labels -- always fetch dynamically from the repo
