Create Issue

Creates a new GitHub issue in the current repository (or specified repo) with formatted description, labels, assignees, and optional reference links to related issues, PRs, or documentation.

Arguments

• - Issue title (wrap in quotes if it contains spaces)
• --body - Issue body/description (wrap in quotes)
• --labels ... - One or more labels to apply
• --assignee - GitHub username to assign
• --milestone - Milestone name or number
• --project - Add to GitHub Project (name or number)
• --refs ... - Reference URLs to include in the issue body
• --repo <owner/repo> - Create in specific repository (default: current)
• --template - Use interactive template mode with guided prompts

Workflow

Phase 1: Parse Arguments

1. Extract Title

The first positional argument is the title. If no flags follow, the entire argument string is the title.

1. Parse Optional Flags

Extract all optional parameters from the command arguments.

1. Determine Target Repository

   # If --repo not specified, use current repository
   gh repo view --json owner,name -q '"\(.owner.login)/\(.name)"'

Phase 2: Build Issue Body

Construct the issue body from the provided description and references.

Body Structure

${body_text}

${references_section}

References Section

If --refs URLs are provided, analyze and categorize them:

Use the WebFetch tool to retrieve metadata for each URL:
- GitHub issue URLs → Extract issue number, title, status
- GitHub PR URLs → Extract PR number, title, status
- Documentation URLs → Extract page title
- Other URLs → Use raw URL with domain name

Format as a "Related Links" section:
## Related Links

- [#123: Original feature request](https://github.com/owner/repo/issues/123)
- [PR #456: Initial implementation](https://github.com/owner/repo/pull/456)
- [Design Doc: Architecture](https://example.com/docs/architecture)

Phase 3: Interactive Template Mode (Optional)

When --template flag is used, guide the user through structured prompts:

Use the AskUserQuestion tool for each section:

1. **Issue Type**
   Options: "Bug", "Feature", "Enhancement", "Documentation", "Question"

2. **Description Prompts** (based on type):

   For Bug:
   - What is the expected behavior?
   - What is the actual behavior?
   - Steps to reproduce?
   - Environment details?

   For Feature/Enhancement:
   - What problem does this solve?
   - Proposed solution?
   - Acceptance criteria?
   - Alternatives considered?
…

The template mode builds the full gh issue create command from responses.

Phase 4: Create Issue

Execute the GitHub CLI command to create the issue:

gh issue create \
  --repo "${repo}" \
  --title "${title}" \
  --body "${body}" \
  ${labels:+--label "$labels"} \
  ${assignee:+--assignee "$assignee"} \
  ${milestone:+--milestone "$milestone"} \
  ${project:+--project "$project"}

Command Construction Notes:

• Use --body-file if body is long (>500 chars) to avoid shell limits
• Multiple labels: --label "bug" --label "needs-triage"
• Escape quotes in title/body properly

Phase 5: Post-Creation Actions

After successful creation, perform follow-up actions:

1. Capture Issue URL

   gh issue create [...] --json url,number -q '"\(.number): \(.url)"'

1. Display Summary

   Created issue #${number}

   Title: ${title}
   URL: ${url}
   Labels: ${labels}
   Assigned: ${assignee}

1. Optional: Add to Project Board

If --project specified:

   gh project item-add ${project_number} --url ${issue_url}

1. Optional: Link Related Issues

If --refs contains GitHub issue/PR URLs, add automatic cross-references:

   # For each GitHub ref URL
   gh issue comment ${ref_number} --body "Related: ${new_issue_url}"

Examples

Example 1: Simple Issue

/create-issue "Fix login timeout on slow connections"

Result:

Created issue #234

Title: Fix login timeout on slow connections
URL: https://github.com/athola/skrills/issues/234

Example 2: Full Issue with Labels and References

/create-issue "Add MCP analytics dashboard" \
  --body "Create a web dashboard showing skill usage metrics and recommendations" \
  --labels "enhancement" "mcp" \
  --assignee "athola" \
  --refs "https://github.com/athola/skrills/issues/21" \
        "https://example.com/docs/analytics-spec"