Submit current branch to main - PR creation, optional code review, squash merge, and branch cleanup. Ensures winter-blanket account is active.

Submit Skill

Submit the current branch to main: create PR, optional AI code review, squash merge, and clean up.

When to Activate

Use this skill when you need to:

  • Submit a feature branch to main
  • Create a pull request
  • Optionally run AI code review
  • Merge and clean up branches

Prerequisites Check

1. GitHub Account Verification (MANDATORY)

Before ANY git/gh operation, verify the active GitHub account:

1gh auth status
  • If the active account is NOT miyeon-cdl, run gh auth switch --user miyeon-cdl to switch to it.
  • If miyeon-cdl is not logged in at all, STOP and ask the user to authenticate first with gh auth login.
  • Do NOT proceed until the active account is confirmed as miyeon-cdl.

2. Branch Validation (with Auto-Branch from Main)

If the current branch is NOT main, proceed as before.

If the current branch IS main, automatically create a new branch:

Branch Name Generation

  • Format: MMDD-간략한-설명 (today's date + change summary in kebab-case)
  • Analyze staged/unstaged changes and recent commits to generate the description
  • Example: 0318-submit-스킬-자동분기-추가

Case A: Only uncommitted changes (no local-only commits on main)

  1. Run git log origin/main..main --oneline to check for local-only commits
  2. If no local-only commits exist: 
    1git checkout -b <auto-generated-branch-name>
  3. Uncommitted changes automatically carry over to the new branch
  4. Proceed to Auto-Commit step

Case B: Local-only commits exist on main

  1. Run git log origin/main..main --oneline to identify unpushed commits
  2. Inform the user: "main에 push되지 않은 커밋 N개가 있습니다. 새 브랜치로 옮기겠습니다."
  3. Create new branch and switch to it (uncommitted changes carry over automatically): 
    1git checkout -b <auto-generated-branch-name>
  4. Proceed to Auto-Commit step

Note: main에 남아있는 local-only 커밋은 PR 머지 후 Step 7에서 git pull로 자동 정리된다. git reset --hard는 커밋되지 않은 수정사항을 삭제하는 위험한 명령이므로 사용하지 않는다.

3. Auto-Commit Changes (MANDATORY)

IMPORTANT: Users typically run this skill without committing first. Always check for uncommitted changes OR lack of commits:

  1. Check commit status: Run git log main..HEAD to see if there are any commits on this branch
  2. Check for uncommitted changes: Run git status to see if there are any staged, unstaged, or untracked files

If EITHER condition is true (no commits exist OR uncommitted changes exist):

  1. Stage all changes: git add -A
  2. Analyze the changes and generate an appropriate conventional commit message
  3. Commit automatically - do NOT ask the user for confirmation
  4. If there are multiple logical groups of changes, commit them all together (since they will be squash-merged anyway)

After this step, verify that commits exist using git log main..HEAD. If still no commits, STOP and inform the user there's nothing to submit.

Execution Steps

Step 0: Update READMEs (MANDATORY - Always First)

PR을 올리기 전에 코드베이스의 README.md 파일을 최신 디렉토리 구조와 동기화한다.

중요: /update-readmes 스킬을 Skill 도구로 호출하지 않는다. 대신 Agent 도구(subagent_type: "general-purpose")를 사용하여 README 업데이트 작업을 서브에이전트에 위임한다. 이렇게 해야 서브에이전트 완료 후 submit 워크플로우가 Step 1부터 이어서 진행된다.

  1. Agent 도구로 서브에이전트를 실행한다. 프롬프트에 .claude/skills/update-readmes/SKILL.md의 프로세스를 따르도록 지시한다.

  2. 서브에이전트 완료 후, README가 업데이트되었으면 해당 변경사항은 Auto-Commit 단계에서 함께 커밋된다.

  3. 반드시 Step 1로 계속 진행한다.

Step 1: Gather Change Information

Run these commands in parallel to understand the full scope of changes:

  1. git status - Check for uncommitted changes
  2. git log main..HEAD --oneline - List all commits on this branch
  3. git diff main...HEAD --stat - Summary of all file changes vs main
  4. git diff main...HEAD - Full diff of all changes vs main

Step 2: Auto-Generate PR Content

git diff main...HEAD --stat 결과를 분석하여 변경된 파일이 어느 폴더에 속하는지 파악한다. 폴더별로 파일의 성격이 다르므로, 해당하는 섹션만 조합하여 PR 본문을 구성한다.

Title (under 70 characters):

  • Use conventional commit style prefix: feat:, fix:, refactor:, docs:, test:, chore:
  • Concise description of the overall change

Body — 아래 규칙에 따라 해당하는 섹션만 포함한다:

Case A: prototypes/ 변경이 있는 경우

소스코드가 포함된 폴더이므로 일반적인 소프트웨어 PR 양식을 사용한다.

1## Summary
2
3<1-3 bullet points describing what changed and why>
4
5## Changes
6
7<Bulleted list of specific code changes, grouped by category if needed>
8
9## Test Plan
10
11- [ ] <Checklist of things to verify>
prototypes/sokind-admin/ 변경 시 추가 섹션 (MANDATORY)

prototypes/sokind-admin/ 하위 파일에 변경이 있으면, 위 기본 양식에 더해 아래 섹션을 반드시 추가한다. 이 프로토타입은 제품 기획의 핵심이므로, 새로 구현된 기능과 디자인 변경사항을 PR에서 빠짐없이 명시해야 한다.

diff를 분석하여 아래 항목 중 해당하는 것만 포함한다:

1## sokind-admin 상세 변경사항
2
3### 새로 구현된 기능
4
5- <새 페이지, 컴포넌트, 모달, 기능 등을 구체적으로 기술>
6- <각 기능이 어떤 사용자 시나리오를 지원하는지 간략히 설명>
7
8### 변경된 디자인 스펙
9
10- <디자인 토큰, 레이아웃, 스타일 변경사항>
11- <컴포넌트 스펙 변경 (색상, 간격, 타이포그래피 등)>
12
13### 데이터 구조 변경
14
15- <목업 데이터, 타입 정의, 스키마 변경사항>
16
17### 수정/개선된 기존 기능
18
19- <기존 기능의 버그 수정 또는 동작 변경>

작성 지침:

  • diff의 실제 코드 변경을 근거로 작성한다 (추측하지 않는다)
  • 새 파일이 추가되었으면 해당 파일의 역할을 설명한다
  • UI 컴포넌트 변경은 사용자가 체감할 수 있는 수준으로 기술한다 (예: "회원 편집 모달에 역할 선택 드롭다운 추가" O, "member-edit-modal.tsx 수정" X)
  • 해당 사항이 없는 하위 섹션은 생략한다

Case B: knowledges/ 변경이 있는 경우

이 폴더에는 소스코드가 없고, 기획서·마케팅 콘텐츠 등 일반적인 '문서'만 존재한다. 따라서 어떤 문서의 어느 내용이 업데이트되었는지만 간결하게 요약한다.

1## 문서 변경 요약
2
3- **<문서 경로/파일명>**: <변경된 내용 요약>
4- **<문서 경로/파일명>**: <변경된 내용 요약>
5- ...

Case C: 기타 폴더(.claude/, scripts/, general-docs/ 등) 변경이 있는 경우

변경 성격에 맞춰 간결하게 요약한다.

1## Other Changes
2
3- <변경 사항 요약>

여러 폴더에 걸친 변경이 있는 경우

해당하는 Case의 섹션을 모두 포함하여 하나의 PR 본문으로 합친다. 예를 들어 prototypes/와 knowledges/ 모두 변경이 있으면 Case A + Case B 섹션을 함께 작성한다.

Present the generated PR content to the user for review before creating.

MANDATORY: User Approval Required

  • PR title and body를 사용자에게 보여주고 반드시 명시적인 승인을 받은 후에만 PR을 생성한다.
  • 사용자가 수정을 요청하면 반영 후 다시 승인을 받는다.
  • 승인 없이 gh pr create를 실행하지 않는다.

Step 3: Create Pull Request (after user approval)

1gh pr create --base main --title "<title>" --body "<body>"
  • Base branch is always main
  • No reviewers or assignees (solo project)
  • No draft mode (direct PR)

Step 4: Ask About Code Review

After PR creation, ask the user:

"PR created successfully. Would you like to run AI code review on the changes?"

Options:

  • Yes - Run the /code-review command on the PR diff
  • No - Skip code review and finish

Guidelines for the user:

  • Small changes (typos, config updates, docs) usually don't need review
  • New features, refactoring, or security-related changes benefit from review

Step 5: Code Review (if requested)

If the user requested code review:

  1. Use the code-reviewer agent to review all changed files in the PR
  2. Present the review results with severity levels (CRITICAL, HIGH, MEDIUM, LOW)
  3. If CRITICAL or HIGH issues are found:
    • Fix the issues
    • Commit fixes with message: fix: address code review findings
    • Push the fixes to the branch: git push
  4. If only MEDIUM/LOW issues are found:
    • Present them to the user
    • Ask if they want to fix them or proceed as-is

Step 6: Final Push and Sync

If there were any additional commits after PR creation (e.g. code review fixes):

1git push

Step 7: Merge PR and Clean Up

After all reviews and fixes are complete, automatically merge and clean up:

  1. Merge the PR using squash merge to keep main history clean:

    1gh pr merge --squash --delete-branch
    • --squash: Combines all branch commits into a single commit on main
    • --delete-branch: Deletes the remote branch after merge

  2. Switch to main and sync:

    1git checkout main && git pull origin main

  3. Delete local branch:

    1git branch -d <branch-name>

  4. Report the merged PR URL to the user when complete.

Step 8: Subtree Push

Note: 현재 subtree로 관리하는 프로토타입이 없으므로 이 단계는 건너뛴다. (sokind-vault-admin은 submodule 방식으로 별도 관리)

Step 9: Usage Report (MANDATORY - Always Last)

모든 작업이 완료된 후 마지막으로 AI 사용량 보고서를 생성한다.

9-1. 미사용 History 파일 수집

  1. .claude/usage/ 폴더의 usage-history-*.json 파일 목록을 수집한다
  2. .claude/usage/report/ 폴더의 기존 보고서를 모두 읽고, 각 보고서의 "출처" 섹션에 나열된 history 파일명을 추출한다
  3. 이미 보고서에 포함된 적 있는 history 파일을 제외하고, 아직 어떤 보고서에도 포함되지 않은 history 파일만 대상으로 삼는다
  4. 미사용 history 파일이 없으면 "보고할 새 history가 없습니다"라고 알리고 이 단계를 건너뛴다

9-2. History 파일 분석

수집된 모든 history JSON 파일을 읽고 다음을 집계한다:

  • 업무 내역: 각 세션의 workSummary와 userPrompts를 분석하여 업무를 카테고리별로 분류
  • Skills: 각 세션의 skills 배열에서 사용된 스킬명과 횟수
  • Agents: 각 세션의 agents 배열에서 에이전트명과 횟수 (에이전트명은 : 앞부분만 추출)
  • Tools: 각 세션의 tools 객체에서 도구명과 총 사용 횟수
  • Cost: 각 세션의 models 객체에서 모델별 비용과 토큰 사용량

9-3. 환율 조회

WebSearch 도구로 보고서 작성일 기준 원-달러 환율을 조회한다.

9-4. 보고서 작성

.claude/usage/report/ 폴더에 {날짜}-{branch명}.md 형식으로 보고서를 생성한다.

  • 날짜: YYYY-MM-DD 형식
  • branch명: 머지된 PR의 브랜치명 (kebab-case)
  • 예: 2026-04-03-0403-submit-스킬-리포트-추가.md

보고서 내용:

1# AI Usage Report: {branch명}
2
3> 생성일: {날짜} | 세션 수: {N}개 | 총 소요 시간: {X}분
4
5## 1. 업무 내역
6
7각 세션의 `workSummary`(첫 프롬프트 기반 요약)와 `userPrompts`(사용자 입력 원문)를 분석하여,
8업무를 아래 카테고리 중 해당하는 것으로 분류한다.
9
10**카테고리 분류 기준:**
11
12| 카테고리          | 판별 기준 (workSummary/userPrompts 키워드)                                 |
13| ----------------- | -------------------------------------------------------------------------- |
14| 프로토타입 개발   | sokind-admin, how-to-use-vault, frontend, 컴포넌트, 페이지, UI, 빌드, 에러 |
15| 마케팅/콘텐츠     | 블로그, SEO, 인터뷰, LinkedIn, 카피, 마케팅, paraggo                       |
16| 기획/PM           | PRD, 유저스토리, Linear, JTBD, 기능 정의, 요구사항                         |
17| 문서/지식관리     | 번역, Notion, README, 가이드, 문서                                         |
18| 인프라/설정       | Claude Code, hook, skill, 설정, 터미널, GCP, tmux                          |
19| 법률/컴플라이언스 | 약관, 개인정보, 법률                                                       |
20| 영업/자료         | 소개서, 소개 자료, collateral, 제안서                                      |
21| 기타              | 위 카테고리에 해당하지 않는 경우                                           |
22
23**출력 형식:**
24
25카테고리별로 해당 세션의 업무를 나열하고, 각 업무의 비용을 표시한다.
26
27```markdown
28### 프로토타입 개발 — $XX.XX
29
30| 업무                                  | 비용 (USD)               | 시간 (분)         |
31| ------------------------------------- | ------------------------ | ----------------- |
32| {workSummary 첫 줄, 80자 이내로 요약} | ${totalEstimatedCostUSD} | {durationMinutes} |
33
34### 인프라/설정 — $XX.XX
35
36| 업무               | 비용 (USD) | 시간 (분)  |
37| ------------------ | ---------- | ---------- |
38| {workSummary 요약} | ${cost}    | {duration} |
39```
  • 각 카테고리 제목에 해당 카테고리의 소계 비용을 표시한다
  • 업무가 0건인 카테고리는 생략한다
  • 한 세션이 여러 카테고리에 걸치면, workSummary의 주된 목적 기준으로 하나만 선택한다
  • workSummary가 비어있으면 userPrompts 첫 항목으로 대체한다. 둘 다 없으면 "(내용 없음)"으로 표시한다

2. Skills

스킬명사용 횟수
{skill}{count}

사용된 스킬이 없으면 "사용된 스킬 없음"으로 표시

3. Agents

에이전트명사용 횟수
{agent}{count}

4. Tools

도구명사용 횟수
{tool}{count}

(사용 횟수 내림차순 정렬)

5. Cost

모델별 비용

모델Input TokensOutput TokensCache ReadCache Creation비용 (USD)
{model}{n}{n}{n}{n}${cost}

총 비용

  • Total USD: ${total}
  • 환율 (작성일 기준): 1 USD = {rate} KRW
  • Total KRW: ₩{total × rate} (소수점 이하 반올림)

6. AI 토큰 비용 최적화 제안

{history 데이터를 분석하여 비용 절감 가능한 부분을 구체적으로 제안}

예시 관점:

  • Opus 대신 Haiku/Sonnet으로 대체 가능한 작업이 있었는지
  • 캐시 히트율이 낮은 세션이 있었는지
  • 도구 호출 횟수가 비정상적으로 많은 세션이 있었는지
  • 특정 에이전트의 비용 대비 효과가 낮았는지

7. 출처

이 보고서에 사용된 history 파일:

  • {filename1}
  • {filename2}
  • ...
1
2#### 9-5. 보고서 커밋
3
4보고서 파일을 커밋한다. 이 커밋은 이미 main에 머지된 후이므로, main 브랜치에서 직접 커밋 & push한다:
5
6```bash
7git add .claude/usage/report/{보고서파일}
8git commit -m "docs: add AI usage report for {branch명}"
9git push origin main

Error Handling

  • If gh pr create fails because a PR already exists, inform the user and provide the existing PR URL
  • If push fails, check if the remote branch exists and suggest git push -u origin <branch>
  • If the branch has no commits ahead of main, inform the user there's nothing to create a PR for

Example Usage

1User: Can you submit this branch?
2
3Agent:
41. Checking GitHub account... miyeon-cdl confirmed.
52. Current branch: feat/add-login-page (3 commits ahead of main)
63. Generated PR:
7   Title: feat: add login page with email authentication
8   Body: ...
94. PR #12 created: https://github.com/winter-blanket/makespace/pull/12
105. Would you like to run AI code review? [Yes/No]
116. (after review) Merging PR #12 via squash merge...
127. Switched to main, pulled latest, deleted local branch.
13   Done! PR #12 merged: https://github.com/winter-blanket/makespace/pull/12

Integration with Other Commands

  • /code-review - Invoked optionally during submit process
  • /plan - Use before this skill to plan implementation
  • /tdd - Use before this skill to ensure test coverage

Best Practices

  1. Always update READMEs first - Ensure documentation is in sync before PR
  2. Always verify GitHub account - Prevent commits to wrong account
  3. Auto-commit changes - Users often forget to commit before submitting
  4. Generate meaningful PR titles - Use conventional commit format
  5. Squash merge - Keep main branch history clean
  6. Clean up branches - Delete both remote and local branches after merge
  7. Optional code review - Let user decide based on change complexity

Remember: This skill automates the entire PR workflow from creation to merge, ensuring consistency and reducing manual steps.