Skip to main content
skill CX Codex

issue-create · terrylica — Claude Code skill: well-formed GitHub issues with AI labels

issue-create turns a rough description into a formatted GitHub issue: detects the type, picks labels that exist in the repo, and warns about duplicates before you post.

MIT 129 installs ★ 3 updated 2026-10-25

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add terrylica/cc-skills --skill issue-create -a claude-code
Open on GitHub

What issue-create does

First the skill decides what you are filing: a bug, a feature request, a question or a docs fix. Each type gets its own body layout — reproduction steps and expected behaviour for bugs, a use case and proposed solution for features. The title is pulled out of your text and prefixed with something like Bug:.

Labels come from what the repository already uses. You get two to four of them, and the list is cached for 24 hours. A search for similar issues runs before anything is posted, so likely duplicates surface early. Bodies can hold up to 65,536 characters, and the skill advises aiming near 60,000 to leave room for GFM rendering. A full preview is shown first; --dry-run stops there and --no-ai keeps the model out of it.

The gh CLI is required, and bun runs the script. AI hints need the gh-models extension. Token rights change the result: WRITE or ADMIN posts the issue, while READ hands you formatted text to paste yourself.

What it helps with

  • file a bug report with reproduction steps
  • pick labels that already exist in the repo
  • spot duplicate issues before posting
  • preview the whole issue without creating it
  • fit a long write-up into one issue body

Example prompts for the agent

  • File a bug about the login form crashing on special characters, and work out the repo yourself.
  • Run /gh-tools:issue-create with the body "API returns 500 on /users" and suggest labels for it.
  • Search for issues about the timeout error and warn me if mine is a duplicate.

How to install issue-create

1Skills CLI (Vercel)

npx skills add terrylica/cc-skills --skill issue-create -a claude-code

2Manually: put the files in place

~/.claude/skills/issue-create/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/issue-create/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about issue-create

How do I install issue-create in Claude Code?

Run npx skills add terrylica/cc-skills --skill issue-create -a claude-code. The skill lands at ~/.claude/skills/issue-create/SKILL.md.

What does issue-create do?

It builds a GitHub issue from your description, formats the body for the detected type, suggests labels the repo already has, and checks for related issues.

Do label suggestions need the gh-models extension?

The gh CLI is required either way. Type detection and label suggestions use gh-models; without it the skill falls back to keyword matching, and --no-ai turns the model off on purpose.

Source text

SKILL.md · MIT
---
name: issue-create
description: "Create well-formatted GitHub issues with AI label suggestions: bug reports, feature requests, questions, docs issues. TRIGGERS - file an issue, create an issue, gh issue create."
allowed-tools: Read, Bash, Grep, Glob
---

# 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**:

```bash
# 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

```bash
# 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

```bash
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)

```bash
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

```bash
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

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

## CLI Options

| Option      | Short | Description                     |
| ----------- | ----- | ------------------------------- |
| `--repo`    | `-r`  | Repository in owner/repo format |
| `--body`    | `-b`  | Issue body content (required)   |
| `--title`   | `-t`  | Issue title (optional)          |
| `--labels`  | `-l`  | Comma-separated labels          |
| `--dry-run` |       | Preview without creating        |
| `--no-ai`   |       | Disable AI features             |
| `--verbose` | `-v`  | Enable verbose output           |
| `--help`    | `-h`  | Show help                       |

## Dependencies

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

### Installing gh-models

```bash
gh extension install github/gh-models
```

## Permission Handling

| Level       | Behavior                                |
| ----------- | --------------------------------------- |
| WRITE/ADMIN | Full functionality                      |
| TRIAGE      | Can apply labels                        |
| READ        | Shows formatted content for manual copy |
| NONE        | Suggests fork workflow                  |

## 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](./references/content-types.md)
- [Label Strategy Reference](./references/label-strategy.md)
- [AI Prompts Reference](./references/ai-prompts.md)

## 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](https://github.com/cli/cli/issues/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:**

```bash
# 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):

| Step | Check                  | Failure Mode                                     |
| ---- | ---------------------- | ------------------------------------------------ |
| 1    | Repo context exists    | No `OWNER_REPO` to build URLs                    |
| 2    | Images are git-tracked | `.gitignore` silently excludes them              |
| 3    | Images are committed   | Staged/untracked files don't exist on remote     |
| 4    | Commit is pushed       | Local-only commits are invisible to `github.com` |
| 5    | URL construction       | Wrong branch name → 404                          |

### 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`:

```markdown
<!-- 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):

```bash
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](../issues-workflow/references/gfm-antipatterns.md#ap-07-private-repo-image-urls-render-as-broken) for the full technical explanation.

### Images NOT in the Repository

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

| Method                    | How                                                              | Permanent?                   | Preflight?   |
| ------------------------- | ---------------------------------------------------------------- | ---------------------------- | ------------ |
| **Commit + push first**   | `git add` images, push, run preflight, then use `?raw=true` URLs | Yes (repo-hosted)            | Yes (5-step) |
| **Web UI paste**          | Open issue in browser, Ctrl/Cmd+V images into comment box        | Yes (`user-attachments` CDN) | None         |
| **Web UI drag-and-drop**  | Drag image files into the comment box                            | Yes (`user-attachments` CDN) | None         |
| **Playwright automation** | Script automates the browser file-attachment flow                | Yes (`user-attachments` CDN) | None         |

#### 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.

Browser routes in general: [`chrome-profiles`](../../../chrome-profiles/skills/browser-automation/SKILL.md).

**How it works:**

1. [`scripts/gh-issue-image-upload.ts`](./scripts/gh-issue-image-upload.ts) opens the issue page in Playwright's Chromium with a persistent profile (`~/.local/share/gh-issue-image-upload/profile`, override `GH_ISSUE_IMAGE_PROFILE`). Run it with `bun "$(cc-plugin-root gh-tools)/skills/issue-create/scripts/gh-issue-image-upload.ts" <issue-url> <image>...`
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("")`

**Browser route**: this is rung 2 of the [`chrome-profiles`](../../../chrome-profiles/skills/browser-automation/SKILL.md) ladder (Playwright's own Chromium, signed in once), which keeps it independent of your everyday Chrome. If GitHub is already signed in to an everyday profile, that plugin's `setup <email>` can drive it instead; the debug-port and Chrome-136 mechanics are documented there, not here.

---

## 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:

```bash
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.

© terrylica · MIT · terrylica/cc-skills

Similar skills

All skills for Git and GitHub →

issue-create by other authors comes first.

issue-create modelcontextprotocol issue-create walks an issue from duplicate check to a board card with status and priority. Useful when work turns up mid-task and needs its own issue. CX Codex +1 ★ 92,149repo stars create-issue dyoshikawa create-issue — a skill that walks through issue creation step by step: gathers context, checks the codebase, drafts English text, and assigns labels. Handy when you want a tidy issue without doing it manually. CX Codex +1 ★ 1,636repo stars create-scrap-issue dyoshikawa The create-scrap-issue skill turns notes and findings into one GitHub issue with context, details, and next steps. Use it when you want to keep project scraps for later. CX Codex +1 ★ 1,636repo stars issue-label toss issue-label is a Claude Code skill that reads GitHub issue content, selects a label from the project matrix, and applies it with one command. CX Codex +1 206installs antfu-issue-triage Anthony Fu antfu-issue-triage — a skill for Claude Code that investigates open GitHub issues and pull requests in the active repository. It detects resolved bugs, duplicates, and spam, generating an action plan before edits. CX Codex +1 413installs issue-progress-tracking OrchestKit issue-progress-tracking guides GitHub issue ceremonies using the gh CLI by updating progress labels, creating dedicated branches, enforcing atomic commits, and linking PRs. CX Codex +1 221installs github-issue-creator alex-ilgayev github-issue-creator is a Claude Code skill that creates GitHub issues for MCPSpy. It runs when asked to report a bug, propose a feature, or record technical debt. CX Codex +1 1installs

From the same set79

The whole set →
terminal-print terminal-print turns iTerm2 output or a session file into a PDF, then sends it to a network printer. It also provides an AirPrint workaround for blank pages on listed HP LaserJet Pro models. CX Codex +1 131installs doppler-workflows The doppler-workflows skill guides commands that use Doppler secrets for Python package publishing and AWS tasks. It also covers common authentication errors. CX Codex +1 130installs ml-data-pipeline-architecture The ml-data-pipeline-architecture skill covers ML data pipelines built with Polars, Arrow, and ClickHouse. Use it to choose between Polars and Pandas or prepare data for PyTorch. CX Codex +1 130installs clickhouse-pydantic-config clickhouse-pydantic-config turns Pydantic v2 ClickHouse models and environment variables into a DBeaver connection file. Handy when one repo talks to both a local and a cloud database. CX Codex +1 130installs asciinema-streaming-backup asciinema-streaming-backup streams asciinema terminal recordings to an isolated GitHub orphan branch using zstd and brotli compression. CX Codex +1 128installs multi-agent-e2e-validation The multi-agent-e2e-validation skill for Claude Code and other AI editors spawns multiple validation agents in parallel to test database refactors comprehensively. CX Codex +1 128installs link-validator The link-validator skill detects absolute paths in markdown links that break when a skill is installed elsewhere. Run it before sharing a skill or after adding new links. CX Codex +1 127installs session-info session-info returns the active Claude Code session UUID and session chain cache details. Helpful for debugging and linking transcripts to sessions. CX Codex +1 127installs

Project sponsors

Companies that keep this analytics open