클로드 코드 스킬 작성법: 좋은 AI 매뉴얼은 어떻게 설계할까?

이 글은 4부작 중 2편입니다. 1편에서 스킬의 개념을 봤다면, 이번 편에서는 좋은 스킬을 설계하는 법을 봅니다.

AI에게 반복 업무를 맡길 때 중요한 건 “스킬을 만든다” 자체가 아닙니다.

더 중요한 건 이런 질문입니다.

• 이 스킬은 언제 불려야 할까?
• 이름만 보고 역할이 보일까?
• AI가 자주 틀리는 부분을 알려주고 있을까?
• 모든 내용을 한 파일에 욱여넣고 있지는 않을까?

이번 편은 이 질문에 답하는 글입니다.

이 글에서 가져갈 것

좋은 스킬은 작고 분명해야 합니다

Claude Code 팀은 내부 스킬을 살펴보면서 여러 유형으로 나눴습니다. API 사용법, 제품 검증, 데이터 분석, 업무 자동화, 코드 리뷰, 배포, 운영 매뉴얼 같은 것들입니다.

원문에 나오는 예시는 개발팀 업무에 가깝습니다.

billing-lib
signup-flow-driver
funnel-query
standup-post
babysit-pr
oncall-runner

이 이름들을 전부 외울 필요는 없습니다. 중요한 건 하나입니다.

너무 큰 스킬은 오히려 불편합니다.

예를 들어 marketing-skill이라는 이름의 스킬이 있다고 해봅시다. 이름만 봐서는 뭘 하는지 모릅니다. 블로그를 쓰는 건지, 카드뉴스를 만드는 건지, 광고 문구를 쓰는 건지, 성과 리포트를 만드는 건지 애매합니다.

반대로 이런 이름은 훨씬 낫습니다.

이름만 봐도 역할이 보입니다. AI도 덜 헷갈리고, 사람도 관리하기 쉽습니다.

여기서 하나 더 중요합니다. 스킬에는 AI가 이미 아는 뻔한 설명을 길게 쓰지 않는 게 좋습니다. 예를 들어 “블로그는 제목과 본문으로 구성됩니다” 같은 말은 큰 도움이 되지 않습니다.

Anthropic 공식 글도 비슷한 예를 듭니다. frontend design skill을 만들 때 “보기 좋은 UI를 만들어라” 같은 뻔한 말보다, Claude가 자주 반복하던 패턴인 Inter 폰트나 보라색 그라디언트를 피하라처럼 실제 실패 지점을 적는 편이 더 도움이 된다는 식입니다.

대신 AI가 자주 놓치는 기준을 적어야 합니다. “외부 글을 그대로 번역하지 말고, 한국 독자에게 필요한 맥락을 붙인다” 같은 내용이 더 쓸모 있습니다.

스킬은 AI를 묶어두는 족쇄도 아닙니다. 너무 세세하게 “항상 이 순서로만 해”라고 적으면, 상황이 조금만 달라져도 답답한 결과가 나올 수 있습니다. 해야 할 기준은 주되, 상황에 맞게 판단할 여지는 남겨두는 게 좋습니다.

스킬 설명은 소개글이 아니라 사용 신호입니다

스킬의 description도 중요합니다.

여기서 description은 사람에게 보여주는 멋진 소개문이 아닙니다. AI가 “이 요청에는 이 스킬을 써야겠다”라고 판단할 때 보는 힌트에 가깝습니다.

블로그 작성에 도움을 주는 스킬

참고 자료를 바탕으로 한국어 블로그 초안, 제목 후보, SEO 메타데이터를 작성해야 할 때 사용한다.

공식 글에서는 babysit-pr 스킬의 description 예시도 보여줍니다. 핵심은 “이 스킬이 얼마나 멋진가”가 아니라, Claude가 어떤 말에서 이 스킬을 떠올려야 하는지입니다.

A comprehensive tool for monitoring pull request status across the development lifecycle.

Monitors a PR until it merges. Trigger on 'babysit', 'watch CI', 'make sure this lands'.

한글로 풀면 이렇습니다. “PR 상태를 종합적으로 모니터링하는 도구”라고 쓰는 것보다, “PR이 merge될 때까지 지켜본다. babysit, watch CI, make sure this lands 같은 표현이 나오면 사용한다”라고 적는 편이 Claude에게 훨씬 직접적인 신호가 됩니다.

AI로 마케팅 콘텐츠를 만드는 업무도 똑같습니다. 처음부터 “마케팅 전체를 다 하는 스킬”을 만들 필요는 없습니다.

먼저 블로그 작성 하나를 안정화하고, 그다음 카드뉴스, 검수, 발행 준비를 하나씩 붙이면 됩니다.

나중에 SEO, 사실 검수, 발행 체크리스트를 다른 업무에서도 자주 쓰게 되면 그때 따로 분리하면 됩니다. 처음부터 잘게 쪼개려고 하면 오히려 시작이 어려워집니다.

스킬에서 진짜 중요한 건 “자주 틀리는 것”입니다

Claude Code 팀 글에서 특히 실용적이었던 부분은 “자주 하는 실수”를 따로 모아두라는 이야기입니다.

공식 글에서는 이런 내용을 gotchas라고 부릅니다. 낯선 단어처럼 보이지만 어렵게 볼 필요는 없습니다. 여기서는 “AI가 이 일을 할 때 자주 하는 실수” 정도로 이해하면 됩니다.

사람은 한 번 실수하면 다음번에 조심하는데, AI는 같은 실수를 반복할 수 있습니다. 그래서 스킬 안에 “이 작업에서는 이 실수를 특히 조심해”라고 적어두는 겁니다.

Claude Code 팀은 이 부분이 스킬에서 가장 쓸모 있는 내용이라고 말합니다. 이유는 단순합니다. “잘 써줘” 같은 뻔한 설명보다 “이 부분에서 자주 실수하니 조심해”라는 말이 AI에게 훨씬 직접적인 도움이 되기 때문입니다.

The subscriptions table is append-only. The row you want is the one with the highest version, not the most recent created_at.

This field is called @request_id in the API gateway and trace_id in the billing service. They're the same value.

Staging returns 200 even when the Stripe webhook didn't actually process. Check payment_events for the real state.

subscriptions 테이블은 계속 추가되는 구조입니다. 원하는 행은 가장 최근 created_at이 아니라 version 값이 가장 높은 행입니다.

API gateway에서는 @request_id라고 부르고, billing service에서는 trace_id라고 부릅니다. 둘은 같은 값입니다.

staging에서는 Stripe webhook이 실제로 처리되지 않았는데도 200이 돌아올 수 있습니다. 진짜 상태는 payment_events를 확인해야 합니다.

이게 왜 “자주 하는 실수” 예시일까요?

AI는 보통 “가장 최근 데이터”를 찾으려고 할 수 있습니다. 그런데 이 회사의 시스템에서는 그게 틀린 방법입니다. 최신 행이 아니라 version이 가장 높은 행을 골라야 맞습니다.

이런 건 회사 내부 규칙을 모르면 누구나 틀리기 쉽습니다. AI도 마찬가지입니다.

블로그 작성 업무도 똑같습니다.

이렇게 적어두면 다음번에 AI가 같은 업무를 할 때 참고할 수 있습니다.

중요한 건 이런 실수 목록을 처음부터 완벽하게 만들려고 하지 않는 겁니다. Claude Code 팀도 스킬을 실제로 쓰면서 Claude가 자주 실패하는 지점을 계속 추가하라고 말합니다.

예를 들면 이렇게 추가하는 겁니다.

## 자주 하는 실수

- 외부 글을 다룰 때 “원문에서는”이라는 표현을 반복하지 말 것. 한국어 블로그에서는 “이 글에서는”, “Claude Code 팀은”처럼 자연스럽게 지칭한다.
- 복사해서 쓸 수 있는 프롬프트 예시는 인용문이 아니라 코드블럭으로 제공한다.
- 코드가 아닌 개념 비교는 코드블럭에 넣지 말고 표로 정리한다.

이게 스킬이 좋아지는 방식입니다. 처음부터 완벽한 매뉴얼을 만드는 게 아니라, 실제 작업에서 나온 실수를 하나씩 적어두면서 다음 결과물을 더 안정적으로 만드는 겁니다.

모든 내용을 한 파일에 넣을 필요는 없습니다

스킬을 만들다 보면 이런 마음이 들 수 있습니다.

“AI가 알아야 할 내용을 한 파일에 전부 넣어두면 더 좋지 않을까?”

처음에는 그럴듯해 보입니다. 하지만 실제로는 반대입니다.

한 파일에 너무 많은 내용을 넣으면 AI도 사람처럼 헷갈립니다. 블로그를 쓰는 데 필요한 정보, SEO 기준, 출처 표시 기준, 발행 체크리스트가 한꺼번에 섞이면 중요한 내용을 놓치기 쉽습니다.

사람 업무로 비유하면 더 쉽습니다.

책상 위에 계약서, 메모지, 영수증, 강의안, 체크리스트를 전부 한 더미로 쌓아두면 찾기 어렵습니다. 반대로 파일철을 나눠두면 필요할 때 필요한 것만 꺼내 보면 됩니다.

스킬도 똑같습니다. SKILL.md에는 가장 중요한 안내만 둡니다.

• 이 스킬을 언제 쓰는지
• 어떤 결과물을 만들어야 하는지
• 절대 하지 말아야 할 것은 무엇인지
• 필요할 때 어떤 파일을 참고하면 되는지

그리고 자세한 기준은 따로 나눠둡니다.

처음에는 이렇게 최소 버전으로 시작해도 됩니다.

반복해서 쓰다 보면 이렇게 확장할 수 있습니다.

이렇게 하면 AI는 처음부터 모든 자료를 다 읽지 않아도 됩니다. 블로그 구조가 필요할 때는 templates/blog-outline.md를 보고, 출처 표시가 필요할 때는 references/source-attribution.md를 보면 됩니다.

링크 확인처럼 반복되는 검사는 scripts/check-links.py 같은 스크립트로 맡길 수도 있습니다.

Claude Code 팀은 이런 방식을 progressive disclosure, 즉 점진적 공개라고 설명합니다. 말은 어렵지만 뜻은 단순합니다.

공식 글에서도 스킬을 “마크다운 파일 하나”가 아니라 폴더로 보라고 말합니다. SKILL.md가 중심 설명서라면, 그 옆에 참고 자료, 예시, 템플릿, 스크립트 같은 파일을 나눠둘 수 있다는 뜻입니다.

공식 원문의 예를 조금 더 구체적으로 풀면 queue-debugging 같은 스킬은 이런 구조가 될 수 있습니다.

SKILL.md에는 “대기열 문제가 의심되면 먼저 상태를 확인하고, 작업이 멈춰 있으면 references/stuck-jobs.md를 읽어라” 정도만 둡니다. 자세한 API 함수 시그니처나 장애별 확인 순서는 별도 파일로 빼둡니다. 그래야 Claude가 처음부터 모든 세부 문서를 읽지 않고, 상황에 맞는 자료만 꺼내 볼 수 있습니다.

반대로 너무 자세한 절차를 고정하면 Claude가 상황에 맞게 판단하지 못할 수 있습니다. 공식 글은 이를 “Claude를 railroading하지 말라”고 표현합니다. 여기서 railroading은 “정해진 선로로만 몰아넣는다”는 뜻에 가깝습니다.

cherry-pick-prod를 실행할 때는 항상 main에서 새 브랜치를 만들고,
항상 같은 PR 템플릿을 사용하고, 항상 같은 순서로만 처리한다.
다른 방법은 사용하지 않는다.

cherry-pick-prod는 운영 브랜치에 특정 커밋을 안전하게 옮길 때 사용한다.
격리된 worktree를 만들고, cherry-pick을 시도하고, 충돌이 있으면 원인을 설명한 뒤
상황에 맞게 해결한다. PR은 팀 템플릿을 참고하되, 변경 내용에 맞게 조정한다.

핵심은 기준을 주되, 모든 상황을 하나의 절차로 못 박지 않는 것입니다. 스킬은 반복 기준을 주는 도구이지, Claude의 판단력을 없애는 체크리스트가 아닙니다.

AI 콘텐츠 업무에 적용하면 이렇게 됩니다

공식 글에 나온 스킬 유형은 개발팀 기준입니다. 그래서 Library/API reference, CI/CD, Runbooks 같은 이름이 나옵니다.

이걸 개발 용어로 외울 필요는 없습니다. “반복 업무를 도와주는 스킬 종류”로 보면 됩니다.

여기부터는 원문의 개발팀 예시를 콘텐츠 업무에 적용해보는 해석입니다.

블로그 하나를 만들 때도 자료 정리, 기획, 초안, 검수, SEO, 발행 준비가 반복됩니다.

그럼 블로그 작성 스킬은 하나로 만들어야 할까요, 여러 개로 나눠야 할까요?

앞에서 본 것처럼 처음에는 SKILL.md에 핵심 안내를 적고, 필요해질 때 references/, templates/, scripts/를 붙여가면 됩니다.

즉, 처음부터 완성된 폴더를 만들라는 뜻이 아니라 필요해질 때 파일을 하나씩 붙이는 방식입니다.

프롬프트보다 먼저 물어봐야 할 질문

AI에게 일을 시키기 전에 이 질문을 해보면 좋습니다.

여기에 “예”가 많다면, 그 일은 프롬프트로 매번 처리하기보다 스킬로 만들 후보입니다.

블로그 작성은 딱 그런 업무입니다.

• 반복됩니다.
• 구조가 필요합니다.
• 출처와 저작권 기준이 필요합니다.
• SEO 메타데이터가 필요합니다.
• 발행 전 검수 기준이 필요합니다.

반대로 한 번만 하는 가벼운 아이디어 회의라면 굳이 스킬로 만들 필요가 없습니다. 스킬은 “자주 반복되는 일”을 안정적으로 처리하려고 만드는 것이니까요.

공식 원문에는 여기서 더 나아간 운영 팁도 나옵니다. 설정값을 config.json에 저장하는 법, 이전 실행 기록을 로그로 남기는 법, 반복 코드를 scripts/에 넣는 법, 훅과 마켓플레이스로 팀에서 스킬을 운영하는 법 같은 내용입니다.

이 글은 2편이므로 여기서는 좋은 스킬의 설계 원칙까지만 다룹니다. 실제 작성과 개선은 3편, 운영 시스템화는 4편에서 이어서 다룹니다.

오늘 바로 할 수 있는 것

거창한 스킬 시스템을 오늘 다 만들 필요는 없습니다.

자주 시키는 업무 하나만 고르면 됩니다. 그리고 세 가지만 적어보세요.

이 정도만 있어도 다음 작업이 훨씬 안정됩니다.

정리하면

Claude Code 팀의 글에서 가져갈 핵심은 단순합니다.

AI 자동화는 멋진 프롬프트 하나로 끝나는 일이 아닙니다. 반복되는 일을 매뉴얼로 만들고, 실제 작업에서 생긴 실수를 계속 반영하는 과정에 가깝습니다.

AI에게 매번 같은 설명을 반복하고 있다면, 그건 귀찮은 일이 생겼다는 뜻만은 아닙니다. 스킬로 만들 업무를 찾았다는 신호일 수 있습니다.