# Create Issue

> Create GitHub issues using repo templates (feature, bug, spike)

- Skill: `nudgebee/create-issue-2` (Agent Skill)
- Install (CLI): `npx skillmds@latest add nudgebee/create-issue-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nudgebee/create-issue-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: nudgebee (https://skillmd.com/u/nudgebee)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/nudgebee/create-issue-2

---


# Create GitHub Issue

Create a GitHub issue using the repository's issue templates. Optional argument: `$ARGUMENTS` (issue type: `feature`, `bug`, or `spike`).

## Available Issue Types

| Type | Template | Title Format | Labels |
|------|----------|--------------|--------|
| `feature` | FEATURE-REQUEST.yml | `[REQUEST] - <title>` | — |
| `bug` | BUG-REPORT.yml | `[BUG] - <title>` | `bug` |
| `spike` | SPIKE-REQUEST.yml | `[REQUEST] - <title>` | — |

## Step 0: Check for Existing Related Issues

Before creating a new issue, search for existing issues (open or closed) that may already cover this work or could be a parent for it:

```bash
# Search for related issues using keywords from the user's description
gh issue list --search "<keywords>" --state all --limit 10 --json number,title,state,labels,url
```

Also check the current sprint for related work:

```bash
# List current sprint issues from the project board
gh project item-list 1 --owner nudgebee --format json --limit 200 | jq '[.items[] | select(.status != "Done") | {number: .content.number, title: .content.title, type: .content.type, status: .status}]' 2>/dev/null | head -50
```

If related issues exist, present them to the user:

```
I found these potentially related issues:
- #1234 [open] - <title>
- #5678 [closed] - <title>

Options:
1. Link to an existing issue (add a comment or reference)
2. Create a new issue anyway
3. Skip issue creation
```

Only proceed to create a new issue if the user confirms none of the existing issues cover the work.

## Step 1: Determine Issue Type

If `$ARGUMENTS` specifies a type (`feature`, `bug`, `spike`), use that. Otherwise, ask the user:

```
What type of issue would you like to create?
- feature: New feature or enhancement request
- bug: Report a bug or defect
- spike: Exploratory work to answer a question
```

## Step 2: Gather Information Based on Type

### For Feature Request

Ask or infer from context. **The web form is the source of truth for this schema** —
these mirror `.github/ISSUE_TEMPLATE/FEATURE-REQUEST.yml` one for one.

1. **Title**: Short descriptive title for the feature
2. **Function** (required): Troubleshooting / collectors · AI · Integrations · Notifications / tickets / optimize · UI / API / auth · Platform · Not sure
3. **Who asked for this** (required): Customer — named account · Prospect — active deal · Sales / field feedback · Support — recurring ticket · Our own judgement · Internal / team need. **Never invent a customer** — "Our own judgement" is valid and common.
4. **Summary** (required): Brief explanation of the feature
5. **What this unblocks** (required): The account, deal, renewal or support load behind it — or a stated bet on product direction
6. **How we will know it worked** (required): The observable change after it ships; a number is best
7. **What we are not doing instead** (required): The trade-off accepted. "Nothing" is legitimate for small work
8. **Basic Example** (optional): Specific examples of how the feature would work
9. **Drawbacks** (optional): Potential drawbacks or impacts
10. **Unresolved questions** (optional): Questions that remain unresolved
11. **Parent / epic** (optional): The larger piece of work this slices, as `#<n>`
12. **Related work** (optional): One link per line, prefixed with the relationship — `Part of #123` · `Blocked by #123` · `Blocks #123` · `Related to #123`

If you cannot answer 5, 6 or 7 from context, **ask** rather than inventing plausible
text — a fabricated customer or metric survives into prioritisation as if it were evidence.

### For Bug Report

Ask or infer from context:

1. **Title**: Short descriptive title for the bug
2. **Description** (required): Explicit description of the issue
3. **Reproduction URL** (required): GitHub URL or relevant link
4. **Reproduction Steps** (required): Step-by-step instructions to reproduce
5. **Screenshots** (optional): Screenshots if applicable
6. **Logs** (optional): Relevant log output
7. **Browsers** (optional): Affected browsers (Firefox, Chrome, Safari, Edge, Opera)
8. **OS** (optional): Affected operating systems (Windows, Linux, Mac)

### For Spike Request

Ask or infer from context:

1. **Title**: Short descriptive title for the spike
2. **Summary** (required): Brief explanation of the exploration
3. **Objectives** (required): What you want to learn/answer
4. **Result Summary** (required): Expected outcome format
5. **Next Steps** (required): What happens after the spike
6. **Unresolved Questions** (optional): Open questions
7. **Reference Issues** (optional): Related issue numbers

## Step 3: Generate Issue Content

Based on the type, format the issue body in markdown:

### Feature Request Body

**The web form is the source of truth for this schema.** GitHub renders
`.github/ISSUE_TEMPLATE/FEATURE-REQUEST.yml` as `###` headings whose text matches each
field's `label`. Match them exactly so form-filed and skill-filed issues parse the same.

```markdown
### Function
{function}

### Who asked for this
{source}

### Summary
{summary}

### What this unblocks
{unblocks}

### How we will know it worked
{success}

### What we are not doing instead
{tradeoff}

### Basic Example
{basic_example or "None"}

### Drawbacks
{drawbacks or "None"}

### Unresolved questions
{unresolved_questions or "None"}

### Parent / epic
{parent or "None"}

### Related work
{related or "None"}
```

### Bug Report Body

**The web form is the source of truth for this schema.** GitHub renders
`.github/ISSUE_TEMPLATE/BUG-REPORT.yml` as `###` headings whose text matches each
field's `label` exactly. Emit the same headings, in the same order, with the same
capitalisation, so an issue filed by this skill is indistinguishable from one filed
through the form. Use `###`, not `##`, and do not rename the headings.

Omit any optional heading you have nothing for rather than writing "N/A" — an empty
section is worse than an absent one.

```markdown
### Environment
{Exactly one of: Production | QA / Test | Dev | Local only | Not sure}

### Description
{description}

### Impact
- **Who is affected**: {all tenants / specific feature users / dev-only / etc.}
- **Severity**: {what the user can't do, or what they see incorrectly}
- **Since when**: {date or version, "unknown" if not known}

### Link
{URL to the affected page, dashboard or conversation. Omit the heading if none.}

### Reproduction steps
{reproduction_steps}

### Logs
{logs — omit the heading if none}

### Screenshots
{screenshots — omit the heading if none}

### Client details
{Browser / OS, e.g. "Chrome 128 / macOS". UI bugs only — omit for backend bugs.}
```

`Environment`, `Description`, `Impact` and `Reproduction steps` are required by the
form: always emit all four, writing "unknown" where you must. `Environment` must be
one of the five literal dropdown options above, spelled exactly — any other string
will not match what the form produces.

**If you change the form, change this block in the same PR.** The two drifting apart
is what made half the bug corpus unparseable in the first place.

### Spike Request Body

```markdown
## Summary
{summary}

## Objectives
{objectives}

## Result Summary
{result_summary}

## Next Steps
{next_steps}

## Unresolved Questions
{unresolved_questions or "None"}

## Reference Issues
{reference_issues or "None"}
```

## Step 4: Confirm with User

Show the user the formatted issue:

```
Title: {title_with_prefix}
Labels: {labels}
Body:
---
{body}
---

Create this issue? (yes/no)
```

## Step 5: Create the Issue

Use GitHub CLI to create the issue:

```bash
gh issue create 
  --title "{title}" 
  --body "$(cat <<'EOF'
{body}
EOF
)" 
  --label "{labels}"  # Only if labels exist
```

## Step 6: Add to Project with Current Iteration

After creating the issue, automatically add it to the project board and set iteration to "current":

```bash
# Get the issue number from the created issue URL
ISSUE_NUMBER={extracted_issue_number}

# Add issue to the project (project number 1 = "Nudgebee" main project)
gh project item-add 1 --owner nudgebee --url "https://github.com/nudgebee/nudgebee/issues/${ISSUE_NUMBER}"

# Get the item ID for the newly added issue
ITEM_ID=$(gh project item-list 1 --owner nudgebee --format json --limit 1000 | jq -r ".items[] | select(.content.number == ${ISSUE_NUMBER}) | .id")

# Set the iteration field to current iteration
# Iteration field ID: PVTIF_lADOCG7t1c4ATt4GzgMmEFQ
gh project item-edit --project-id PVT_kwDOCG7t1c4ATt4G --id "${ITEM_ID}" --field-id PVTIF_lADOCG7t1c4ATt4GzgMmEFQ --iteration-id "@current"
```

**Note**: If the project commands fail (e.g., project not found or permissions), the issue is still created successfully. The iteration assignment is a best-effort addition.

## Step 7: Output Result

```
Issue created: {url}
Title: {title}
Type: {type}
Number: #{number}
Iteration: Current (if project assignment succeeded)
```

## Context-Aware Creation

If the user is working on code changes and asks to create an issue, try to infer:

- **Feature**: If they've implemented something new, suggest documenting it as a feature request for tracking
- **Bug**: If they've fixed something, suggest creating a bug report to document the issue
- **Spike**: If they've been exploring/researching, suggest a spike to document findings

Example: After implementing the new/recurring issues feature, suggest:
```
Would you like to create a feature request issue to track this work?
Title: [REQUEST] - Add new vs recurring issue tracking to Kubernetes events
```