Issue Create

Issue Create Skill

Create well-formatted GitHub issues with intelligent automation including AI-powered label suggestions, content type detection, template formatting, and related issue linking.

Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

When to Use This Skill

Use this skill when:

• Creating bug reports, feature requests, questions, or documentation issues
• Need AI-powered label suggestions from repository's existing taxonomy
• Want automatic duplicate detection and related issue linking
• Need consistent issue formatting across different repositories

Invocation

Slash command: /gh-tools:issue-create

Natural language triggers:

• "Create an issue about..."
• "File a bug for..."
• "Submit a feature request..."
• "Report this problem to..."
• "Post an issue on GitHub..."

Features

1. Repository Detection

• Auto-detects repository from current git directory
• Supports explicit --repo owner/repo flag
• Checks permissions before attempting to create

2. Content Type Detection

• AI-powered detection (gpt-4.1 via gh-models)
• Fallback to keyword matching
• Types: Bug, Feature, Question, Documentation

3. Title Extraction

• Extracts informative title from content
• Adds type prefix (Bug:, Feature:, etc.)
• Maximizes GitHub's 256-character limit for informative titles

4. Body Limit Maximization (65,536 Characters)

GitHub issue bodies support 65,536 characters (not bytes — UTF-8 multibyte characters count as 1). Always aim to fill a single post rather than splitting across multiple issues or comments.

Principle: One comprehensive post is more valuable than many fragmented ones. Pack as much analysis, context, history, and multi-perspective reasoning as possible into a single issue body or comment.

When composing long-form issue content:

• Check remaining capacity: echo "$BODY" | wc -m (characters, not bytes)
• Target ~60,000 chars to leave headroom for GFM rendering edge cases
• Use collapsible sections (<details><summary>) for dense reference material — they don't reduce the char budget but improve readability
• Include all perspectives: if the issue documents a decision, include the alternatives considered, trade-offs, evidence for/against, and why the chosen path won
• Embed historical context: timelines, prior art, links to related issues, session provenance — all belong in one post
• Never pre-emptively split: only split if you genuinely exceed 65,536 chars (rare)

Pre-post size check pattern:

# Build body, then verify it fits
BODY=$(cat <<'EOF'
... your content ...
EOF
)
CHARS=$(echo "$BODY" | wc -m | tr -d ' ')
echo "Body size: ${CHARS}/65536 chars"
if [ "$CHARS" -gt 65536 ]; then
  echo "WARNING: Exceeds limit by $((CHARS - 65536)) chars — trim or split"
fi

5. Template Formatting

• Auto-selects template based on content type
• Bug: Steps to reproduce, Expected/Actual behavior
• Feature: Use case, Proposed solution
• Question: Context, What was tried
• Documentation: Location, Suggested change

5. Label Suggestion

• Fetches repository's existing labels
• AI suggests 2-4 relevant labels
• Only suggests labels that exist (taxonomy-aware)
• 24-hour cache for performance

6. Related Issues

• Searches for similar issues
• Links related issues in body
• Warns about potential duplicates

7. Preview & Confirm

• Full preview before creation
• Dry-run mode available
• Edit option for modifications

Usage Examples

Basic Usage

# From within a git repository
bun ~/eon/cc-skills/plugins/gh-tools/scripts/issue-create.ts \
  --body "Login page crashes when using special characters in password"

With Explicit Repository

bun ~/eon/cc-skills/plugins/gh-tools/scripts/issue-create.ts \
  --repo owner/repo \
  --body "Feature: Add dark mode support for better accessibility"

Dry Run (Preview Only)

bun ~/eon/cc-skills/plugins/gh-tools/scripts/issue-create.ts \
  --repo owner/repo \
  --body "Bug: API returns 500 error" \
  --dry-run

With Custom Title and Labels

bun ~/eon/cc-skills/plugins/gh-tools/scripts/issue-create.ts \
  --repo owner/repo \
  --title "Bug: Login fails with OAuth" \
  --body "Detailed description..." \
  --labels "bug,authentication"

Disable AI Features

bun ~/eon/cc-skills/plugins/gh-tools/scripts/issue-create.ts \
  --body "Question: How to configure..." \
  --no-ai

CLI Options

Dependencies

• gh CLI (required) - GitHub CLI tool
• gh-models extension (optional) - Enables AI features

Installing gh-models

gh extension install github/gh-models

Permission Handling

Logging

Logs to: ~/.claude/logs/gh-issue-create.jsonl

Events logged:

• preflight - Initial checks
• type_detected - Content type detection
• labels_suggested - Label suggestions
• related_found - Related issues search
• issue_created - Successful creation
• dry_run - Dry run completion

Related Documentation

• Content Types Reference
• Label Strategy Reference
• AI Prompts Reference

Embedding Images in Issues

GitHub Issues have no API for programmatic image upload. The web UI's drag-and-drop uses an internal S3 policy flow that is intentionally not exposed to API clients (cli/cli#1895).

Preflight: Ensure Images Are Reachable

The ?raw=true URL resolves via github.com — if the image doesn't exist at that path on the remote, it silently 404s (broken image, no error). Run this preflight before creating the issue:

# 1. Detect repo context
OWNER_REPO=$(gh repo view --json nameWithOwner -q '.nameWithOwner')
BRANCH=$(git rev-parse --abbrev-ref HEAD)
VISIBILITY=$(gh repo view --json visibility -q '.visibility')

# 2. Verify images are git-tracked (not gitignored)
IMG_DIR="path/to/images"
for f in ${IMG_DIR}/*.png; do
  git ls-files --error-unmatch "$f" >/dev/null 2>&1 \
    || echo "WARNING: $f is NOT tracked by git (check .gitignore)"
done

# 3. Verify images are committed (not just staged or untracked)
UNCOMMITTED=$(git diff --name-only HEAD -- "${IMG_DIR}/" 2>/dev/null)
UNTRACKED=$(git ls-files --others --exclude-standard -- "${IMG_DIR}/" 2>/dev/null)
if [[ -n "$UNCOMMITTED" || -n "$UNTRACKED" ]]; then
  echo "FAIL: Images not committed — commit and push first"
  echo "  Uncommitted: ${UNCOMMITTED}"
  echo "  Untracked:   ${UNTRACKED}"
  exit 1
fi

# 4. Verify commit is pushed to remote (local commits invisible to github.com)
LOCAL_SHA=$(git rev-parse HEAD)
REMOTE_SHA=$(git rev-parse "origin/${BRANCH}" 2>/dev/null)
if [[ "$LOCAL_SHA" != "$REMOTE_SHA" ]]; then
  echo "FAIL: Local commits not pushed — run: git push origin ${BRANCH}"
  exit 1
fi

# 5. Build image base URL
IMG_BASE="https://github.com/${OWNER_REPO}/blob/${BRANCH}/${IMG_DIR}"
echo "Image base URL: ${IMG_BASE}/<filename>.png?raw=true"
echo "Repo visibility: ${VISIBILITY}"
if [[ "$VISIBILITY" == "PRIVATE" ]]; then
  echo "NOTE: Images only visible to authenticated collaborators"
fi

Preflight checklist (what each step catches):

URL Format: ?raw=true vs raw.githubusercontent.com

For images already committed and pushed, use github.com/blob/...?raw=true URLs — not raw.githubusercontent.com:

<!-- BROKEN for private repos (no browser cookies on raw.githubusercontent.com) -->

![img](https://raw.githubusercontent.com/owner/repo/main/path/image.png)

<!-- WORKING for all repos (browser has cookies on github.com, gets signed redirect) -->

![img](https://github.com/owner/repo/blob/main/path/image.png?raw=true)

Scripting pattern (batch images → issue body):

IMG_BASE="https://github.com/${OWNER_REPO}/blob/${BRANCH}/${IMG_DIR}"

gh issue create --title "Feedback with screenshots" --body "$(cat <<EOF
## Item 1
![description](${IMG_BASE}/01-screenshot.png?raw=true)

## Item 2
![description](${IMG_BASE}/02-screenshot.png?raw=true)
EOF
)"

See AP-07 in GFM Anti-Patterns for the full technical explanation.

Images NOT in the Repository

For images only on disk (not committed), four options:

Playwright Automation (Programmatic CDN Upload)

GitHub has no API for image uploads, but the browser's file-attachment flow can be automated via Playwright to get permanent user-attachments CDN URLs without any commit/push preflight.

How it works:

1. Playwright opens the issue page in Chromium with a persistent profile (~/.claude/tools/pw-github-profile/) 2. First run only: user logs in to GitHub (any method — Google SSO, passkey, password). Cookies persist. 3. Script clicks "Paste, drop, or click to add files" → intercepts the file chooser → sets the image file 4. GitHub uploads to its S3 backend and inserts an <img> tag with a user-attachments CDN URL into the comment textarea 5. Script extracts the CDN URL and clears the textarea (no comment is actually posted)

Key implementation details (GitHub's 2026 React comment composer):

• Comment textarea selector: textarea[placeholder="Use Markdown to format your comment"] (dynamic React IDs — do NOT match by id)
• File upload trigger: click the "Paste, drop, or click to add files" text, then intercept page.waitForEvent("filechooser")
• Upload result format: <img width="W" height="H" alt="Image" src="https://github.com/user-attachments/assets/UUID" /> (HTML <img> tag, not ![](...) markdown)
• Old textarea#new_comment_field and file-attachment input[type='file'] selectors no longer exist
• Batch uploads: clear textarea between uploads with textarea.fill("")

Chrome CDP note: chromium.connectOverCDP() fails with Chrome 136+ (WebSocket timeout). Use chromium.launchPersistentContext() with Playwright's bundled Chromium instead. Chrome 136+ also requires --user-data-dir for CDP (DevTools remote debugging requires a non-default data directory), making CDP impractical for reusing existing browser sessions.

---

Troubleshooting

"No repository context"

Run from a git directory or use --repo owner/repo flag.

Labels not suggested

• Check if gh-models is installed: gh extension list
• Verify repository has labels: gh label list --repo owner/repo
• Check label cache: ls ~/.cache/gh-issue-skill/labels/

AI features not working

Install gh-models extension:

gh extension install github/gh-models

Post-Execution Reflection

After this skill completes, check before closing:

1. Did the command succeed? — If not, fix the instruction or error table that caused the failure. 2. Did parameters or output change? — If the underlying tool's interface drifted, update Usage examples and Parameters table to match. 3. Was a workaround needed? — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.

Only update if the issue is real and reproducible — not speculative.

AI Prompts Reference

This document describes the AI prompts used by the issue-create skill for content detection and label suggestion.

Model Configuration

Content Type Detection Prompt

Purpose: Classify issue content into one of four categories.

Classify this GitHub issue content into exactly one category.
Categories: bug, feature, question, documentation
Return ONLY the category name, nothing else.

Content:
{content}

Expected Response: Single word - bug, feature, question, or documentation

Validation: Response must contain one of the valid category names.

Label Suggestion Prompt

Purpose: Suggest 2-4 labels from the repository's existing taxonomy.

Suggest 2-4 labels from the EXISTING taxonomy only for this GitHub issue.
Never suggest labels that don't exist in the list below.
Return ONLY a JSON array of label names, nothing else.

AVAILABLE LABELS:
- label1: description
- label2: description
...

ISSUE TITLE: {title}
ISSUE BODY:
{body}

Return format: ["label1", "label2"]

Expected Response: JSON array of label names

["bug", "authentication", "priority-high"]

Validation:

1. Parse as JSON array 2. Filter to only labels that exist in taxonomy 3. Return validated list

Title Extraction (Future)

Purpose: Extract an informative title from issue content.

Extract an informative GitHub issue title (max 256 chars).
Maximize the character limit based on the nature of the content.
Content: {content}

Expected Response: Single line title string (up to 256 characters)

Principle: GitHub allows 256 characters for issue titles. Maximize this limit to create informative, searchable titles. The approach depends on the nature of the content.

Error Handling

AI Unavailable

1. Check if gh-models extension is installed 2. If not, offer installation command 3. Fall back to keyword-based detection

Parse Errors

1. Log the raw response for debugging 2. Fall back to keyword matching 3. Return empty array for labels

Timeout

1. 30-second timeout on all AI calls 2. On timeout, fall back to keywords 3. Log timeout event

Prompt Engineering Guidelines

1. Be Explicit: Clearly state expected output format 2. Constrain Output: Ask for ONLY the specific format needed 3. Provide Context: Include relevant labels/categories 4. Limit Input: Truncate long content to avoid token limits 5. Validate Output: Always validate AI responses before use

Token Considerations

Debugging AI Responses

Enable verbose logging:

bun issue-create.ts --body "..." --verbose

Check logs:

tail -20 ~/.claude/logs/gh-issue-create.jsonl | jq 'select(.ai_model)'

Content Types Reference

This document defines the content types detected by the issue-create skill and their associated templates.

Supported Content Types

Bug

Detection indicators:

• Keywords: bug, error, crash, broken, fail, exception, stacktrace
• Patterns: "not working", "doesn't work", TypeError, ReferenceError

Template:

## Description

{CONTENT}

## Steps to Reproduce

1.
2.
3.

## Expected Behavior

## Actual Behavior

## Environment

- OS:
- Version:

Suggested labels: bug, defect, error, issue

---

Feature

Detection indicators:

• Keywords: feature, enhancement, add, implement, support, would be nice
• Patterns: "I want", "could you add", "suggestion"

Template:

## Summary

{CONTENT}

## Use Case

## Proposed Solution

## Alternatives Considered

Suggested labels: enhancement, feature, feature-request, improvement

---

Question

Detection indicators:

• Keywords: how, what, why, when, where, which
• Patterns: Questions ending with "?", "help", "confused"

Template:

## Question

{CONTENT}

## Context

## What I've Tried

Suggested labels: question, help wanted, support

---

Documentation

Detection indicators:

• Keywords: docs, documentation, readme, typo, spelling
• Patterns: "example", "tutorial", "guide", "outdated"

Template:

## Description

{CONTENT}

## Location

## Suggested Change

Suggested labels: documentation, docs, readme

---

Title Prefixes

Detection Priority

When multiple types are detected, priority is:

1. Bug (error indicators take precedence) 2. Question (explicit question marks) 3. Feature (enhancement requests) 4. Documentation (doc-specific terms) 5. Unknown (default fallback)

Evolution Log

Convention: Reverse chronological order (newest on top, oldest at bottom). Prepend new entries.

---

2026-02-26: Initial Evolution Log

Status: Skill is in use and maintained. Track improvements here.

Purpose

This evolution log tracks updates to the skill. Each entry should note:

• What changed (content, structure, tooling)
• Why it changed (bug fix, feature request, best practice)
• Files affected

How to Use

1. When updating SKILL.md or references, add an entry here with the date 2. Keep entries reverse-chronological (newest first) 3. Link to ADRs or GitHub issues when relevant 4. Reference specific line changes when helpful

---

Label Strategy Reference

This document describes the label suggestion strategy used by the issue-create skill.

Core Principles

1. Taxonomy Awareness: Only suggest labels that exist in the repository 2. Conservative Suggestions: Suggest 2-4 labels (not too many) 3. Type Alignment: Prefer labels matching detected content type 4. Cache Efficiency: Cache labels per-repo for 24 hours

Label Suggestion Flow

1. Fetch Labels
   └── gh label list --repo OWNER/REPO --json name,description,color

2. Cache Check
   ├── Hit (< 24h) → Use cached labels
   └── Miss → Fetch fresh, cache result

3. AI Suggestion (if gh-models available)
   ├── Build prompt with available labels
   ├── Send to openai/gpt-4.1
   └── Parse JSON response

4. Fallback (keyword matching)
   ├── Match content against keyword patterns
   └── Return matching labels from taxonomy

5. Validation
   └── Filter out any labels not in taxonomy

AI Prompt Template

Suggest 2-4 labels from the EXISTING taxonomy only for this GitHub issue.
Never suggest labels that don't exist in the list below.
Return ONLY a JSON array of label names, nothing else.

AVAILABLE LABELS:
- bug: Something isn't working
- enhancement: New feature or request
- documentation: Improvements to docs
...

ISSUE TITLE: {title}
ISSUE BODY:
{body}

Return format: ["label1", "label2"]

Keyword Patterns (Fallback)

Cache Structure

Location: ~/.cache/gh-issue-skill/labels/{owner}_{repo}.json

{
  "labels": [
    {
      "name": "bug",
      "description": "Something isn't working",
      "color": "d73a4a"
    }
  ],
  "cachedAt": 1705123456789,
  "repo": "owner/repo"
}

Cache Management

# View cache
ls ~/.cache/gh-issue-skill/labels/

# Invalidate specific repo cache
rm ~/.cache/gh-issue-skill/labels/owner_repo.json

# Clear all cache
rm -rf ~/.cache/gh-issue-skill/labels/

Edge Cases

Empty Taxonomy

• Repository has no labels
• Behavior: Skip label suggestion, log warning
• User action: Consider adding labels to repository

Large Taxonomy (100+ labels)

• AI handles large taxonomies better than keywords
• Keyword fallback may be less accurate
• Consider enabling gh-models for best results

Private Repositories

• Requires appropriate GitHub authentication
• Uses gh CLI which handles auth automatically