요즘 AI 코딩 어시스턴트 없이는 개발을 못 할 것 같은 세상이 됐다.
그중에서도 VSCode 에서 많이들 사용하는게 GitHub Copilot 인데, Copilot 에는 커스텀 Instructions 와 .github/copilot-instructions.md 를 통해 나만의 워크플로우를 만들 수 있다.
근데 Copilot 만 쓰는건 아니잖아.
Claude 도 VSCode Extension 으로 쓸 수 있고, 최근에는 claude.md 나 커스텀 커맨드를 통해 스킬처럼 만들어서 쓸 수 있다.
오늘 소개할건, 내가 실제로 쓰고 있는 코드 리뷰 자동화 스킬이다.
PR 올리기 전에 Copilot 나 Claude 에이전트한테 먼저 리뷰 받는 방식인데, 꽤 쓸만하다.
사실 굳이 스킬까지 사용하지 않더라도 AI 에이전트에게 현재 수정사항과 orign/master 브랜치의 변경사항을 비교해서 개선할 부분과 문제가 될 만한 부분 찾아줘 라고만 입력해도 코드리뷰를 훌륭하게 해준다.
하지만 문제는 프롬프트를 입력하는게 번거로울뿐만 아니라 그때그때 다른 프롬프트를 입력하게 되면 코드리뷰의 품질이 일정하지 않다는 거다.
그래서 스킬을 만들어서 간단한 명령으로 코드리뷰를 진행하게 되면 사용도 간편해지고, 협업을 진행하는 팀 내에서 같이 사용이 가능하며 일관된 품질의 리뷰 결과도 얻을수 있으니 이것이 바로 일석삼조의 결과가 아닐까...
스킬(Skill) 이란
본론 들어가기 전에 스킬이 뭔지부터 짚고 넘어가자.
스킬은 claude 에서 먼저 생성된 개념으로 간단히 말해 AI 에이전트에게 알려주는 지침서 같은 역할을 한다.
Copilot 에서는 2025년 12월에 정식으로 추가된 기능인데, 특정 작업에 대해서 어떤식으로 하면 된다 라는걸 md 파일로 만들어 두면 AI 에이전트가 특정 명령어나 프롬프트 실행시 해당 스킬을 읽어와 지침(규칙)대로 작업을 수행한다.
스킬 파일 안에는 에이전트가 수행해야 할 절차를 마크다운으로 적어두면 된다.
어떤 git 명령어를 실행할지, 어떤 관점에서 분석할지, 결과를 어떤 포맷으로 출력할지 등을 전부 정의해두는 거다.
Copilot 의 .github/copilot-instructions.md 가 "항상 적용되는 전체 코딩 가이드라인" 이라면, 스킬은 필요할 때만 꺼내 쓰는 목적별 레시피 라고 보면 된다.
.github/
├── copilot-instructions.md ← 항상 적용되는 전체 가이드라인
└── skills/
├── code-review/
│ └── SKILL.md ← 코드 리뷰 스킬
├── test-gen/
│ └── SKILL.md ← 테스트 코드 생성 스킬
└── commit-msg/
└── SKILL.md ← 커밋 메시지 작성 스킬각 스킬은 독립적으로 호출되고, 인자도 넘길 수 있다.
한번 만들어두면 팀원들과 공유도 되고, git 으로 버전 관리도 된다.
Claude Code 에서도 동일하게 사용 가능
여기서 재밌는 점이 있다.
Agent Skills 는 오픈 스탠다드라서 Copilot 만의 전용 기능이 아니다.
.claude/skills 폴더에 동일한 스킬 파일을 두면 Claude Code 에서도 그대로 쓸 수 있다.
그리고 더 편한 건, .claude/skills 위치에 스킬을 두면 Copilot 이 자동으로 인식한다.
즉 파일 하나로 두 AI 에서 동시에 쓸 수 있는 거다.
| 위치 | Copilot | Claude Code |
|---|---|---|
.github/skills/<name>/SKILL.md | 가능 | 불가 |
.claude/skills/<name>/SKILL.md | 가능 (자동 인식) | 가능 |
팀에서 Copilot 쓰는 사람, Claude 쓰는 사람이 섞여 있어도
.claude/skills 하나로 다 커버가 된다.
스킬 파일 구조
스킬 파일은 마크다운 frontmatter 로 메타정보를 설정하고, 본문에 절차를 기술하는 방식이다.
---
name: code-review
description: "브랜치 간 코드 변경사항을 비교하고 코드리뷰를 수행한다."
---frontmatter 의 description 이 중요한데, Copilot 이 이 설명을 읽고 어떤 요청에 이 스킬을 써야 할지 판단한다.
"코드리뷰 해줘", "PR 리뷰해줘", "diff 분석해줘" 같은 요청이 들어오면 자동으로 이 스킬을 로딩하는 방식이다.
슬래시 커맨드(/code-review)로 직접 호출도 가능하다.
코드 리뷰 스킬 동작 방식
기본 개념은 간단하다.
- 현재 작업 브랜치와 비교 대상 브랜치(보통
origin/master나origin/dev) 를 git diff 로 비교 - 커밋된 변경사항뿐 아니라 Staged, Unstaged 변경사항까지 모두 긁어서
- 코드 품질 / 보안 / 성능 / 유지보수성 관점으로 리뷰
프로젝트에 등록하기
프로젝트 루트에 스킬 폴더를 만들고 SKILL.md 파일을 넣으면 된다.
project-root/
├── .claude/
│ └── skills/
│ └── code-review/
│ └── SKILL.md ← 스킬 파일
├── src/
└── ....claude/skills 위치를 쓰면 Copilot 과 Claude Code 둘 다 인식한다.
Copilot 만 쓴다면 .github/skills 를 써도 된다.
.github/
└── skills/
└── code-review/
└── SKILL.md ← 코드 리뷰 스킬등록 후 Copilot 채팅창에서는 이렇게 쓰면 된다.
/code-review
/code-review origin/dev
/code-review origin/staging또는 그냥 자연어로 "코드 리뷰해줘", "PR 올리기 전에 한번 봐줘" 라고 해도
description 을 보고 자동으로 이 스킬을 로딩해서 실행한다.
주의사항
pnpm-lock.yaml,package-lock.json같은 자동 생성 파일은 리뷰 제외- 변경 파일이 20개 이상이면 핵심 파일 중심으로 요약 리뷰
- diff 에 API 키나 비밀번호가 포함되면 Critical 로 즉시 보고
- Unstaged 변경사항이 있으면 커밋 또는 스테이징 여부를 안내
전체 스킬 파일
실제로 사용 중인 SKILL.md 전체는 아래와 같다.
---
name: code-review
description: "브랜치 간 코드 변경사항을 비교하고 코드리뷰를 수행한다. 코드리뷰, code review, diff 비교, 브랜치 비교, PR 리뷰, 변경사항 검토 요청 시 반드시 사용한다."
argument-hint: "비교 대상 브랜치명 (기본값: origin/master). 예) origin/dev, origin/staging"
---
# 브랜치 코드 리뷰 스킬
커밋된 변경사항 + Staged + Unstaged 변경사항을 모두 포함해 종합적으로 리뷰한다.
## Procedure
### 1. 브랜치 확인 및 BASE_BRANCH 결정
git branch --show-current && git branch -a
git fetch origin
**BASE_BRANCH 우선순위**: ① 인자로 전달된 브랜치 → ② 메시지에 언급된 브랜치 → ③ 기본값 `origin/master`
- `origin/` 없으면 자동으로 `origin/<브랜치명>`으로 변환
- 원격 브랜치 미존재 시 로컬 브랜치 사용 후 사용자에게 안내
### 2. 변경사항 수집
# 워킹 트리 상태
git status --short
# 파일 목록
git diff --name-status BASE_BRANCH...HEAD
git diff --name-status --cached
git diff --name-status
# 상세 diff
git diff -U5 --ignore-blank-lines BASE_BRANCH...HEAD # 커밋된 변경
git diff -U5 --ignore-blank-lines --cached # Staged
git diff -U5 --ignore-blank-lines # Unstaged
# 커밋 히스토리
git log --oneline BASE_BRANCH..HEAD
> diff 500줄 초과 시 파일 단위로 분할 분석. `pnpm-lock.yaml`, `package-lock.json` 등 자동 생성 파일은 제외.
### 3. 리뷰 수행
| 관점 | 체크 항목 |
|------|-----------|
| 코드 품질 | 가독성, 중복, 명명 규칙, 불필요한 로그 |
| 보안 | 인젝션, 민감 정보 노출, 인증/인가, SSRF |
| 성능 | N+1 쿼리, 불필요한 연산, 비동기 처리 |
| 유지보수성 | 단일 책임 원칙, 의존성 방향, 테스트 가능성 |
| 타입 안전성 | TypeScript `any` 남용, 타입 단언 오용 |
| 에러 처리 | 예외 처리 누락, 에러 메시지 노출 |
### 4. 결과 출력 (한국어)
## 코드 리뷰 결과
**브랜치**: `<현재>` ← `<BASE_BRANCH>`
**변경 파일**: N개 | **추가**: +N줄 | **삭제**: -N줄
📌 리뷰 범위: [커밋됨 / Staged / Unstaged] (해당 범위만 표시)
---
### 커밋 요약
- <해시> <메시지>
### 워킹 트리 현황
- Staged / Unstaged / Untracked (해당 항목만 표시)
### 변경사항 요약
<파일별 1~2줄 요약>
---
### 리뷰 소견
#### 🔴 Critical (즉시 수정)
#### 🟡 Warning (개선 권장)
#### 🟢 Suggestion (선택적 개선)
---
### 종합 의견
**심각도 기준**
- 🔴 보안 취약점, 런타임 오류, 데이터 손실 위험
- 🟡 성능 저하, 유지보수성 문제, 베스트 프랙티스 위반
- 🟢 코드 스타일, 가독성, 선택적 리팩토링
## 주의사항
- diff 없으면 사용자에게 안내
- 민감 정보(API 키 등) 발견 시 🔴 Critical로 즉시 보고
- 파일 20개 이상이면 핵심 파일 중심 요약 리뷰
- Unstaged 변경사항 있으면 커밋/스테이징 여부 안내PR 올리기 전에 한번 돌려보면 생각보다 잡히는 것들이 꽤 있다.
특히 팀 컨벤션 어긴 부분이나 빠뜨린 에러 처리 같은 거.
사람한테 리뷰 받기 전에 1차 필터 역할로 쓰기 딱 좋다.
끗.
