Agent Mentor Learn
Claude Code Skills: 나만의 AI 워크플로 만들기 · 6 / 6강

레슨 6: 고급 패턴: 스킬을 더 강력하게 만들기

학습 목표:

  • 개인 스킬과 프로젝트 스킬의 차이 이해하기
  • Git으로 프로젝트 스킬 관리하기
  • 공유 스킬을 건강하게 유지하는 팀 관행 적용하기
  • 스킬 생태계에 또 무엇이 있는지 알기

전제: << 레슨 5

개인 스킬 vs 프로젝트 스킬

지금까지 만든 스킬은 모두 ~/.claude/skills/에 들어갔습니다. 그것들은 개인 스킬입니다 — 오직 당신만 쓸 수 있습니다. 1

그런데 팀에서는 보통 다른 것이 필요합니다.

  • 모두가 같은 기준으로 코드를 리뷰하는 것
  • 새로 합류한 사람이 저장소를 클론하면 곧바로 팀의 스킬을 갖게 되는 것
  • 스킬의 개선이 아무도 파일을 복사해 나르지 않아도 모두에게 닿는 것

그것이 바로 프로젝트 스킬이 존재하는 이유입니다. 2

둘은 어떻게 다른가

특성개인 스킬프로젝트 스킬
위치~/.claude/skills/.claude/skills/
범위당신의 모든 프로젝트현재 프로젝트
버전 관리필요 없음Git에 커밋
팀 공유공유되지 않음모두와 공유
전형적 용도개인 습관, 범용 도구프로젝트 컨벤션, 팀 프로세스

어느 쪽을 골라야 하나

개인 스킬: 2

  • 문서 형식 변환 (Markdown → Word)
  • 당신이 개인적으로 선호하는 작업 정리 방식
  • 자기만의 코드 스타일 취향
  • 모든 프로젝트에서 쓰고 싶은 범용 도구

프로젝트 스킬:

  • 팀의 코드 리뷰 기준
  • 프로젝트의 커밋 메시지 형식
  • 특정 프레임워크용 스캐폴딩
  • 프로젝트의 배포 절차

프로젝트 스킬 만들기

1단계: 프로젝트 디렉터리에 만들기

프로젝트로 이동합니다.

2단계: Git에 커밋하기

3단계: 팀원이 받아 가기

팀의 다른 사람들은 이렇게 합니다.

스킬이 곧바로 동작합니다. 따로 설정할 것은 없습니다. 1

Git으로 스킬 관리하기

프로젝트 스킬이 Git 안에 들어오면, Git이 할 수 있는 모든 것이 그대로 적용됩니다. 3

버전 이력

스킬 자체를 코드 리뷰하기

스킬을 리뷰하는 일은 코드를 리뷰하는 일만큼 중요합니다. 4

누군가 새 스킬을 제출하거나 기존 스킬을 바꿀 때:

  1. description이 명확한지 확인한다
  2. 지시문이 충분히 구체적인지 확인한다
  3. 실제로 의도대로 동작하는지 테스트한다
  4. 이 프로젝트에 자리를 차지할 만한지 판단한다 (기존 스킬과 충돌하지는 않는가?)

PR에서 스킬 파일을 리뷰할 때:

브랜치 활용

실험적인 스킬은 피처 브랜치에 둡니다.

오래가는 팀 관행

1. README에 문서화한다

스킬을 문서화하는 일은 간단합니다. 프로젝트 루트 README나 .claude/README.md에 목록을 적으면 됩니다. 4

2. 네이밍을 합의한다

팀 전체가 하나의 네이밍 컨벤션에 합의합니다. 3

권장:

  • 하이픈: commit-format, api-doc-gen
  • 동사-명사 또는 명사-동사: format-commit, review-code
  • 짧고 분명하게: 두세 단어

피할 것:

  • 숫자 접미사: skill-1, helper-v2
  • 모호한 것: tool, helper, utility
  • 프로젝트 약어에 숫자를 붙인 것: proj-skill-3

3. 주기적으로 솎아낸다

분기에 한 번씩 전체를 점검합니다. 3

거의 쓰이지 않는 스킬은 개선하거나 삭제해야 합니다. 쓰이지 않는 스킬이 쌓이면 Claude가 실제로 맞는 스킬을 찾기 어려워집니다.

4. 변경을 알린다

이건 중요합니다: 기존 스킬을 바꿨다면 팀 채널에 알립니다.

📢 스킬 업데이트: code-review
변경 사항:- React Hooks 규칙 점검 추가- 함수 길이 임계값 하향 (50줄 → 40줄)
영향:- 전에는 통과하던 코드가 이제 지적될 수 있음- 최근 PR을 다시 리뷰해 볼 만함
문의: @dana

스킬 조합하기

스킬 조합이란 여러 스킬을 이어 붙여 더 큰 작업 하나를 처리하는 것입니다. 1

/commit-format 로그인 버그 고침
(Claude가 포맷팅된 커밋을 돌려준다)
/code-review
(방금 바꾼 코드를 붙여넣는다)

또는 한 스킬 안에서 다른 스킬을 참조합니다.

바로 여기에서 스킬의 도달 범위가 생깁니다. 작고 목적이 하나뿐인 스킬들이 모여 더 큰 워크플로가 됩니다. Anthropic 엔지니어링 가이드는 이렇게 표현합니다. "Instead of building fragmented, custom-designed agents for each use case, anyone can now specialize their agents with composable capabilities." (각 유스케이스마다 파편화된 맞춤 에이전트를 만드는 대신, 이제 누구나 조합 가능한 능력으로 자기 에이전트를 전문화할 수 있다.) 5

기본기를 넘어서: 다음은 어디로

이제 핵심 기술은 갖췄습니다. 여기서부터 살펴볼 만한 방향이 몇 가지 있습니다.

선택적 프론트매터 필드

이 코스에서는 name과 description만 썼습니다. 더 있습니다. 6

  • model: 이 스킬이 어느 모델에서 돌아갈지 (더 강한 추론이 필요할 때)
  • allowed-tools: 스킬을 특정 도구로 제한
  • disable-model-invocation: Claude가 자동으로 로드하지 못하게 해서 수동 전용으로 만들기

셋 중에서 model은 모델을 고르고, allowed-tools는 권한 경계를 긋고, disable-model-invocation은 자동 트리거를 끄고 수동 호출만 남깁니다.

언제 쓰는가:

  • 비용이 큰 작업 (외부 API 호출) → disable-model-invocation으로 실수로 발동되지 않게
  • 신중한 추론이 필요한 작업 → model: claude-opus-4
  • 보안에 민감한 스킬 → allowed-tools로 건드릴 수 있는 범위 제한

전체 필드 목록은 공식 문서에 있습니다: https://code.claude.com/docs/en/skills 1

스킬과 MCP 서버

MCP(Model Context Protocol) 서버는 도구를 공급하고, 스킬은 워크플로 지식을 공급합니다. 7

예를 들면:

  • MCP 서버가 read_database 도구를 노출한다
  • 스킬이 그 도구를 써서 "월간 리포트 생성" 워크플로를 수행하는 법을 Claude에게 가르친다

이 둘을 합치면, 스킬은 Claude와 외부 시스템을 잇는 다리가 됩니다. 7

커뮤니티 스킬

다른 사람들이 무엇을 만들었는지 보려면:

남의 스킬을 실행하기 전에:

  • SKILL.md 전체를 읽고 무엇을 하는지 파악한다
  • 프로덕션 코드가 아니라 임시 프로젝트에서 먼저 시험한다
  • 위험할 만한 것을 살핀다 (스크립트 실행, 네트워크 접근, 파일 수정)

정리

  • 개인 스킬(~/.claude/skills/)은 자기 습관을 위한 것이고, 프로젝트 스킬(.claude/skills/)은 팀으로 일하기 위한 것이다 2
  • 프로젝트 스킬은 Git에 들어가고, 팀원은 자동으로 받아 가며, 다른 파일과 똑같이 버전 관리하고 브랜치를 딸 수 있다
  • 팀 관행: 문서화하기, 네이밍 합의하기, 주기적으로 솎아내기, 변경 알리기
  • 스킬은 조합된다: 작고 목적이 하나뿐인 스킬들이 모여 더 큰 워크플로가 된다 5
  • 다음 갈 곳: 선택적 프론트매터 필드, MCP 서버 연동, 커뮤니티 스킬

코스를 마쳤습니다

이제 이런 것을 할 수 있습니다.

  • ✅ 스킬이 어떻게 동작하고 어디에 쓰이는지 설명하기
  • ✅ 구조가 탄탄한 SKILL.md 작성하기
  • ✅ 체계적인 테스트와 디버깅 절차 돌리기
  • ✅ 더 복잡한 스킬 구성하기
  • ✅ 공유 스킬을 건강하게 유지하는 팀 관행 적용하기

다음에 할 일:

  1. 오늘 스킬 하나 쓰기: 이번 주에 세 번 설명한 작업을 골라 스킬로 만드세요
  2. 일주일 써 보기: 몇 번 호출했는지, 무엇이 깨졌는지, 시간을 얼마나 아꼈는지 기록하세요
  3. 반복하기: 놓친 점검을 추가하고, 실제로 벌어진 일에 맞춰 출력 형식을 조정하세요
  4. 공유하기: 정말 쓸모가 있다면 프로젝트 스킬로 승격시키세요

기억하세요: 좋은 스킬은 한 번 써서 끝나는 것이 아니라, 쓰이면서 다듬어집니다. 3 4

이제 몇 번이고 다시 설명해 온 그 워크플로를 직접 만들러 가세요.

Footnotes

  1. Claude Code 공식 문서: Extend Claude Code with skills — https://code.claude.com/docs/en/skills ↩ ↩2 ↩3 ↩4 ↩5

  2. Teach Claude Code your workflow: 커스텀 Skills 실습 가이드 — https://medium.com/@n913239/teach-claude-code-your-workflow-a-hands-on-guide-to-custom-skills-8bc35d4a11ed ↩ ↩2 ↩3

  3. Claude Code skills: .NET 워크플로와 재사용 가능한 프롬프트 — https://codewithmukesh.com/blog/skills-claude-code/ ↩ ↩2 ↩3 ↩4

  4. 자기 문서화 runbook으로서의 Claude skills — https://zackproser.com/blog/claude-skills-internal-training ↩ ↩2 ↩3

  5. Anthropic 엔지니어링 블로그: Equipping agents for the real world with Agent Skills — https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills ↩ ↩2

  6. Claude Skills 심층 분석(제1원리 관점) — https://leehanchung.github.io/blogs/2025/10/26/claude-skills-deep-dive/ ↩

  7. The complete guide to building skills for Claude(PDF) — https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf ↩ ↩2

연습

01

지금 작업 중인 프로젝트를 하나 골라 프로젝트 스킬을 추가합니다.

레벨 1: 첫 프로젝트 스킬 만들기
  1. 프로젝트 디렉터리에 .claude/skills/[skill-name]/을 만든다
  2. 그 프로젝트에 특화된 스킬을 쓴다 (커밋 형식, 배포 절차, 테스트 생성 등 맞는 것으로)
  3. Git에 커밋한다
  4. 프로젝트 README에 문서화한다
완료 기준 · 로컬에서 확인
02

팀원이 새 스킬을 추가하는 PR을 열었습니다. 리뷰를 작성하세요.

레벨 2: 스킬 PR 리뷰하기

PR 내용:

최소 3가지 문제를 짚어 리뷰를 작성하세요.

완료 기준 · 로컬에서 확인