/create-issue

name: create-issue
description: Create a new GitHub issue with formatted description, labels, and optional reference links
usage: /create-issue <title> [--body <text>] [--labels <label>...] [--assignee <user>] [--milestone <milestone>] [--refs <url>...]

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

• `<title>` - Issue title (wrap in quotes if it contains spaces)
• `--body <text>` - Issue body/description (wrap in quotes)
• `--labels <label>...` - One or more labels to apply
• `--assignee <user>` - GitHub username to assign
• `--milestone <milestone>` - Milestone name or number
• `--project <project>` - Add to GitHub Project (name or number)
• `--refs <url>...` - 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.

2. **Parse Optional Flags**

Extract all optional parameters from the command arguments.

3. **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. Follow `Skill(leyline:ticket-writing)`. If leyline is absent: the first screen says what was decided and why, or links to the document that does.

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, with environment if it matters?

   For Feature/Enhancement:
   - What changes, or what was decided?
   - Why, in one to three sentences, or a link to the document?
   - Done when? (skip if the title says)

3. **Labels** (suggest based on type):
   - bug → "bug", "needs-triage"
   - feature → "enhancement", "feature"
   - documentation → "docs"

4. **Priority** (optional):
   Options: "critical", "high", "medium", "low"
   → Adds corresponding label

5. **Related Links**:
   Prompt: "Any related issues, PRs, or docs? (URLs, one per line, empty to finish)"
   Loop until empty input.

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)"'

2. **Display Summary**

   Created issue #${number}

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

3. **Optional: Add to Project Board**

If `--project` specified:

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

4. **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"

**Generated Body:**

Create a web dashboard showing skill usage metrics and recommendations

## Related Links

- [#21: Enhance MCP analytics](https://github.com/athola/skrills/issues/21)
- [Analytics Spec](https://example.com/docs/analytics-spec)

Example 3: Interactive Template Mode

/create-issue --template

> Issue Type? [Bug/Feature/Enhancement/Documentation/Question]
Feature

> What changes, or what was decided?
Build a dashboard using the MCP analytics API.

> Why, in one to three sentences, or a link to the document?
Users cannot see skill usage patterns.

>