issue-create
File a new GitHub issue in the checked-out repo — search first for duplicates/adjacent issues to update or reference, detect the repo's issue template if any, then compose title/body/labels/milestone
SKILL.mddot_claude/skills/issue-create/SKILL.md
GitHubIssue create
Don't file first. Search and inspect before composing.
Dedup pre-flight
Open and closed — omitting --state searches both:
gh search issues "<keywords>" --repo <owner>/<repo> --limit 20
Read near-matches with gh api repos/:owner/:repo/issues/<N>. Decide:
- Same outcome already open — update the existing one
(
mcp__github__issue_writewithmethod: updatefor the body,mcp__github__add_issue_commentfor new context). Don't file a new one. - Same outcome closed for stale reasons — reopen it
(
mcp__github__issue_write,method: update,state: open) with a comment citing what changed. Don't file a new one. - Adjacent (same area, different angle) — file new, cite the
existing in Additional context; consider an
issue-linksedge. - Partially covers — narrow the new issue to the uncovered slice; cross-reference both ways.
- Nothing close — file new.
If torn, surface the call rather than silently pick.
Detect repo conventions
ls .github/ISSUE_TEMPLATE/ 2>/dev/null
# REST reads — see ~/.claude/CLAUDE.md "GitHub API budget".
gh api 'repos/:owner/:repo/labels?per_page=100' --jq '.[].name'
gh api repos/:owner/:repo/milestones \
--jq '.[] | "\(.number)\t\(.title)"' # open only — can't assign a closed one
gh api 'repos/:owner/:repo/issues?per_page=5&state=all' \
--jq '.[].title' # skim recent house style
Template present → read it and fill its fields into the body. Templates encode the project's required fields; don't bypass with a freeform body.
Standard structure (no template)
- Title — statement true when done. Active voice, outcome. "Profile writes persist across API restarts in Firestore", not "Fix profile persistence".
- Summary — 1-2 sentences. What this delivers.
- Motivation — what problem, dependency, or opportunity drives it. Cite the trigger (PR review, incident, related issue).
- Scope — concrete changes, specific enough to start without guessing. Bullets, not prose.
- Acceptance criteria — measurable conditions,
- [ ]task-list. - Additional context — links, screenshots, related issues, only when they help. Skip the section if empty.
Labels and milestones
- Pick existing labels. Don't invent inline — if nothing fits, skip or raise the label question separately.
- Milestone: assign if closing the issue moves one of the milestone's key results (its "As measured by" checklist). Unset otherwise. Never use milestones as labels.
- Creating a new milestone →
milestonesskill. - Relating to other issues/PRs →
issue-linksskill, after submit.
Submit
Filing creates shared state — propose the body before submitting on any non-obvious choice (scope, label call, dedup verdict).
File with mcp__github__issue_write (method: create):
labels— array of existing label names.milestone— the number from the listing above, not the title.
Procedure
- Search open + closed; decide update / reopen / new / link.
- Detect template; else prepare standard structure.
- Fetch labels and milestones; pick fitters or skip.
- Compose; surface non-obvious choices.
- Submit; capture URL.
- Apply cross-edges via
issue-linksif related.