클로드 코드 스킬 입문: 반복 업무를 AI 매뉴얼로 만드는 방법

AI에게 일을 시킬 때마다 같은 설명을 반복하고 있나요?

예를 들면 이런 말들입니다.

• “지난번처럼 정리해줘.”
• “빠진 항목 없는지 확인해줘.”
• “우리 기준에 맞게 다시 다듬어줘.”

한두 번은 괜찮습니다. 그런데 같은 일을 계속 맡긴다고 생각하면 금방 귀찮아집니다. 매번 기준을 다시 설명해야 하고, 확인할 항목도 다시 말해야 합니다. 지난번에는 잘하던 일을 이번에는 빼먹기도 합니다.

블로그 작성도 그렇습니다. 출처 표시, 제목 후보, SEO 메타 설명, 발행 체크리스트처럼 매번 반복해서 챙겨야 하는 기준이 많습니다.

이럴 때 필요한 게 **스킬(Skill)**입니다.

Claude Code는 Anthropic의 AI 코딩 도구입니다. 그리고 여기서 말하는 스킬은 Claude Code가 특정 일을 반복해서 잘 처리하도록 만든 작업 폴더에 가깝습니다.

Anthropic은 Claude Code를 만들면서 내부적으로 수백 개의 스킬을 운영했다고 합니다. 그 경험을 정리한 글이 Lessons from building Claude Code: How we use skills입니다.

다만 이 글은 원문을 그대로 옮긴 번역문이 아닙니다. Claude Code 팀의 스킬 운영 경험을 바탕으로, 개발자가 아닌 초보자도 이해할 수 있게 풀어본 1편 입문 해설입니다.

이 글에서 가져갈 것

스킬은 그냥 메모장이 아닙니다

처음에는 스킬을 이렇게 생각하기 쉽습니다.

“그냥 지시문 적어둔 마크다운 파일 아닌가?”

그런데 Claude Code 팀이 말하는 스킬은 조금 더 큽니다. 단순한 지시문 하나가 아니라, 반복 업무에 필요한 자료 묶음에 가깝습니다.

영어 이름을 외울 필요는 없습니다. 세 가지로 나누면 지시, 자동화 코드, 참고자료입니다.

프롬프트와 스킬의 차이는 이렇게 보면 쉽습니다.

말로 한 번 설명하면 그 순간에는 움직입니다. 하지만 다음번에 또 설명해야 합니다. 반대로 매뉴얼이 있으면 같은 일을 할 때마다 기준을 다시 꺼내 쓸 수 있습니다.

스킬이 없으면 뭐가 불편할까?

블로그 작성 업무를 예로 들어보겠습니다.

스킬이 없다면 매번 이런 지시를 해야 합니다.

Claude Code 팀의 스킬 운영 사례를 한국 독자가 이해하기 쉬운 블로그 글로 풀어줘.
단순 번역처럼 보이면 안 되고, 왜 AI 업무 매뉴얼이 필요한지 먼저 느껴지게 써줘.
Claude Code 팀이 말한 내용과 내 해설이 섞여 보이지 않게 출처를 자연스럽게 표시해줘.
제목 후보 3개, SEO 메타 설명, 태그도 같이 만들어줘.
마지막에는 발행 전에 확인할 체크리스트까지 정리해줘.

문제는 이걸 매번 똑같이 말하기가 어렵다는 겁니다.

오늘은 “출처를 자연스럽게 표시해줘”라고 말했는데, 내일은 그 말을 빼먹을 수 있습니다. 오늘은 “SEO 메타 설명도 만들어줘”라고 했는데, 다음번에는 제목 후보만 받고 끝날 수도 있습니다.

AI도 매번 같은 방식으로 이해하지 않습니다. 그래서 결과물이 흔들립니다.

• 어떤 글은 출처가 자연스럽게 들어갑니다.
• 어떤 글은 단순 요약문처럼 끝납니다.
• 어떤 글은 제목은 괜찮은데 SEO 정보가 빠집니다.
• 어떤 글은 발행 체크리스트가 없습니다.

스킬은 이 불편함을 줄이기 위한 장치입니다. 자주 반복되는 일의 작업 방식을 한 번 정리해두고, 필요할 때 AI가 그 내용을 읽고 일하게 만드는 겁니다.

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

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

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

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

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

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

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

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

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

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

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

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

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

스킬의 description도 중요합니다.

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

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

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

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가 중심 설명서라면, 그 옆에 참고 자료, 예시, 템플릿, 스크립트 같은 파일을 나눠둘 수 있다는 뜻입니다.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

이 글은 1편이므로 여기서는 입문 구조까지만 다룹니다. 이런 고급 운영 내용은 2편과 3편에서 나눠서 다루겠습니다.

오늘 바로 할 수 있는 것

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

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

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

정리하면

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

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

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

다음 편에서는 스킬을 실제로 만들고, 쓰면서 개선하는 방법을 다룹니다.