최근 Claude Code를 본격적으로 쓰기 시작하면서, 매번 같은 프롬프트를 반복적으로 입력하게 되는 게 번거로웠습니다. Jira 티켓을 분석해달라거나, 코드 리뷰를 요청하거나, 커밋 & 푸시까지 처리해달라는 식의 작업은 결국 비슷한 흐름이 반복되는데요.
처음에는 단순히 제 개인 작업을 편하게 하려고 시작했는데, 정리해보니 먼저 적용해보고 괜찮으면 팀 내 공통 컨벤션으로 확장할 수 있겠다는 생각도 들어서 본격적으로 정리해보게 되었습니다. 이번 글에서는 그 과정에서 만들게 된 Skill들에 대해 정리해보려고 합니다.
Skill이란?
Claude Code에서 Skill은 재사용 가능한 프롬프트/워크플로우 단위라고 이해하시면 됩니다. 자주 쓰는 작업 흐름을 미리 정의해두고, 필요할 때 슬래시 커맨드로 호출해서 쓰는 방식입니다.
구조는 단순합니다.
- 위치:
~/.claude/skills/<skill-name>/SKILL.md - 형식: frontmatter (메타데이터) + 본문 (실제 지시사항)
- 호출: 채팅에서
/<skill-name>입력
SKILL.md의 frontmatter에는 name, description, category 같은 메타 정보가 들어가고, 본문에는 해당 Skill이 수행해야 할 역할·실행 순서·산출물 형식을 자유롭게 기술합니다. Claude Code가 사용자의 입력을 보고 적절한 Skill을 자동으로 매칭해주거나, 사용자가 명시적으로 /skill-name을 호출하면 본문 내용을 컨텍스트에 끌어와 작업을 수행합니다.
Skill을 도입하게 된 배경
크게 두 가지 이유가 있었습니다.
첫 번째는 반복되는 프롬프트 문제였습니다. Jira 티켓을 받으면 → 요구사항을 정리하고 → 구현 계획을 세우고 → 코드를 작성하고 → 리뷰를 받는 흐름이 거의 매번 반복됩니다. 매번 손으로 "이 티켓 분석해줘", "이 계획대로 구현해줘", "리뷰해줘" 같은 프롬프트를 입력하다 보니, 같은 말을 반복하는 시간이 아깝게 느껴졌습니다.
두 번째는 팀 컨벤션 공유로의 확장 가능성이었습니다. 어차피 정리할 거라면 저 혼자만 쓰는 매크로로 끝내지 말고, 팀 내 다른 분들도 같은 흐름으로 작업할 수 있도록 표준화된 자산으로 키울 수 있겠다는 생각이 들었습니다. 그래서 처음부터 개인용 → 팀용으로 확장 가능한 형태로 설계했습니다.
이 의도를 네이밍에도 반영했는데요. pol-team-* 라는 prefix를 붙여서, 개인 prefix(pol) 와 팀 단위(team) 임을 동시에 드러내고, 추후 다른 팀이나 다른 사람의 Skill과 이름이 충돌하지 않도록 했습니다.
pol-team-* Skill 구성
팀 단위 작업 흐름 전체를 분해해서 Skill로 만들었습니다. 하나의 큰 작업을 단계별로 쪼개고, 각 단계를 독립된 Skill이 담당하게 한 뒤, 마지막에 오케스트레이터가 전체 흐름을 묶는 구조입니다.
전체 파이프라인
[Jira 티켓]
↓
요구사항 분석 ∥ Repo 도메인 매핑 ← 병렬
↓
구현 계획 수립
↓
코드 작성 ↔ 코드 리뷰 ← 피드백 루프
↓
[완료]각 단계마다 산출물을 .claude-artifacts/*.md 파일로 남겨서, 다음 Skill이 이 문서를 읽어 컨텍스트를 이어받도록 설계했습니다. Skill 간의 인터페이스를 파일 단위로 명확하게 만들어두면, 중간에 사람이 산출물을 직접 수정하거나 검토하기에도 편하다는 장점이 있습니다.
pol:team-requirements-organize — 요구사항 정리
Jira 티켓을 받아 요구사항을 분석·정리하는 Skill입니다.
티켓을 그대로 다음 단계에 던지면 내용이 모호하거나, 명시되지 않은 암묵적 요구사항을 놓치기 쉽습니다. 그래서 분석 단계를 명시적으로 떼어내 아래 4가지 관점으로 분해하도록 했습니다.
- 필요한 기능 (Features) — 사용자가 명시적으로 요구한 기능 단위
- 수정되어야 할 영역 (Impacted Areas) — 변경이 예상되는 파일/모듈/레이어
- 주의사항 (Cautions) — 기존 동작에 미칠 영향, 사이드이펙트, 엣지케이스
- 놓치기 쉬운 부분 (Hidden Requirements) — 티켓에 명시되지 않았지만 구현상 필수적인 암묵적 전제
이 Skill은 구현하지 않습니다. 오직 분석과 정리만 담당하고, 결과물은 후속 Skill이 소비할 수 있도록 시멘틱 태그가 포함된 Markdown 문서로 출력합니다.
산출물:
.claude-artifacts/requirements-<TICKET-ID>.md
pol:team-repo-domain-expression — Repo 도메인 정리
현재 Repo의 도메인 구조를 정리·유지하는 Skill입니다.
매 작업마다 Claude가 전체 Repo를 다시 탐색하면 토큰과 시간이 낭비되는데요. 그래서 한 번 정리해둔 도메인 구조 문서를 재사용하고, develop 브랜치의 신규 커밋 기준으로 증분 업데이트만 수행하도록 했습니다.
동작 흐름은 이렇습니다.
- 기존 도메인 정리 문서가 있으면 먼저 읽고, 마지막 동기화 커밋 SHA를 확인
- 그 SHA 이후의
develop커밋들 중 도메인 구조에 영향을 주는 변경(엔티티/모듈 경계/public API 등)만 식별 - 영향이 있으면 문서를 갱신, 없으면 그대로 유지
산출물에는 도메인 정리 본문 외에 .state.json을 함께 두어, 다음 실행 시 어디서부터 비교해야 하는지를 추적합니다.
산출물:
.claude-artifacts/repo-domain-expression.md+.state.json
pol:team-plan — 구현 계획 수립
위에서 만든 두 산출물(요구사항 정리서 + 도메인 구조 문서)을 병합하여, 실제 구현 계획서를 만드는 Skill입니다.
이 Skill의 결과물은 다음 단계의 코드 작성 Skill이 오직 이 문서만 보고 바로 구현할 수 있을 정도로 구체적이어야 한다는 원칙을 두었습니다. 구체적으로는 아래와 같은 항목을 결정합니다.
- 변경 영역별로 신규 생성 / 기존 확장 / 리팩토링 중 어느 접근을 택할지
- 새로 작성한 함수·메서드별 테스트 전략
- 변경으로 인해 간접 영향을 받을 다른 도메인·모듈 식별
- 모호한 결정은
<decision-points>섹션으로 빼서 사용자 확인을 거치도록 함
<decision-points>를 둔 이유는, 계획 단계에서 모호함을 그냥 흘려보내면 코드 작성 단계에서 더 큰 비용으로 돌아오기 때문입니다. Trade-off가 있거나 정책이 충돌하는 부분은 계획 단계에서 명시적으로 사람과 합의하는 편이 훨씬 낫습니다.
산출물:
.claude-artifacts/plan-<TICKET-ID>.md(이후 단계의 SSOT)
pol:team-code-work — 계획 기반 코드 작성
pol:team-plan이 산출한 계획서를 입력으로 받아 실제 코드 변경을 수행하는 Skill입니다.
이 Skill에서 가장 중요한 원칙은 Plan은 불가침(Single Source of Truth) 이라는 것이었습니다. 구체적으로는 이런 규칙을 두었습니다.
- 계획서는 절대 수정하지 않음
- 계획에 없는 파일 수정, 리팩토링, "겸사겸사 정리" 금지
- 계획과 실제 코드가 충돌하면 → 즉시 작업 중단 후 보고
이렇게까지 빡빡하게 둔 이유는, LLM이 코드를 작성하다 보면 자연스럽게 "이 부분도 같이 정리하면 좋을 것 같은데?" 라며 스코프를 넓히는 경우가 많기 때문입니다. 한두 번은 괜찮은 판단처럼 보이지만, 누적되면 PR 리뷰가 어려워지고 의도와 다른 변경이 섞여 들어갑니다. 그래서 재설계자가 아니라 실행자 역할만 하도록 명시했습니다.
산출물:
.claude-artifacts/code-work-<TICKET-ID>.md
pol:team-request-code-review — 코드 리뷰 리포트
현재 브랜치의 변경분을 리뷰해 심각도별로 분류된 리뷰 리포트를 생성하는 Skill입니다.
여기서도 한 가지 강한 제약을 두었는데, 코드를 절대 수정하지 않는다는 것입니다. 오직 진단만 담당하고, 결과는 Markdown 리포트로 남깁니다. 코드 수정과 리뷰를 같은 Skill이 동시에 하면 두 역할이 섞여서 리뷰의 객관성이 떨어지기 때문입니다.
리뷰 리포트는 후속 작업(pol:take-review-and-push 등)이 이 문서를 보고 실제 반영 작업을 수행할 수 있도록 구조화되어 있고, 오케스트레이터가 사용할 때는 라운드 번호를 붙여 피드백 루프를 추적합니다.
산출물:
.claude-artifacts/review-<TICKET-ID>-round<N>-*.md
pol:team-orchestrate — 전체 흐름 지휘
위 5개 Skill을 순서대로 자동 실행하는 오케스트레이터입니다.
티켓 ID 하나만 주면 다음 흐름으로 자동 진행합니다.
[요구사항 분석 ∥ 도메인 매핑] → 계획 → 구현 ↔ 리뷰 피드백 루프 → 완료옵션도 몇 가지 두었습니다.
--max-review-rounds=N(기본 3): 리뷰 ↔ 구현 피드백 루프 최대 반복 횟수--interactive: 계획 생성 후 사용자 승인 대기--skip-domain-sync: 도메인 매핑 단계 건너뛰기 (기존 문서 그대로 사용)
사람이 매번 5번 Skill을 호출하지 않아도 되도록 만든 진입점이지만, 단순히 "묶어준다"에 그치지 않습니다. 오케스트레이터는 직접 코드를 작성하거나 분석하지 않고, 각 단계의 결과를 해석해서 다음 단계로 넘기는 지휘자 역할만 합니다.
왜 이렇게 쪼갰는가
여러 Skill로 잘게 쪼개고 산출물 파일까지 두는 게 처음에는 과해 보일 수 있는데요. 직접 운영해보면서 느낀 장점은 크게 세 가지입니다.
- 각 Skill은 자기 일만 한다 — 분석은 구현하지 않고, 구현은 재설계하지 않고, 리뷰는 코드를 고치지 않습니다. 역할이 좁을수록 결과물의 품질이 일관되게 유지됩니다.
- 산출물(
.claude-artifacts/*.md)로만 소통한다 — Skill 간 컨텍스트가 디스크에 명시적으로 남아 있어, 어느 단계에서 무엇이 결정됐는지 추적할 수 있습니다. - 사람이 중간에 개입할 수 있다 —
--interactive옵션이나 산출물 파일을 직접 수정하는 방식으로, 자동화 흐름 중간에 자연스럽게 끼어들 수 있습니다.
후기
Skill을 도입하기 전에는 같은 프롬프트를 매번 손으로 쓰면서 "이거 매크로로라도 만들어두고 싶다"는 생각을 자주 했었는데요. Skill로 정리하고 나니 작업 흐름이 훨씬 매끄러워지고, 무엇보다 각 단계의 책임이 명확해진 게 가장 큰 변화였습니다. "지금 무슨 단계를 하고 있는지", "다음 단계의 입력으로 뭐가 필요한지"가 산출물 파일로 눈에 보이니까 작업 자체가 더 단단해졌습니다.
팀 컨벤션으로 확장할 때는 네이밍 규칙(<개인-prefix>-team-*)과 산출물 디렉토리(.claude-artifacts/) 위치를 팀 차원에서 합의해두는 게 좋을 것 같다는 생각도 들었습니다. 개인이 만든 Skill을 그대로 팀에 던지기보다는, 팀의 작업 흐름과 한 번 더 맞춰보는 단계가 필요해 보입니다.
이렇게 Skill로 작업 단계를 쪼개놓고 운영해보다 보니, 각 Skill이 더 독립적인 컨텍스트와 역할을 가질 수 있다면 퍼포먼스가 한층 더 올라갈 수 있겠다는 생각이 들었습니다. 그래서 다음 글에서는 Skill을 한 단계 더 보완해주는 Subagent 도입 과정을 정리해보고자 합니다.
긴 글 읽어주셔서 감사합니다.
