Claude Code Skills로 코드리뷰 Skill 커스텀 해보기

들어가며

Claude Code의 Skills는 Claude가 특정 작업을 더 잘 수행하도록 지침, 스크립트, 리소스를 폴더 단위로 묶어두는 방식이다.
쉽게 말하면, 비슷한 역할을 수행하는 기능들을 하나의 묶음으로 구성해 재사용 가능하게 만든 구조라고 이해하면 된다

공식 문서에서는 Skills를 이렇게 설명한다.

Skills extend what Claude can do.
Create a SKILL.md file with instructions, and Claude adds it to its toolkit.

 

SKILL.md 파일 하나만 만들어줘서 Claude의 “능력” 자체를 확장할 수 있다는 의미다

https://code.claude.com/docs/en/slash-commands

Extend Claude with skills - Claude Code Docs

SKILL.md를 중심으로 동작하고, 필요하면 /skill-name 형태로 직접 호출할 수도 있다. Claude 내부 context에 로드시켜서 특정 명령어를 입력한다면, Claude가 작업 문맥에 맞춰 자동으로 불러오기도 한다. 만약에 반복해서 하는 작업들이 있다면 재사용이 가능하도록, 리소스를 줄일 수 있다

 

해당 기능을 사용해보면서, 개발자가 아니여도 PDF, PPT, Word, Excel 같은 것도 원하는대로 커스텀하여 제작 시간을 줄일 수도 있겠다라는 생각이 들기도 하였다

Anthropic에서 공식으로 Skills 마켓플레이스를 제공해주고 있으니까, 여러가지 내용들을 둘러보고 필요한 내용들은 활용해준다면 좋을거같다

https://github.com/anthropics/skills

GitHub - anthropics/skills: Public repository for Agent Skills

---

공식 문서 기준으로 Skill은 아래의 구조처럼 생성된다고 설명한다

1. Skills 구조 이해하기

위는 예시이고, 여기서 SKILL.md를 커스텀한다고 생각해주면 된다

name은 레거시 코드 내용 팔로업으로 네이밍하고, description에서는 간단하게 코드 팔로업용 Skill과 아래의 내용들을 작성해놓을 수도 있다
코드를 설명시, 아래 내용 포함 :

1. 비유

2. 다이어그램

3. API 요청 - 응답 플로우

---

2. Skill은 언제 실행될까?

Claude uses skills when relevant, or you can invoke one directly with /skill-name.

크게 보면 자동 실행 (문맥 기반)과 앞서 서론에서 짧게 설명한 수동 실행 (/skill-name) 방식을 의미한다

 

좀 더 자세히 설명해보면, 자동 실행은 Claude가 현재 요청의 의도를 해석한 뒤 가장 적절한 Skill을 스스로 선택해 적용하는 방식이다. 예시로 테스트 코드 작성이나 깃허브 PR, 이슈 등등의 문서처럼 반복적인 컨벤션이 있는 작업에서는 사용자가 명시하지 않아도 별도의 호출 없이 관련 Skill이 자연스럽게 적용될 수도 있다 

해당 이유에서 수동 실행의 세부적인 커스텀이 중요하다. 결론부터 먼저 얘기하자면 수동 실행을 잘쓰기 위해선 description을 잘 써야 한다. 이유는 description이 모호하면 의도하지 않은대로 자동 실행이 작동할 수도 있고, 만약에 Skill을 사용하여 수동으로 호출하더라도 의도한 방식으로 동작하지 않을 가능성이 높기때문이다

추가적으로 /skill-name 을 설정해두면 편리한 이유는 로고, 폰트, 색상 같은 브랜딩 규칙이나 특정 팀의 문서 양식, 리뷰 기준, 출력 형식을 클로드에게 반복해서 설명하지 않아도 된다는 점이다. 한번 Skill로 정의해두면 Claude가 해당 컨텍스트를 일관되게 재사용하기 때문에, 기준이 흔들리지 않고 원하는 품질에 가깝게 결과를 유지할 수 있다

---

본론

이제 본격적으로 코드리뷰 관련 Skills를 만드는 예시를 설명해보려한다

---

1. 초기 세팅

skill-creator는 document-skills가 아니다. 이게 무슨 말이냐면, document-skills는 이름 그대로 문서 생성 계열 Skill 묶음일 뿐이고 코드리뷰 Skill을 만들고 싶다면 document-skills만 설치해서는 부족하다는 뜻이다. 따라서 추가적인 설치가 필요하다는 뜻이다

/plugin marketplace add anthropics/skills

/plugin install document-skills@anthropic-agent-skills

/plugin install example-skills@anthropic-agent-skills

/reload-plugins

 

만약에 문서 생성만 하고싶다면 두번째 줄 플러그인만 설치해도 충분하지만, 코드 리뷰용 Skill을 만들기 위해서는 해당 플러그인들이 모두 필요하다고 이해해주면 된다

---

2. 코드 리뷰 가이드 생성

개인적으로 먼저 Claude에게 가이드를 주고 시작하는 것이 좀 더 완성도가 높았던거같다. 예를 들면 아래처럼 시작할 수 있다

코드리뷰 관련 skills를 작성하고 싶은데, 먼저 코드리뷰 best practice를 찾아서 학습해봐. 특히 아키텍처 경계, 예외 처리, 테스트 가능성, 성능, 보안, 가독성 관점으로 정리해줘.

---

3. skill-creator로 코드리뷰 Skill 만들기

기준 정리가 끝나면 이제 실제 Skill 생성을 시킬 수 있는데, 아래는 예시니까 참고만 해주면 좋을거같다

이제 skill-creator skills를 써서

방금 학습한 코드리뷰 철학으로 코드리뷰 Skills를 만들어줘.

Compaction이 일어나도 중요한 상태를 유지할 수 있게

reference 파일, 체크리스트, 중간 산출물 구조도 함께 고려해줘.

 

이렇게 하면 서론에 설명한거처럼 Skills.md가 생성되는데, 레퍼런스 파일들도 함께 생성됩니다

여기서 SKILL.md의 frontmatter는 최대한 자세하게 적어주는게 좋다

---

4. Compaction까지 고려해서 설계

여기서 중요한 점이 하나 있는데, Skill 자체가 대화 상태를 영구 저장해주는 것은 아니다. Claude Code는 컨텍스트가 차면 자동으로 또는 /compact 명령으로 대화를 요약해 공간을 확보할 수 있는데, 이 과정에서 세부 맥락이 일부 사라질 수도 있다. 공식 문서도 compaction 이후 중요한 문맥이 손실될 수 있다고 설명하면서, SessionStart hook의 compact matcher를 이용해 핵심 컨텍스트를 다시 주입하는 예시를 제공해주기도 한다

따라서 아래의 내용처럼 설계해주면, 커스텀한 내용들이 휘발되지 않도록 복구하는 플로우를 생성해줄 수도 있다

 

첫째, SKILL.md에는 핵심 workflow만 두고 상세 기준은 references/로 분리

둘째, 리뷰 중간 결론이나 체크포인트는 .claude/state/code-review-summary.md 같은 파일에 따로 남긴다

셋째, compaction 이후 이 파일을 다시 읽게 만드는 hook을 둔다

---

마치며

개인적으로 해당 방식의 장점은 명확하다고 생각한다 

1. 한 번 잘 만들어둔 작업 방식을 계속 재사용할 수 있다

2. document-skills와 결합하면, 코드리뷰 이후 결과를 Word나 PPT 요약본 등으로 시각화 할 수도 있다

3. Anthropic에서 제공해주는 공식 플러그인이라 그런지 퀄리티는 보장해주는거같다