클로드 코드 스킬 만들기: 반복하는 절차를 명령 하나로

Claude Code(클로드 코드)에는 반복되는 절차를 명령 하나로 등록해 두는 스킬이 있습니다. CLAUDE.md가 매 세션 항상 따르는 규칙이라면, 스킬은 필요할 때 불러 쓰는 절차입니다.

같은 절차를 채팅창에 세 번째 붙여넣고 있다면 신호입니다.

지난 레슨에서 남이 만든 플러그인을 설치해 바로 써봤다면, 오늘은 남의 것이 아니라 내 절차를 직접 스킬로 만들 차례입니다. 스킬 작성법이 급해서 오셨다면 이 레슨만 보셔도 됩니다. SKILL.md 파일 형식 자체는 잘 안 바뀌는 편이지만, 관련 옵션이나 명령은 릴리스마다 조금씩 늘어날 수 있으니 오래된 시점에 읽으신다면 공식 문서를 함께 확인해 주세요.

스킬 (Skill)

스킬은 지침을 담은 SKILL.md 파일 하나로 Claude Code의 능력을 넓히는 장치다. 폴더 이름이 그대로 슬래시 명령이 되어 /스킬이름으로 직접 부를 수도 있고, 대화 맥락과 관련이 있으면 Claude(클로드)가 스스로 찾아 쓸 수도 있다. 같은 지침을 채팅창에 계속 붙여넣거나 CLAUDE.md의 한 항목이 점점 절차로 불어났다면 스킬로 옮길 때다.

스킬 구조: SKILL.md 파일 하나

스킬은 SKILL.md를 진입점으로 하는 폴더입니다. 가장 단순한 형태는 이렇습니다.

~/.claude/skills/summarize-changes/
└── SKILL.md

파일 맨 위에 YAML frontmatter가 있고, 그 아래에 Claude가 실행할 때 따르는 지침이 이어집니다. frontmatter 중 실제로 자주 쓰이는 것만 추려보면 이렇습니다.

지침 본문에는 $ARGUMENTS라는 자리표시자를 쓸 수 있습니다. 스킬 이름 뒤에 입력한 텍스트가 그대로 이 자리에 채워집니다. 인수가 여러 개 필요하면 $ARGUMENTS[0], $ARGUMENTS[1]처럼 순서대로 나눠 받을 수도 있습니다.

스킬을 어디에 두느냐에 따라 누가 쓸 수 있는지가 갈립니다. CLAUDE.md 위치 규칙과 결이 같습니다.

같은 이름의 스킬이 여러 위치에 있으면 개인 위치가 프로젝트 위치를 덮어씁니다. 플러그인 스킬은 플러그인이름:스킬이름처럼 이름 앞에 플러그인 이름이 붙어서 다른 위치와 겹칠 일이 없습니다.

지원 파일을 곁들일 수도 있다는 점이 커스텀 명령과 갈리는 지점입니다. 이 블로그가 쓰는 저장소의 post-writer 스킬이 실제 예입니다.

.claude/skills/post-writer/
├── SKILL.md         # 골격과 워크플로우
├── lexicon.md        # 문체 어휘 사전
└── style-guide.md    # 문체 규칙

SKILL.md는 뼈대만 담고, 세부 규칙은 옆 파일에 두어 필요할 때만 펼쳐 봅니다. 참고로 이 저장소의 스킬들은 scope와 execution이라는 항목도 frontmatter에 함께 적어두고 있는데, 이 둘은 공식 필드가 아니라 이 저장소가 "다른 에이전트에도 그대로 이식할 수 있는 절차인지"를 표시하려고 자체적으로 붙인 관행입니다. 공식 스펙에 없는 필드를 얹어도 스킬은 그대로 동작합니다. YAML이니까요.

내 절차를 스킬로

이 트랙이 이어온 관통 시나리오, 고객사 월간 콘텐츠 리포트로 실습해 보겠습니다. 지난 CLAUDE.md 레슨에서 리포트의 표 형식과 표기 규칙을 파일에 고정해 뒀습니다. 이번에는 그 규칙 위에서 실제로 초안을 뽑아내는 절차를 스킬 하나로 만듭니다.

리포트 작업을 하는 프로젝트에서 .claude/skills/monthly-report-draft/SKILL.md를 만듭니다. 팀원과 함께 쓰는 저장소라면 이 위치가 맞습니다. 버전 관리에 커밋되어 있는 그대로 협업자에게도 적용되기 때문입니다.

---
description: 고객사 월간 콘텐츠 리포트 초안을 만든다. 이번 달 게시물과 지난달 대비 증감을 정리해 달라고 할 때 쓴다.
argument-hint: "[YYYY년 M월]"
disable-model-invocation: true
---
 
# 월간 콘텐츠 리포트 초안
 
$ARGUMENTS 리포트 초안을 만든다. 형식과 표기 규칙은 이 프로젝트의 CLAUDE.md를 그대로 따른다.
 
1. 해당 월과 지난달의 게시물 목록, 채널별 지표를 확인한다
2. CLAUDE.md의 표 형식대로 표를 만든다 (첫 칸 게시일, 둘째 칸 채널명)
3. 지난달과 비교하는 문장에는 반드시 근거 수치를 괄호로 병기한다
4. 초안 끝에 다음 달 제안을 한 줄 덧붙인다

disable-model-invocation: true를 넣은 이유가 있습니다. 리포트 초안 작성은 사람이 시점을 정해서 시작하는 작업이지, Claude가 대화 맥락만 보고 알아서 실행할 작업이 아닙니다. 공식 문서도 배포나 커밋처럼 사람이 타이밍을 쥐어야 하는 작업에는 이 옵션을 권합니다.

이 스킬이 매번 같은 파일을 읽거나 같은 명령으로 데이터를 가져온다면 allowed-tools를 함께 적어두는 것도 방법입니다. 예를 들어 리포트 자료를 프로젝트 안의 특정 폴더에서만 읽는다면 allowed-tools: Read(./reports/*)처럼 지정해 그 안에서는 매번 승인을 묻지 않게 할 수 있습니다. 스킬이 켜져 있을 때만 적용되고, 나머지 도구는 평소 권한 설정을 그대로 따릅니다.

저장한 뒤 /monthly-report-draft 8월처럼 입력하면 $ARGUMENTS 자리에 "8월"이 채워진 채로 Claude에게 전달됩니다.

/mo까지만 쳐도 방금 만든 스킬이 frontmatter의 description 문장과 함께 목록에 올라옵니다.

메뉴에 안 뜬다면 십중팔구 frontmatter의 YAML 형식이 어긋난 경우입니다. ---로 감싼 부분의 들여쓰기나 콜론 뒤 띄어쓰기가 깨지면 Claude Code는 본문은 읽되 frontmatter는 빈 채로 처리하므로, /monthly-report-draft로 직접 부르는 건 되어도 스킬 메뉴에서 설명이 안 보이는 식으로 나타납니다. 이럴 때는 claude --debug로 다시 열어 파싱 오류 로그를 확인하시면 됩니다.

잘 도는 스킬과 안 도는 스킬

스킬로 만든다고 전부 안정적으로 도는 건 아닙니다. 이 블로그가 쓰는 저장소에는 성격이 다른 스킬이 여러 개 있는데, 나란히 놓고 보면 기준이 드러납니다.

thumbnail 스킬은 순서가 완전히 고정되어 있습니다. 픽셀 그리드를 그리고, 렌더링 명령을 실행하고, 결과 PNG 파일이 생겼는지 확인합니다. 매번 같은 순서로 돌고, 끝났는지 아닌지도 파일 존재 여부로 판정할 수 있습니다. 판단이 끼어들 자리가 거의 없어서 스킬로 만들기 딱 좋은 자리입니다.

factcheck 스킬은 다릅니다. "수정 0건 라운드가 나올 때까지 반복한다"는 조건으로 끝을 판정합니다. 이 판정 자체가 판단입니다. 무엇을 "수정"으로 칠지, 언제 라운드를 더 돌릴지는 매번 다시 봐야 합니다. 그런데도 이 스킬이 안정적으로 도는 이유는 판단이 필요한 지점을 애매하게 남겨두지 않고 "수정 0건 라운드"라는 멈추는 조건을 명시해뒀기 때문입니다. draft-weave 스킬도 비슷합니다. "AI는 이어붙이는 역할이지 고쳐 쓰는 역할이 아니다"처럼 하지 말아야 할 경계를 못박아둡니다.

여기서 얻는 기준은 이렇습니다. 순서가 고정된 기계적인 작업은 스킬로 만들면 그대로 잘 돕니다. 판단이 필요한 작업이라면 "언제 끝나는지"와 "무엇을 하면 안 되는지"를 문장으로 못박아야 매번 다르게 돌지 않습니다. 반대로 "알아서 잘 판단해서 처리해줘" 식으로만 적어두면, 판단 기준이 없는 스킬은 매번 다른 결과를 냅니다. post-writer 스킬은 이 둘을 겹쳐 씁니다. 자체 절차 안에서 factcheck 스킬을 다시 불러 쓰는 식으로, 스킬이 다른 스킬을 단계로 참조할 수도 있습니다.

길이도 참고할 만합니다. 공식 문서는 SKILL.md를 500줄 이하로 유지하라고 권합니다. 스킬 본문은 호출될 때마다 그대로 컨텍스트에 얹히는 비용이기 때문입니다. 실제로 이 저장소의 스킬들은 factcheck와 draft-weave가 71줄, thumbnail이 110줄, 가장 긴 post-writer도 202줄로 권장선 안에 있습니다. 자세한 규칙은 본문이 아니라 옆에 둔 지원 파일로 뺀 덕분입니다.

커스텀 명령과는 뭐가 다른가

자동완성에는 "클로드코드 커스텀 커맨드"도 상위 쿼리로 잡힙니다. 공식 문서가 둘을 한 페이지에서 다루는 이유가 있습니다. 사실상 같은 메커니즘이기 때문입니다.

이 저장소에는 실제로 두 방식이 함께 있습니다. .claude/commands/handoff.md는 폴더 없이 파일 하나로 만든 예전 방식의 명령입니다.

---
description: 워크트리 간 핸드오프 우편함 확인·처리
argument-hint: "[pull | new <받는쪽> <주제>]"
---
 
워크트리 간 핸드오프를 확인하고 처리한다. ...

이 파일은 /handoff라는 명령을 만들고, .claude/skills/post-writer/처럼 폴더로 만든 스킬이 /post-writer를 만드는 것과 똑같이 동작합니다. frontmatter도 description, argument-hint처럼 스킬과 같은 필드를 그대로 씁니다. 공식 문서는 이 둘이 완전히 같은 방식이라고 못박습니다.

둘의 차이는 딱 하나, 폴더냐 파일 하나냐입니다. 스킬은 폴더라서 SKILL.md 옆에 lexicon.md나 스크립트 같은 지원 파일을 같이 둘 수 있습니다. 명령은 파일 하나뿐이라 그럴 자리가 없습니다. 지원 파일이 필요 없는 짧은 절차라면 .claude/commands/의 파일 하나로도 충분하고, 실제로 기존 .claude/commands/ 파일은 계속 그대로 작동합니다. 다만 공식 문서는 새로 만들 때는 스킬 폴더 형식을 권합니다. 나중에 참고 자료나 스크립트가 필요해져도 폴더 구조를 새로 짤 필요가 없기 때문입니다.

제가 처음 스킬로 묶은 것은 GA4 데이터 분석이었습니다. 매번 대화로 같은 순서를 불러주다가 "이건 묶어야겠다" 싶었던 순간이 왔습니다. 그 뒤로는 광고 현황 점검, 분석 결과를 자연어 리포트로 받기처럼 매번 대화로 시작해야 했던 일들을 순서대로 알아서 돌게 하는 루트로 짰고, 콘텐츠 마케팅 쪽에서도 주제 찾기부터 글 구조 잡기, 초안 쓰기까지를 한 묶음으로 만들어 썼습니다. 공통점은 하나였습니다. 순서가 정해져 있는데 그 순서를 매번 제 입으로 다시 말하고 있었다는 것.