서론

안녕하세요. 주식회사 에이아이 시큐리티 랩(Aeye Security Lab)에서 SaaS형 Web 애플리케이션 취약점 진단 플랫폼 「AeyeScan」의 개발 엔지니어를 맡고 있는 아리마입니다.

릴리스 담당으로서, 2주에 1회 정도 진행되는 릴리스마다 매번 10건 전후의 Issue나 PR을 확인하고 있습니다. 릴리스 전체 내용을 대략적으로 파악하고, 타 부서에도 전달될 수 있는 형태로 개요를 정리합니다.

담당이 되자마자 "더 편하게 할 수 없을까"라고 생각했습니다. 1건씩 확인하는 것 자체는 어렵지 않습니다. 다만, 10건 분량을 읽고 내용을 파악하여 타 부서용 언어로 정리하는 작업. 이를 매번 수동으로 하면 은근히 시간이 소요됩니다.

그래서 Claude Code의 **Skills(스킬 기능)**와 **GitHub CLI (gh)**를 조합하여 이 작업을 자동화했습니다. 사용법은 간단합니다. 캐치업하고 싶은 Issue나 PR의 URL을 모아서 복사한 뒤, "릴리스 내용 정리해줘"라고 말하기만 하면 됩니다. 이것은 우선,

내가 릴리스 내용을 캐치업하기 위한 도구입니다. 거기에 더해,

그대로 타 부서에 공유할 수 있는 개요를 평이한 문장으로 정리해 주도록 만들었습니다.

결과적으로 "내가 변경 내용을 파악하는 것"과 "공유용 개요를 준비하는 것"이 동시에 해결되게 되었습니다.

Claude Code는 사용하고 있어도 Skills는 아직 잘 모르겠다는 분들이 많을 것이라 생각합니다. 이 기사에서는 실제로 만든 Skill을 소재로, 그 제작 방법과 설계 포인트를 소개합니다.

Claude Code의 스킬 기능이란

Claude Code의 Skills는 특정 작업 절차나 판단 기준을 SKILL.md라는 파일에 저장해 둘 수 있는 메커니즘입니다.

매번 프롬프트에 긴 지시 사항을 쓰는 대신, "이 작업에서는 무엇을 보고, 어떻게 판단하며, 어떤 형식으로 출력할 것인가"를 하나의 파일에 모아둘 수 있습니다.

슬래시 커맨드로도, 자연스러운 언어로도 호출 가능

/usage와 같은 슬래시 커맨드(Slash Command)를 사용해 본 적이 있는 분들도 많을 것입니다. Claude Code의 Skills도 /release-catchup처럼 수동으로 호출할 수 있지만, 흥미로운 점은 **"호출 방법을 외울 필요가 없다"**는 점입니다.

SKILL.md의 프론트매터(Frontmatter)에 작성한 description을 Claude가 읽어 들여, 자연스러운 언어로 의뢰하는 것만으로 관련 Skill이 자동으로 선택됩니다. "릴리스 내용 정리해줘"라고 말하면 이번 Skill이 선택되는 방식입니다.

파일 구성

# 글로벌 (모든 프로젝트에서 사용 가능)
~/.claude/skills/
└── release-catchup/
...

Claude Code에서는 디렉터리 이름이 /release-catchup과 같은 호출명이 됩니다. name은 표시 이름으로서 디렉터리 이름과 일치시켜 두면 알아보기 쉽습니다.

작성 자체는 간단합니다. Skill용 디렉터리를 만들고 그 안에 SKILL.md를 두기만 하면 됩니다.

mkdir -p ~/.claude/skills/release-catchup
touch ~/.claude/skills/release-catchup/SKILL.md

SKILL.md의 구조

SKILL.md는 프론트매터와 본문으로 구성됩니다.

---
name: release-catchup
description: |
...

포인트는 description입니다. 여기에 "어떤 의뢰로 사용하는 Skill인지"와 "반응해주길 바라는 문구"를 적어둠으로써 Claude가 자동으로 호출하는 계기가 됩니다.

정해진 커맨드를 외워서 입력하는 것이 아니라, 평소 대화의 연장선에서 자신만의 절차를 그대로 실행한다. 이 메커니즘이 실제로 사용해 보았을 때 가장 편리하다고 느낀 점입니다.

참고로, Claude Code Skills의 사양은 업데이트될 수 있습니다. 본 기사는 2026년 6월 시점에서 사용 중인 구성을 바탕으로 하고 있습니다.

구현: GitHub CLI와의 조합

만든 Skill의 전체적인 흐름은 다음과 같습니다.

실제 SKILL.md의 내용은 다음과 같습니다 (실제 파일을 바탕으로 사내 고유 규칙을 범용화한 샘플입니다).

SKILL.md 구성 예시

---
name: release-catchup
description: |
...

**B. PR URL**

**C. 커밋 (Commit) URL**

**D. 텍스트 설명 + URL 혼재 (스프레드시트 등에서 복사/붙여넣기 등)**

다크 모드 대응 https://github.com/org/repo/issues/101
목록 정렬 추가 https://github.com/org/repo/issues/102

**E. CSV 형식**

날짜,프로덕트,종류,담당자,내용,URL,비고
5/25,SampleApp,기능 추가,〇〇,다크 모드 대응,https://github.com/org/repo/issues/101,

---
## 실행 절차
### Step 1: gh auth 확인
```bash
gh auth status

인증되지 않은 경우 사용자에게 gh auth login을 권장한다.

Step 2: URL 종류를 판정하여 데이터 취득

URL 종류 (issue / PR / commit)를 자동 판정하고, 각각 적절한 명령어로 취득한다.
...

gh issue view {issue번호} --repo {owner}/{repo} \
--json title,body,labels,assignees,comments,closedByPullRequestsReferences

PR URL의 경우

PR을 직접 취득한다 (Step 3·4를 스킵).

gh pr view {PR번호} --repo {owner}/{repo} \
--json title,body,assignees,additions,deletions,mergedAt,files

커밋 (Commit) URL의 경우

gh api /repos/{owner}/{repo}/commits/{sha}

커밋 메시지·저자·변경 파일 목록을 취득한다.

Step 3: 연결된 PR 특정 (issue의 경우에만)

closedByPullRequestsReferences에 PR 번호가 있으면 그것을 사용한다.
...

gh pr list --repo {owner}/{repo} --state merged \
--search "#{issue번호}" --json number,title,mergedAt

만약 찾을 수 없는 경우에는 issue 제목의 일부를 키워드로 하여 검색한다.

Step 4: PR의 파일 목록을 취득하여 변경 범위를 파악한다

gh pr view {PR번호} --repo {owner}/{repo} \
--json title,body,files,additions,deletions,mergedAt

변경 파일 목록에서 읽어들이는 것은 다음 범위로 한정한다:

• 어떤 파일이 바뀌었는가 (기능의 변경 범위 파악)
• 테스트 파일의 추가 여부 (품질 보증 확인)
  ...

gh pr diff {PR번호} --repo {owner}/{repo}

Step 5: 비엔지니어용 요약 리포트 생성

취득한 정보 (issue 본문·PR 코멘트·코드 차분 (diff))를 종합하여 요약한다.
요약 관점 (3개 섹션 구성):
...

# 릴리스 캐치업 {날짜}
생성 일시: {timestamp} / 대상: {n}건
---
## {프로덕트명}
### {제목}
#{번호} | {종류} | 담당: {담당자명} | {mergedAt}
#### 개요
{배경·문제점을 2~3문장으로}
#### 대응·변화
- {변경점1}
- {변경점2}
#### 사용자 경험의 변화
{경험 레벨의 변화를 1~2문장으로}
---
## 취득할 수 없었던 항목
- #{번호}：{이유}

---

파일 출력

리포트 생성 후, 다음 경로에 저장한다:

~/release-notes/release-catchup-{YYYY-MM-DD}.md

같은 날에 여러 번 실행한 경우에는 끝에 일련번호를 붙인다 (예: release-catchup-2026-05-15-2.md).

에러 핸들링 (Error Handling)

...

### 입력 형식은 의도적으로 느슨하게 허용한다

매번 깔끔한 URL만 들어오는 것은 아닙니다. 스프레드시트에서 복사한 문자열이나, 메모와 URL이 섞인 상태에서도 동작하도록 만들었습니다. 구체적으로는 다음 형식을 모두 수용합니다.

**A. Issue URL**

**B. PR URL**

**C. 커밋 (Commit) URL**

**D. 텍스트 설명 + URL 혼재 (스프레드시트 복사/붙여넣기 등)**

다크 모드 대응 https://github.com/org/repo/issues/101
목록 정렬 추가 https://github.com/org/repo/issues/102

**E. CSV 형식**

날짜,프로덕트,종류,담당자,내용,URL,비고
5/25,SampleApp,기능 추가,〇〇,다크 모드 대응,https://github.com/org/repo/issues/101,

입력을 너무 엄격하게 제한하면, 결국 "AI에게 전달하기 전의 정제 작업"이 남게 됩니다. 그 과정을 없애는 것을 가장 우선적으로 의식했습니다.

### GitHub CLI로 데이터 가져오기

URL 종류(Issue / PR / commit)를 자동으로 판정하여, 각각 적절한 명령어로 가져옵니다.

전제로, 로컬 환경에서 GitHub CLI를 사용할 수 있는 상태여야 합니다. GitHub 로그인이 완료되어 있고, 대상 리포지토리(Repository)의 Issue나 PR을 참조할 수 있는 권한이 있는 상태를 가정합니다.

Issue의 경우

gh issue view 1234 --repo org/repo
--json title,body,labels,assignees,comments,closedByPullRequestsReferences
...

Issue만 전달된 경우에도 관련 PR을 찾도록 설계했습니다. 먼저 `closedByPullRequestsReferences`를 확인하고, 찾을 수 없다면 Issue 번호나 타이틀 키워드로 `gh pr list`를 검색합니다.

### 차이점(구현 내용)까지 읽게 하여 정확도 높이기

Issue나 PR의 본문은 작성자에 따라 상세도와 작성 방식이 제각각입니다. 배경까지 친절하게 적혀 있는 경우도 있지만, 타이틀과 짧은 한 줄만 있는 경우도 있습니다. 본문에만 의존하면 요약의 정밀도가 이러한 "작성 방식의 편차"에 휘둘리게 됩니다.

그래서 이 Skill은 **차이점(diff)을 전제로 설계되었습니다**. `gh pr view`의 메타 정보에 더해, `gh pr diff`를 통해 구현의 차이점까지 읽게 함으로써, 1차 정보인 **실제 코드의 변경 사항 그 자체**로부터 "무엇이 바뀌었는가"를 직접 파악합니다. 코드를 가져와서 읽는 단계까지 스스로 실행할 수 있는 Claude Code이기에 가능한 방식입니다.

단, 차이점(diff)을 사용하는 용도는 의식적으로 구분하고 있습니다.

- diff는 "무엇이 바뀌었는가"에 대한 **사실 확인**에 사용한다 (OK)
- diff를 통해 "왜 바꿨는가", "이전에는 어떠했는가"를 **추측으로 보완하지 않는다** (NG)

### 설계의 핵심: 추측하지 않기

그 구분점을 지탱하는 것이 요약 규칙에 적은 다음 문장입니다.

> 쓸 수 없는 정보는 쓰지 않는다. 추측·보완·지어내기는 엄금. "이전에는 ~라는 문제가 있었다", "~할 수 없었다" 등의 과거 상태는 Issue / PR 본문 및 코멘트에 명시되어 있는 경우에만 작성한다.

AI에게 자유롭게 쓰게 하면 그럴싸한 설명을 만들어내곤 합니다. 예를 들어, 차이점만 보고 "사용자의 조작 실수를 줄이기 위해 UI를 개선했다"라고 쓸 수 있을 것처럼 보여도, Issue나 PR에 그 배경이 적혀 있지 않다면 그것은 단순한 추측일 뿐입니다.

타 부서에 공유하는 문서는 편리해 보이는 것보다 사실로서 설명할 수 있는 것이 더 중요합니다. 그렇기에 "쓸 수 없는 것은 쓰지 않는다"라는 규칙을 Skill에 강력하게 반영했습니다.

### 비엔지니어 대상 출력 규칙

어휘 규칙도 프롬프트에 심어두었습니다.

- 기술적인 용어(파일명, 함수명, DB 등)는 사용하지 않고 평이한 단어로 대체한다
- 경험 측면의 변화에 초점을 맞춘다 ("~할 수 있게 되었다", "~하기 쉬워졌다")

지금까지 제가 암묵적으로 해왔던 "이 용어는 사내에서는 통하지만 타 부서에는 적합하지 않다", "이것은 구현 상세(Implementation Detail)이므로 공유 시에는 생략한다"와 같은 판단을 그대로 Skill에 써 내려가는 이미지입니다.

## 출력 예시

실제로는 항목별로 나뉘지 않고 **하나의 Markdown 파일**로 합쳐져서 출력됩니다. 제품명 헤더 아래에 각 항목이 「개요 / 대응·변화 / 사용자 경험의 변화」 단위로 나열됩니다 (내용은 더미 데이터입니다).

릴리스 캐치업 2026-06-23

생성 일시: 2026-06-23 / 대상: 3건

...

이와 같이 「개요」, 「대응·변화」, 「사용자 경험의 변화」가 항목별로 나열된 1개의 파일로 출력됩니다. 「대응·변화」에서는 GitHub CLI의 `gh pr diff`로 읽어들인 구현 차분(Diff)에서 추출한 구체적인 변경점이 불렛 포인트로 나열됩니다. 기술적인 변경 내용을 타 부서에 그대로 공유할 수 있는 수준의 문장으로 풀어내 주는 것이 포인트입니다.

### Before / After

먼저 바뀐 점은 저의 캐치업(Catch-up) 수고입니다. 릴리스 전체를 파악하기 위한 작업이 이전보다 짧게 끝날 수 있게 되었습니다.

| Before | After |
|---|---|
| Issue / PR을 하나씩 열어서 내용을 추적한다 | URL을 모아서 붙여넣고 전체를 파악한다 |
| ... | ... |

또 하나는 당초에는 상정하지 않았던 효과입니다. 캐치업을 위해 요약을 생성하는 흐름을 타는 김에 리포트가 한 장 남게 되므로, 그 개요를 그대로 타 부서 공유용으로도 사용할 수 있게 되었습니다. 이전에는 개요까지 손을 댈 여력이 없어 내놓지 못했기에, 이 부분은 부가가치라고 할 수 있습니다.

참고로, 사내 리포지토리의 차분을 AI에게 읽히기 때문에, 이용 환경의 데이터 취급 정책이나 기밀 정보 취급 방식은 사전에 확인해 둘 필요가 있습니다.

그 전제 조건만 지킨다면, 자신이 파악하기 위한 작업을 하는 것만으로도 타 부서에 공유할 수 있는 개요를 함께 얻을 수 있습니다. 마지막 확인은 인간의 업무로 남지만, 그 부하는 가벼워졌습니다.

## 사용해 보니 좋았던 점

### 「모아서」라고 말하는 것만으로 동작한다

"이번 주 릴리스 내용 모아서"라고 말하는 것만으로 발동합니다. `description`에 적어둔 트리거 문구가 작동하는 순간입니다.

이는 작아 보이지만 큰 변화였습니다. "이 작업에는 이 명령어를"이라고 외울 필요가 없기 때문에, 가끔 사용하더라도 방법을 다시 떠올리는 수고가 없습니다.

### 자신의 판단이 Skill에 깃든다

"기술 용어 금지", "추측하지 말 것", "사용자 경험 위주로 작성할 것"은 지금까지 제가 매번 머릿속에서 암묵적으로 해왔던 판단입니다. 그것을 파일로 써 내려가면 AI가 그 판단을 재현하기 쉬워집니다.

범용 AI에게 통째로 맡기는 것이 아니라, **자신의 판단을 학습시킨 전용 도구**를 키워나가는 감각에 가깝습니다.

### 확인하기 쉬운 입도로 나온다

출력 포맷을 고정함으로써 내용 체크도 쉬워졌습니다. 「개요 / 대응·변화 / 사용자 경험의 변화」로 나뉘어 있기 때문에, PR과 대조하여 수상한 부분만 수정하면 됩니다. AI의 출력을 그대로 믿는 것이 아니라, 스스로 확인하기 쉬운 형태로 정돈해 두는 것. 이 점도 실무에서 효과적이었습니다.

## 요약

본 기사에서는 Claude Code Skills와 GitHub CLI를 조합하여, 릴리스 공유회 자료 작성을 자동화한 시도를 소개했습니다.

- **파일 1장**으로 작업 절차를 정의할 수 있다
- **description**에 적은 문구가 자동 실행의 트리거가 된다
- **GitHub CLI**와 조합하면 GitHub의 정보를 동적으로 가져올 수 있다
- 구현 차분까지 읽게 하여 「사실 확인」에 사용하고, 「추측」에는 사용하지 않도록 선을 긋는 것이 효과적이다
- 프롬프트에 자신의 규칙을 적으면, **범용 AI가 자신만의 전용 도구로 동작한다**

직접 만들어 보며 느낀 점은, Skills는 단순한 프롬프트 저장소가 아니라는 것입니다. 매번 처음부터 AI에게 지시하는 것이 아니라, 자신의 절차나 판단을 파일로 써 내려가며 사용하면서 조금씩 고쳐 나가는 것. 그렇게 자신의 작업에 맞춘 전용 도구를 만들어 나가기에 적합한 구조라고 생각합니다.

이번에는 저 자신을 위해 만들었지만, Skill은 단순한 파일이기에 Git으로 공유하면 팀 전체로 확산할 수도 있습니다. 자신의 작업을 편하게 하려고 만든 것이 그대로 팀의 자산이 될 수도 있다는 뜻입니다.

팀의 정보 공유 비용으로 고민하고 계신 분들이나, Claude Code Skills를 시도해 보고 싶은 분들에게 참고가 되기를 바랍니다. "우리 팀에서는 이렇게 사용하고 있어요"와 같은 댓글도 기다리고 있겠습니다.

### Discussion

![](https://static.zenn.studio/images/drawing/discussion.png)