Claude Code 스킬 설계법: 반복 작업을 검증 가능한 절차로

Claude Code에 같은 작업 순서와 검토 기준을 매번 설명하고 있다면 스킬을 고려할 수 있습니다. 스킬은 반복할 작업의 목적, 절차, 필요한 자료를 정리해 에이전트가 작업할 때 참고하도록 만든 안내서입니다. 좋은 스킬의 핵심은 AI에게 ‘최고의 전문가가 되라’고 말하는 데 있지 않습니다. 언제 어떤 자료를 읽고 무엇으로 결과를 확인할지 구체적으로 적는 데 있습니다.

이 글은 Claude Code의 공식 스킬 문서를 기준으로 반복 작업용 스킬을 설계할 때의 판단 기준을 정리합니다. 스킬 파일을 만든 것만으로 모든 규칙이 자동 강제되거나 결과가 보장되는 것은 아닙니다.

CLAUDE.md와 스킬은 어떻게 다를까요?

CLAUDE.md에는 프로젝트에서 지속적으로 필요한 공통 지침을 두기 좋습니다. 예를 들어 테스트 명령이나 중요한 파일 변경 원칙입니다. 스킬에는 특정 작업이 필요할 때 참고할 절차를 정리할 수 있습니다. 예를 들어 블로그 글의 출처를 확인하고 초안을 검수하는 순서나, 배포 전 점검 절차입니다.

이는 정보를 정리하는 실용적인 기준입니다. 실제 적용 시점과 우선순위는 도구의 현재 설정과 공식 문서를 확인하세요.

1. 반복되는 실패나 작업부터 고릅니다

스킬이 필요한 이유가 모호하면 내용이 길어지고 유지보수가 어려워집니다. 먼저 실제로 반복되는 작업 하나를 고르고, 현재 어떤 결과가 빠지는지 적어 보세요.

예를 들어 블로그 원고에서 링크 확인이 자주 빠진다면 ‘웹 전문가처럼 행동하라’보다 다음과 같은 기준이 구체적입니다.

• 자료의 원문과 작성일을 확인한다.
• 수치가 조사 대상과 조건을 함께 설명하는지 확인한다.
• 확인하지 못한 내용은 사실로 단정하지 않는다.
• 최종 원고에서 사용한 출처를 찾을 수 있게 남긴다.

이 기준도 실제로 링크를 열고 내용을 확인하는 작업이 뒤따라야 의미가 있습니다.

2. 언제 사용할지 설명합니다

Claude Code 스킬은 SKILL.md의 앞부분에 이름과 설명을 둘 수 있습니다. 공식 문서는 description에 스킬이 무엇을 하고 언제 쓰이는지 적도록 권장합니다. 설명이 지나치게 넓으면 원하지 않는 상황에서도 선택될 수 있고, 너무 좁으면 필요한 요청에서 발견되지 않을 수 있습니다.

아래는 구조를 보여 주는 예시입니다. 경로와 절차는 자신의 환경에 맞게 조정해야 합니다.

---
name: source-review
description: 제공된 자료를 바탕으로 블로그 초안의 출처와 주요 주장을 검토할 때 사용한다.
---

# 출처 검토
1. 주장과 원문 링크를 나란히 정리한다.
2. 원문에서 수치의 대상과 시점을 확인한다.
3. 확인된 내용과 확인하지 못한 내용을 구분한다.
4. 결과에 출처와 남은 확인 사항을 기록한다.

3. 핵심 절차와 참고 자료를 나눕니다

공식 문서는 스킬 디렉터리에 참고 문서나 예시, 스크립트를 별도 파일로 둘 수 있다고 설명합니다. 자주 필요한 순서는 SKILL.md에 두고, 긴 기준표나 예시는 필요할 때 찾아 읽도록 연결하면 관리하기 쉽습니다. 파일을 나눴다는 사실만으로 토큰 비용이 일정 비율 줄거나 성능이 개선된다는 뜻은 아닙니다. 어떤 자료가 실제로 로드됐는지와 작업 결과를 확인해야 합니다.

4. 검증은 작업에 맞게 설계합니다

스킬에 “검증하라”고 적는 것과 실제 검증을 수행하는 것은 다릅니다. 코드라면 관련 테스트와 실행 환경을 확인하고, 글이라면 원문 링크와 주장의 일치 여부를 확인해야 합니다. 검증하지 못한 항목은 이유와 함께 보고하도록 적어 두면 다음 사람이 이어받기 쉽습니다.

기계적으로 단어만 찾는 검사는 보조 수단입니다. 예를 들어 CSS에 @media가 없다는 이유만으로 모바일 대응이 없다고 단정하거나, 특정 HTML 문자열 하나로 접근성을 판정할 수는 없습니다. 실제 화면과 사용 흐름을 함께 살펴야 합니다.

5. 실제 요청으로 시험하고 고칩니다

스킬을 완성했다고 생각되면 다음을 확인해 보세요.

1. 적용해야 하는 요청에서 선택되거나 명시적으로 호출할 수 있나요? 2. 관계없는 요청에서 불필요하게 적용되지 않나요? 3. 필요한 파일과 자료를 실제로 읽었나요? 4. 검증 결과와 미확인 사항을 구분해 보고하나요? 5. 지침이 모순되거나 오래돼 작업을 방해하지 않나요?

같은 업무를 스킬 적용 전후로 비교해 누락이 줄었는지 살펴보세요. 한 번 성공한 사례만으로 모든 작업의 품질이 좋아진다고 일반화할 수는 없습니다.

자주 묻는 질문

스킬을 쓰면 AI가 규칙을 무조건 지키나요?

아닙니다. 스킬은 작업을 안내하는 지침입니다. 반드시 필요한 통제는 도구 권한, 실제 테스트와 검토 등 적절한 방법을 함께 사용해야 합니다.

스킬은 길수록 좋은가요?

아닙니다. 반복 작업에 필요한 핵심과 구체적인 검증 기준을 우선하고, 긴 참고 자료는 필요에 맞게 정리하세요.

기존 CLAUDE.md를 모두 스킬로 옮겨야 하나요?

그럴 필요는 없습니다. 프로젝트 전반에서 필요한 지침과 특정 작업에만 필요한 절차를 나누는 편이 관리하기 쉽습니다.

참고 자료: Claude Code 스킬 공식 문서, Claude Code 프로젝트 지침, Claude Code 권장 사항. 확인일: 2026년 11월 6일.