# Report Issue

> 자연어로 이슈 내용을 말하면 GitHub 이슈 초안을 작성하고 생성하는 스킬. 버그, 기능 요청, 개선, 작업 등 모든 유형의 이슈를 다룬다. 다음 표현이 나오면 반드시 이 스킬을 사용할 것: - "이슈 올려줘", "이슈 만들어줘", "이슈 생성해줘", "깃허브 이슈" - "github issue", "issue 올려줘", "report-issue" - "버그 리포트", "버그 이슈", "버그 올려줘" - "기능 요청 이슈", "개선 이슈", "작업 이슈"

- Skill: `gagip/report-issue` (Agent Skill)
- Install (CLI): `npx skillmds@latest add gagip/report-issue`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gagip/report-issue/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: gagip (https://skillmd.com/u/gagip)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/gagip/report-issue

---


## 작업 흐름

### 1단계: 맥락 파악

현재 레포 확인 (이 스킬은 어느 레포에서든 실행되는 범용 스킬이다 — 지금 작업 중인 레포 기준으로 매번 새로 조회한다):

```bash
gh repo view --json nameWithOwner,owner,visibility
gh label list
gh api "repos/{owner}/{repo}/milestones?state=open"
gh api user -q .login
```

레포 소유자가 `gh api user`로 확인한 **내 개인 계정**과 같고 visibility가 `PRIVATE`이면 "개인 private 레포"로 판단한다 — 3단계 STOP을 생략한다 (아래 3단계 참고). 그 외에는 기존대로 STOP을 지킨다.

사용자가 제공한 내용에서 다음을 추출:
- **무엇이 문제인가 / 무엇이 필요한가** (증상 또는 요구사항)
- **어떤 환경·범위인가** (플랫폼, 화면, 기능 영역)
- **완료 기준은 무엇인가** (언제 이슈를 닫을 수 있는가)

정보가 부족하면 한 번만 질문한다. 여러 번 묻지 않는다.

### 2단계: 타입·우선순위·담당자·마일스톤 판단

**타입** — 사용자 말에서 추론한다:

| 표현 예시 | 타입 |
|-----------|------|
| "안 돼요", "동작 안 해", "깨졌어", "오류" | `fix` |
| "추가해줘", "만들어줘", "기능이 필요해" | `feat` |
| "느려", "개선", "더 좋게" | `perf` / `feat` |
| "코드 정리", "리팩터링" | `refactor` |
| "설정", "패키지", "환경" | `chore` |

**우선순위** — `priority: high/medium/low` 라벨이 레포에 있으면(`gh label list` 결과 기준), 완료 기준·영향 범위로 추론해 하나를 추천한다. 그런 라벨 체계가 없는 레포면 이 항목은 건너뛴다:

| 신호 | 우선순위 |
|------|---------|
| 로그인·인증 실패, 데이터 유실·손상, 보안 취약점, 크래시, 핵심 플로우 완전 차단 | `high` |
| 그 외 일반 버그, 기능 요청, UX 개선 | `medium` |
| 코드 정리, 리팩터, 사소한 UI 오차, 테스트 보강 | `low` |

**담당자** — 완료 기준이 **지금 작업 중인 레포 코드 변경만으로 달성 가능한지**로 판단한다:
- 가능 → `@me`
- 이 레포 밖(다른 레포·다른 팀 영역) 변경이 필요 → 미배정 + 본문 참고(Notes)에 "타 레포/팀 협의 필요"라고 명시. 다른 사람에게 자동으로 배정하지 않는다(다른 팀·다른 트래커에서 별도로 관리되는 작업일 수 있어서).

**마일스톤** — 1단계에서 조회한 열린 마일스톤 목록과 이슈 내용을 비교해 가장 가까운 것 하나를 후보로 고른다. 열린 마일스톤이 없거나 뚜렷하게 맞는 게 없으면 배정하지 않는다("해당 없음"으로 표시).

### 3단계: 이슈 초안 작성 후 반드시 멈춤 [STOP]

아래 형식으로 초안을 작성해 사용자에게 보여준다. 본문(마크다운)과 메타데이터를 함께 제시한다.

**제목**: `타입: 한 줄 요약 (동사 원형으로 시작)`

**라벨**: `<타입>`(, `priority: <추정치>` — 해당 라벨 체계가 있을 때만)
**담당자**: `@me` (또는 "미배정 — 타 레포/팀 협의 필요")
**마일스톤**: `<추천 마일스톤명>` (또는 "해당 없음")

```markdown
## 문제 (Problem)
<!-- 지금 무엇이 깨져 있거나 부족한가. 증상과 영향 범위를 1-3문장으로. -->

## 작업 범위 (Scope)
<!-- 이번 이슈에서 바꾸는 것. 바꾸지 않는 것도 명시하면 좋음. -->
-

## 완료 기준 (Done When)
<!-- 검증 가능한 형태로. -->
-

## 참고 (Notes)
<!-- 재현 환경, 관련 이슈·PR 링크. 타 레포/팀 협의가 필요하면 여기 명시. 없으면 섹션 생략. -->
```

작성 원칙:
- 개조식, 간결하게
- 구현 세부 사항(코드 라인 등)은 PR에 — 이슈에 넣지 않음
- 검증 시나리오 전체는 PR checklist에 — 이슈에는 완료 기준만
- **외부 협업자가 알 필요 없거나 이해할 수 없는 private·내부 전용 정보는 본문에 넣지 않음** — 개인 메모, 로컬 경로·내부 IP, 내부 임시 분석 등. 공유 가능한 형태로 요약하거나 제외

**1단계에서 "개인 private 레포"로 판단된 경우**: 대기하지 않고 바로 4단계로 진행한다.

**그 외의 경우**: 초안 작성 후 사용자 확인을 기다린다. 라벨·담당자·마일스톤 추정치도 같이 확인받는다. 수정 요청이 오면 반영 후 다시 대기한다.

### 4단계: 이슈 생성 [사용자 명시적 승인 후에만]

"올려줘", "생성해줘", "만들어줘", "ok", "좋아" 등 명시적 지시 후 실행. `--assignee`는 담당자가 `@me`일 때만, `--milestone`은 후보가 있을 때만, priority 라벨은 그 라벨 체계가 있을 때만 붙인다(해당 없으면 그 플래그 자체를 뺀다):

```bash
# 담당자 @me + 마일스톤 있음 + priority 라벨 체계 있음 — 전부 해당하는 예시
gh issue create \
  --title "<제목>" \
  --label "<타입>" --label "priority: <추정치>" \
  --assignee "@me" \
  --milestone "<마일스톤명>" \
  --body "$(cat <<'EOF'
<본문>
EOF
)"

# 미배정 + 마일스톤 없음 + priority 라벨 없음이면 해당 플래그들을 뺀 형태로 실행
```

- 라벨은 `gh label list`로 확인한 것만 사용
- 생성 완료 후 이슈 URL 전달
- 이슈 번호를 브랜치명에 연결할 수 있음을 안내 (예: `fix/19-ios-logout-confirm-button`)