| name | gh-create-issue |
| description | Create GitHub issues from agent findings, bugs, regressions, UX problems, or follow-up work. Use when the user asks to create, file, or draft a GitHub issue and the result should be a structured issue body plus a `gh issue create` command. |
GitHub Issue Creation
Create issues with a concrete, reproducible body instead of a one-line summary.
When To Use
Use this skill when the user asks to:
- create a GitHub issue
- file a bug
- report an agent-found problem
- draft an issue body for manual review
Do not use it for PRs, code reviews, or release notes.
Workflow
- Gather the minimum factual context first.
- Prefer concrete repro steps, observed behavior, expected behavior, and scope.
- If the repo has an issue template, mirror its structure rather than inventing a new format.
- If the issue touches agent-specific files, prompts, or skills, inspect the matching
.claude and .codex paths and either make the equivalent update or call out the gap explicitly in the issue.
- If screenshots or images were provided in chat, do not upload them by default. Only upload and embed them if the user explicitly asks for that (see Uploading Images below).
- Write the issue body to a temp markdown file.
- Create the issue with
gh issue create --body-file ....
- Return the created issue URL to the user.
Structure
Unless the repository clearly uses a different format, prefer sections like:
## Summary## Issue Type## Priority## Agent Context## Area## Expected Behavior## Actual Behavior## Steps to Reproduce## Evidence## Frequency## Suspected Cause## Suggested Next Step## Validation After Fix
Keep issue bodies factual. Avoid speculative root causes unless labeled as suspicion.
Uploading Images
Images pasted into the chat thread appear in the conversation as [image: /absolute/path/to/file.png]
references. Those files live on this machine and are readable.
Only upload them when the user explicitly asks for the images to be uploaded to GitHub or embedded in
the issue body. If the user does not ask for upload, describe the screenshots in the issue and say
plainly that they were provided in chat but were not uploaded.
When upload was explicitly requested, upload each relevant image before writing the issue body:
bash .claude/skills/gh-create-issue/scripts/upload-assets.sh <path> [<path>...]
The script commits the files to the repo's issue-assets branch and prints one
 line per file. Paste those lines into the
Evidence / Screenshots section of the issue body. Notes:
- The script targets the current repo by default; pass
--repo owner/name to override.
- It requires push access. If the upload fails, fall back to the Evidence Rules below.
- Raw links only render for public repos. For a private repo, link the committed file path instead
and say the image requires repo access.
Codex Install Sync
After changing this checked-in skill or its helper scripts, refresh Codex's installed skills from the
repo root:
npm run sync:codex-skills
The sync command copies every checked-in skill from .claude/skills/ into ~/.codex/skills/. For
this issue skill, it also rewrites the image upload command in the Codex
copy so it points at the installed ~/.codex/skills/gh-create-issue/scripts/upload-assets.sh
helper instead of the checked-in .claude source path.
Evidence Rules
- Include short logs or error text inline when useful.
- If a screenshot exists but could not be uploaded to GitHub, say so plainly.
- Do not claim an image is attached unless the issue body contains a real image link or upload.
Command Pattern
Use a temp file for the body:
gh issue create --repo <owner/repo> --title "<title>" --body-file /private/tmp/<file>.md
If a --template flag conflicts with --body-file, prefer the explicit rendered body file.
Quality Bar
- Title should identify the user-facing problem, not the investigation process.
- Repro steps should be short and ordered.
- Validation should explain how to know the fix worked.
- Runtime and model should still be included only when they help reproduce or scope the issue.
