팟캐스트Hear the voice. See the shape of the thought.

Claude Code에는 기본 내장 서브에이전트가 있지만, 커스텀 서브에이전트를 만들면 특정 작업에 맞는 전문화된 동작을 직접 설정할 수 있습니다. 이 튜토리얼은 코드 리뷰 서브에이전트를 처음부터 만드는 과정을 다룹니다. `/agents` 명령어, 도구 선택, 모델 결정, 그리고 Claude가 언제 어떻게 위임하는지 제어하는 설정 파일의 필드까지 차례로 살펴봅니다. ## [00:03] 커스텀 서브에이전트란 무엇인가 Claude Code에는 내장 서브에이전트가 포함되어 있지만, 특정 작업을 전담하는 서브에이전트를 직접 만들 수도 있습니다. 커스텀 서브에이전트는 YAML front matter가 있는 마크다운 파일입니다. front matter는 Claude에게 해당 에이전트로 라우팅할 시점과 에이전트가 가진 기능을 알려주고, 마크다운 본문은 서브에이전트가 실행되는 시스템 프롬프트가 됩니다. > *"Custom sub aents are markdown files with YAML front matter. These markdown files contain configuration that helps claude understand when to use the sub aent and provides directions to the sub aent itself."* ## [00:28] /agents로 서브에이전트 만들기 `/agents` 명령어를 실행하면 에이전트 관리 패널이 열립니다. "새 에이전트 만들기"를 선택하면 두 가지를 묻습니다. 범위(현재 프로젝트 또는 머신의 모든 프로젝트에서 공유)와 생성 방법입니다. 권장 방법은 Claude가 자동으로 에이전트를 생성하도록 맡기는 것입니다. 내레이터가 코드 품질과 보안 문제를 검토하는 서브에이전트를 평범한 말로 요청하면 Claude가 나머지를 처리합니다. > *"Now, the easiest way to create a sub agent is with the / agents command. Next, you can create a sub agent manually, but we recommend using claw code to automatically generate it for you."* ## [00:56] 도구, 모델, 색상 설정하기 Claude가 파일을 작성하기 전에 서브에이전트가 접근할 수 있는 도구를 선택합니다. 코드 리뷰 에이전트는 편집 도구가 꼭 필요하지 않지만, 실행을 활성화해 두면 대기 중인 변경 사항을 더 쉽게 확인할 수 있습니다. 도구 선택 후 모델을 고릅니다. 속도 우선이면 haiku, 깊이 있는 분석은 opus, 그 중간은 sonnet입니다. 마지막으로 색상을 선택합니다. UI에서 서브에이전트를 한눈에 알아볼 수 있게 해주는 색상입니다. > *"Now, given that our sub agent is only responsible for reviewing code, you might decide to disallow tools for editing, but I'll leave an execution to allow the sub agent to more easily identify pending changes."* ## [01:43] 설정 파일 이해하기 생성된 파일은 요약 창에 표시된 경로의 프로젝트 내에 저장됩니다. 핵심 필드는 네 가지입니다. `name`은 고유 식별자로, 메시지에 `@agent-code-quality-reviewer`를 입력해 참조할 수 있습니다. `description`은 Claude가 읽고 위임 여부를 결정하는 내용으로, 한 줄로 작성해야 합니다(이스케이프된 `\n`은 그대로 literal 문자입니다). description에 "proactively"를 추가하면 Claude가 에이전트를 더 자주 사용하고, 예시 대화를 추가하면 라우팅이 더 정확해집니다. `tools`는 생성 시 부여된 접근 권한을 반영하지만 파일에서 직접 편집할 수 있습니다. > *"If you want Claude to use the sub agent automatically more often, add in the word proactively to the description."* ## [02:41] 시스템 프롬프트와 Claude의 활용 방식 `model` 필드는 `haiku`, `sonnet`, `opus`, `inherit` 중 하나를 받습니다. `inherit`는 서브에이전트를 상위 대화와 같은 모델로 실행합니다. front matter 아래의 모든 내용이 시스템 프롬프트입니다. 서브에이전트가 작업을 수행하는 방법과 결과를 메인 에이전트에게 돌려주는 방법을 안내합니다. > *"The system prompt will provide guidance to the sub agent, helping it understand how to complete its task and how it should return information back to the main agent."* ## [03:15] 서브에이전트 테스트하기 설정을 저장한 뒤 코드를 수정하고 Claude에게 검토를 요청합니다. 서브에이전트가 예상대로 트리거되지 않으면 `description` 필드부터 조정하세요. 더 구체적인 예시를 추가하면 Claude가 언제 위임해야 할지를 더 정확하게 파악합니다. > *"If the sub agent isn't being used when you expect, check your description. Adding more specific examples helps Claude understand when to delegate."* ## 등장인물 - **Anthropic Tutorial Narrator** (사람): 이 에피소드의 단독 진행자; Anthropic 공식 YouTube 채널에서 Claude Code 서브에이전트 튜토리얼 시리즈를 진행함 - **Claude Code** (소프트웨어): Anthropic의 AI 코딩 어시스턴트; 내장 서브에이전트와 사용자가 만든 커스텀 서브에이전트를 모두 지원 - **커스텀 서브에이전트** (개념): YAML front matter가 있는 마크다운 파일로, Claude Code가 특정 작업을 전문화된 에이전트 인스턴스에 위임하도록 설정 - **/agents command** (개념): 서브에이전트를 만들고 관리하는 Claude Code UI 진입점; 프로젝트 범위 또는 전역 범위 제공 - **시스템 프롬프트** (개념): 서브에이전트 설정 파일의 마크다운 본문; 런타임에 서브에이전트에게 작업 지침과 출력 형식 안내를 제공 - **Anthropic** (조직): Claude 및 Claude Code 플랫폼의 개발사

Anthropic의 Claude Code 시리즈 튜토리얼로, 신뢰할 수 있는 서브에이전트와 방향을 잃거나 멈추거나 건드려서는 안 되는 파일을 건드리는 서브에이전트를 구분하는 네 가지 구체적인 패턴을 다룬다. 내레이터는 코드 리뷰어와 웹 검색 서브에이전트를 예시로 삼아 각 패턴을 설명하며, 어떤 설정을 왜 바꿔야 하는지 직접 보여준다. ## [00:03] 이름과 설명으로 서브에이전트 동작 제어하기 메인 컨텍스트 윈도우 에이전트에게 보내는 모든 메시지에는 시스템 프롬프트를 통해 등록된 각 서브에이전트의 이름과 설명이 포함된다. 따라서 설명은 두 가지 역할을 동시에 한다. 오케스트레이터에게 서브에이전트를 *언제* 실행할지 알려주고, 입력 프롬프트 작성 시 사용할 템플릿을 제공한다. 튜토리얼은 코드 리뷰어 서브에이전트로 이를 보여준다. 원래 설정에서는 오케스트레이터가 서브에이전트에게 직접 `git diff`를 실행하라고 일반적인 프롬프트를 작성한다. 설명을 "리뷰할 파일을 에이전트에게 정확히 알려줘야 한다"로 바꾸면 파일 선택의 책임이 오케스트레이터로 넘어가고, 다음 실행에서 입력 프롬프트가 눈에 띄게 구체적으로 바뀐다. 웹 검색 서브에이전트도 마찬가지다. 설명에 "인용 가능한 출처를 반환하라"를 추가하면 메인 에이전트가 작업을 위임할 때 그 지시를 자동으로 포함시킨다. > *"메인 에이전트가 서브에이전트를 자동으로 실행하는 시점을 더 잘 제어하려면 이름과 설명을 수정해야 합니다."* ## [01:41] 출력 형식 정의하기 내레이터는 출력 형식을 단일 개선 사항 중 효과가 가장 큰 것으로 꼽는다. 형식이 없으면 서브에이전트는 언제 충분히 했는지 명확한 신호를 받지 못하고 계속 실행되면서 컨텍스트를 쌓고 토큰을 소모한다. 구조화된 출력 형식은 자연스러운 종료 지점을 만들어준다. 서브에이전트는 필수 필드가 채워지면 작업이 끝났음을 안다. 실질적으로는 서브에이전트의 시스템 프롬프트에 명확한 스키마를 직접 추가하는 것을 의미한다. 요약 블록, 발견 목록, 상태 필드 등이 그 예다. > *"출력 형식이 정의되지 않으면 서브에이전트는 연구가 충분히 됐는지 판단하는 데 어려움을 겪고, 출력 형식이 주어진 서브에이전트보다 훨씬 오래 실행되는 경향이 있습니다."* ## [02:04] 요약에서 장애물 보고하기 서브에이전트가 문제를 해결했을 때 — 의존성 충돌, 예상치 못한 플래그가 필요한 명령, 환경의 특이사항 등 — 메인 에이전트는 그 정보가 필요하다. 없으면 다음 단계에서 같은 벽에 부딪힌다. 해결책은 출력 형식 자체에 장애물 보고를 필수로 넣는 것이다. 내레이터는 항상 드러나야 할 카테고리를 나열한다. 마주친 장애물, 설정 문제, 발견한 우회 방법, 특별한 플래그나 설정이 필요했던 명령, 문제를 일으킨 임포트나 의존성. 이것들을 필수 출력 스키마에 포함시키면 메인 에이전트는 서브에이전트가 힘들게 얻은 발견을 그대로 물려받아 처음부터 다시 발견하지 않아도 된다. > *"그렇지 않으면 메인 에이전트가 같은 해결책을 다시 발견해야 합니다. 마주친 장애물, 설정 문제, 발견한 우회 방법이나 환경 특이사항, 특별한 플래그나 설정이 필요했던 명령, 문제를 일으킨 의존성이나 임포트가 모두 해당됩니다."* ## [02:42] 역할별 도구 접근 제한하기 도구 접근 제어는 단순한 보안 장치가 아니라 명확성 도구이기도 하다. `glob`, `grep`, `read`만 가진 읽기 전용 서브에이전트는 실수로 파일을 수정할 수 없어서, 설정을 읽는 누구에게든 역할이 명확하게 전달된다. 내레이터는 세 가지 접근 단계를 세 가지 서브에이전트 역할에 대응시킨다. 리서치 서브에이전트는 코드베이스 탐색에 쓰기가 필요 없으므로 읽기 전용 접근을 받는다. 리뷰어는 `git diff`용 `bash`를 받되 파일 편집 도구는 없다. CSS 업데이트를 적용하는 에이전트처럼 코드 변경이 명시적으로 요구되는 서브에이전트만 `edit`와 `write`를 받는다. 서브에이전트가 여럿 있을 때 도구 목록은 각각이 무엇을 해야 하는지를 기계가 읽을 수 있는 형태로 요약해준다. > *"edit와 write는 CSS 업데이트를 적용하는 스타일링 에이전트처럼 실제로 코드를 변경해야 하는 서브에이전트에게만 주세요."* ## [03:27] 효과적인 서브에이전트를 위한 네 가지 패턴 튜토리얼은 네 가지 패턴을 한 문장으로 정리하며 마무리된다. 구조화된 출력, 장애물 보고, 구체적인 설명, 제한된 도구 접근. 각 패턴은 나머지를 강화한다. 정확한 설명은 입력 프롬프트의 모호함을 줄이고, 출력 형식은 종료 지점을 만들며, 장애물 보고는 에이전트 경계를 넘어 컨텍스트를 보존하고, 최소한의 도구 접근은 남은 모호함을 증폭시킬 수 있는 부작용을 막는다. > *"효과적인 서브에이전트는 구조화된 출력을 사용하고, 장애물을 보고하고, 구체적인 설명을 갖추고, 도구 접근을 제한합니다."* ## 등장 항목 - **Anthropic Tutorial Narrator** (인물): Claude Code 서브에이전트 튜토리얼 시리즈 진행자, Anthropic을 대표하여 발표 - **Claude Code** (소프트웨어): 다단계 엔지니어링 작업을 수행하기 위해 서브에이전트를 오케스트레이션하는 Anthropic의 에이전트형 코딩 도구 - **Subagent** (개념): 오케스트레이터 에이전트가 실행하는 특화된 Claude 인스턴스로, 고유한 시스템 프롬프트, 도구 접근 권한, 입력 프롬프트를 가짐 - **Output format** (개념): 서브에이전트의 시스템 프롬프트에 정의된 필수 스키마로, 종료 조건을 만들고 메인 에이전트에 반환되는 정보를 구조화함 - **Obstacle reporting** (개념): 서브에이전트가 우회 방법, 의존성 문제, 환경 특이사항을 출력에 포함시키도록 요구하는 패턴으로, 오케스트레이터가 이를 다시 발견하지 않아도 됨 - **Tool access scoping** (개념): 각 서브에이전트를 역할에 필요한 도구만으로 제한하는 것 — 리서치는 읽기 전용, 리뷰는 bash, 파일을 변경해야 하는 에이전트만 edit/write - **Anthropic** (조직): Claude와 Claude Code 에이전트형 코딩 플랫폼을 만든 회사

서브에이전트는 Claude Code가 작업을 위임할 수 있는 전문화된 보조 에이전트입니다. 각 서브에이전트는 독립된 컨텍스트 창에서 실행되어 작업을 자율적으로 처리한 뒤, 핵심 요약만 반환하고 중간 과정 전체는 삭제됩니다. Anthropic의 이 2분짜리 튜토리얼은 해당 격리가 메인 컨텍스트 창을 사용 가능한 상태로 유지하는 데 왜 중요한지 설명하고, 코드 탐색 시나리오를 통해 트레이드오프를 보여주며, Claude Code에 기본 내장된 서브에이전트 목록을 소개합니다. ## [00:03] 서브에이전트란 무엇인가 서브에이전트는 직접 정의한 커스텀 시스템 프롬프트로 초기화된 별도의 대화 컨텍스트 창에서 실행됩니다. 상위 에이전트(메인 스레드의 Claude Code)는 요청 내용을 바탕으로 서브에이전트에게 작업 설명을 전달합니다. 서브에이전트는 이를 자율적으로 처리한 뒤 메인 스레드에 요약을 반환하고, 중간 작업은 모두 격리된 채로 남습니다. > *"Sub-agents are specialized assistants that Claude can delegate tasks to."* 핵심 설계 원칙: 서브에이전트가 작업을 마치면 해당 대화 스레드 전체가 완전히 삭제됩니다. 반환된 요약만 메인 대화에 남습니다. ## [00:24] 컨텍스트 창 관리 Claude가 메인 스레드에서 수행하는 모든 도구 호출 — 파일 읽기, 검색, 함수 추적 — 은 메인 컨텍스트 창에 쌓입니다. 긴 세션에서는 금방 가득 차게 됩니다. 서브에이전트는 개별 조사 및 실행 작업을 오프로드하여 그 비용이 메인 창에 부과되지 않도록 하기 위해 존재합니다. > *"Each sub-agent runs in its own conversation contacts window with a custom system prompt that you define."* 트레이드오프는 명확합니다. 메인 창은 깔끔한 컨텍스트를 유지하지만, 서브에이전트가 어떻게 결론에 도달했는지, 과정에서 무엇을 발견했는지는 볼 수 없습니다. 답만 받을 뿐, 추론 과정은 알 수 없습니다. ## [01:13] 구체적인 예시: 결제 시스템 낯선 코드베이스에서 어떤 서비스가 환불을 처리하는지 Claude Code로 파악하는 상황을 생각해 보세요. 서브에이전트 없이는 Claude가 파일 15개를 읽고, 여러 번 검색하고, 여러 함수 호출을 추적할 수 있으며, 사실 하나만 필요했음에도 그 모든 과정이 메인 컨텍스트 창을 채웁니다. > *"With a sub-agent, you get the answer without the journey."* 서브에이전트가 코드베이스를 탐색하고 답을 찾아 집중된 요약을 반환하므로 메인 컨텍스트가 깔끔하게 유지됩니다. 잃는 것은 가시성입니다. 어떤 파일을 읽었는지, 어떤 추적 경로를 밟았는지는 확인할 수 없습니다. ## [02:00] Claude Code의 기본 내장 서브에이전트 Claude Code는 즉시 사용 가능한 세 가지 기본 내장 서브에이전트를 제공합니다. - **범용 서브에이전트** — 탐색과 실행이 모두 필요한 다단계 작업을 위한 에이전트. - **Explore 서브에이전트** — 전체 작업 루프 없이 코드베이스를 빠르게 검색하는 에이전트. - **Plan 서브에이전트** — 플랜 모드에서 코드베이스를 조사·분석한 뒤 계획을 제시하는 에이전트. > *"And you can also create your own sub-agents with custom system prompts and tool access."* 이 세 가지 외에도, 특정 워크플로에 맞게 자체 시스템 프롬프트와 도구 접근 목록을 갖춘 커스텀 서브에이전트를 직접 정의할 수 있습니다. ## [02:30] 서브에이전트를 써야 할 때 서브에이전트는 메인 창에 많은 중간 컨텍스트를 쌓을 수밖에 없는 독립적이고 자기 완결적인 질문이나 작업이 있을 때 효과를 발휘합니다. > *"Sub-agents like Claude Code break work into focused pieces, keep your main context window clean, and bring back just what you need, whether you're using the built-in ones or creating your own."* 컨텍스트 창 압박이 누적되는 긴 Claude Code 세션에서 특히 유용합니다. 서브 작업을 서브에이전트에게 넘기면 메인 스레드에 흘러들어오는 부담이 줄어들어, 세션이 효과적으로 지속되는 시간이 늘어납니다. ## 등장 인물 - **Anthropic Tutorial Narrator** (인물): Anthropic이 제작한 "Claude Code subagents" 튜토리얼 시리즈의 나레이터 - **Claude Code** (소프트웨어): Anthropic의 에이전트 기반 코딩 어시스턴트; 서브에이전트가 동작하는 호스트 환경 - **Claude** (소프트웨어): Claude Code와 서브에이전트를 구동하는 기반 AI 모델 - **서브에이전트** (개념): Claude Code가 작업을 위임하는 전문화된 보조 에이전트로, 자체 시스템 프롬프트를 갖춘 격리된 컨텍스트 창에서 실행 - **컨텍스트 창** (개념): 모든 대화 기록, 도구 호출, 결과를 담는 유한한 토큰 버퍼; 서브에이전트는 중간 작업으로 채워지는 것을 방지 - **범용 서브에이전트** (소프트웨어): 다단계 탐색·실행 작업을 위한 기본 내장 Claude Code 서브에이전트 - **Explore 서브에이전트** (소프트웨어): 코드베이스 빠른 검색에 최적화된 기본 내장 Claude Code 서브에이전트 - **Plan 서브에이전트** (소프트웨어): 플랜 모드에서 계획 제시 전 코드베이스를 조사하는 기본 내장 Claude Code 서브에이전트 - **Anthropic** (조직): Claude와 Claude Code의 개발사; 이 튜토리얼 시리즈의 제작사

Claude Code 스킬은 전문 지식을 한 번만 담아두는 재사용 가능한 마크다운 파일입니다. 요청이 일치하면 Claude가 자동으로 스킬을 활성화하므로, 사용자가 지시를 반복하거나 슬래시 명령어를 입력할 필요가 없습니다. 이 3분짜리 튜토리얼은 스킬이 무엇인지, 어디에 저장되는지, CLAUDE.md 파일과 어떻게 다른지, 그리고 스킬을 작성해야 할 시점을 알려주는 신호가 무엇인지 설명합니다. ## [00:03] 스킬이 해결하는 반복 문제 팀의 코딩 표준을 설명하거나, PR 피드백 구조를 다시 안내하거나, Claude에게 선호하는 커밋 메시지 형식을 상기시킬 때마다 같은 말을 반복하게 됩니다. 내레이터는 세 가지 연속 사례로 시작하며 스킬이 해소하는 바로 그 마찰 지점을 짚어냅니다. > *"Claude에게 팀의 코딩 표준을 설명할 때마다, 당신은 자신을 반복하고 있습니다."* ## [00:20] 스킬의 정의와 Claude의 선택 방식 스킬은 Claude에게 무언가를 한 번 가르쳐두는 마크다운 파일입니다. Claude는 그 지시를 저장한 뒤, 상황이 맞을 때 자동으로 적용합니다. Claude Code에서 이 파일은 SKILL.md입니다. 그 파일의 description 필드가 핵심 메커니즘입니다. PR 리뷰를 요청하면 Claude가 요청 내용을 사용 가능한 모든 스킬 설명과 비교해 일치하는 스킬을 활성화합니다. > *"Claude는 요청을 읽고, 사용 가능한 모든 스킬 설명과 비교한 뒤, 일치하는 스킬을 활성화합니다."* ## [01:05] 스킬 저장 위치: 개인용 vs. 프로젝트용 스킬은 누가 필요로 하느냐에 따라 두 곳에 저장됩니다. 개인 스킬은 ~/.claude/skills에 두면 모든 프로젝트에서 따라다닙니다. 커밋 메시지 스타일, 문서 형식, 코드 설명 방식 같은 것들이 여기에 해당합니다. 프로젝트 스킬은 저장소 루트의 .claude/skills에 두면, 해당 저장소를 클론하는 누구든 자동으로 받게 됩니다. 이 두 번째 위치가 팀 표준이 자리하는 곳입니다. 브랜드 가이드라인, 웹 디자인에서 선호하는 폰트와 색상 같은 것들이 그 예입니다. > *"저장소를 클론하는 누구든 이 스킬을 자동으로 받습니다."* ## [01:42] 스킬 vs. CLAUDE.md: 자동 실행과 컨텍스트 효율 Claude Code는 여러 커스터마이징 레이어를 제공하며, 스킬은 그 중 고유한 위치를 차지합니다. CLAUDE.md 파일은 모든 대화에 조건 없이 로드됩니다. "항상 TypeScript strict mode를 사용하라"처럼 전역 규칙에 적합합니다. 스킬은 온디맨드로 로드되며, 현재 요청과 일치할 때만 활성화되고, 그 시점에는 이름과 설명만 컨텍스트에 들어옵니다. 스킬 전체 본문은 실제로 트리거될 때만 로드됩니다. 덕분에 디버깅 중에는 PR 리뷰 체크리스트가 컨텍스트 창 밖에 머물고, 실제로 리뷰를 요청할 때만 불러와집니다. 슬래시 명령어는 직접 입력해야 하지만, 스킬은 그럴 필요가 없습니다. > *"스킬은 자동으로 실행되고 작업에 특화되어 있다는 점에서 독보적입니다."* ## [02:27] 스킬을 작성해야 할 때 스킬은 특정 작업에 연결된 전문 지식에 가장 잘 맞습니다. 팀의 코드 리뷰 기준, 커밋 메시지 형식, 브랜드 가이드라인 같은 것들이 그 예입니다. 마지막 규칙은 단순하고 실용적입니다. 같은 내용을 Claude에게 반복해서 설명하고 있다면, 그것이 바로 스킬로 만들어야 할 신호입니다. > *"같은 내용을 Claude에게 반복해서 설명하고 있다면, 그건 작성을 기다리는 스킬입니다."* ## 등장인물 - **Anthropic Tutorial Narrator** (인물): Claude Code 스킬 튜토리얼 시리즈의 내레이터 겸 진행자 - **Claude Code** (소프트웨어): Anthropic의 AI 코딩 어시스턴트; 스킬이 발견되고 적용되는 런타임 환경 - **SKILL.md** (개념): 스킬을 정의하는 마크다운 파일 — Claude를 위한 이름, 설명, 지시 사항이 담겨 있음 - **CLAUDE.md** (개념): 모든 Claude Code 대화에 조건 없이 로드되는 프로젝트 수준 또는 전역 지시 파일; 스킬과 대비되는 개념 - **Anthropic** (기관): Claude와 Claude Code를 만든 회사

한 명의 엔지니어가 사용하는 PR review skill은 유용하다. 같은 skill을 팀 전체에 배포하면 코드 리뷰가 표준화되고 조직 전체에 일관된 경험이 만들어진다. 이 튜토리얼은 네 가지 구체적인 배포 방법 — repository 커밋, plugins, enterprise managed settings, custom sub-agents — 을 살펴보고 각각 언제 쓰는지 정확히 설명한다. Sub-agent 섹션에는 직관에 반하는 주의사항이 있다: sub-agents는 skills를 자동으로 상속하지 않으며, 내장 agents는 skills에 전혀 접근할 수 없다. ## [00:01] 공유가 skill 가치를 배가시키는 이유 한 개발자에게만 머무는 skill은 제 역할을 한다. 같은 skill을 팀에 배포하면 기준이 고정되고, 개인별 편차가 사라지며, 모든 리뷰가 같은 모습과 느낌을 갖게 된다. 진행자는 개인 사용과 팀 규모 사용의 직접적인 대비로 시작한 뒤 네 가지 공유 메커니즘을 열거한다. > *"A PR review skill that only you use is helpful. The same skill shared across your team standardizes code review and provides a consistent experience amongst your organization which is much better."* ## [00:18] Repository에 skills 커밋하기 가장 마찰이 적은 방법: project repo 내부 `.claude/skills`에 skills를 두면 된다. Repository를 clone한 누구든 즉시 그 skills를 갖게 된다 — 별도의 설치 단계도, 추가 도구도 필요 없다. 업데이트는 일반적인 `git pull` 사이클로 전달된다. 팀 코딩 표준, 프로젝트 특화 워크플로, 코드베이스 자체 구조를 참조하는 skills에 적합한 방식이다. > *"Anyone who clones the repository gets these skills automatically. No extra installation, it's just what you're doing already."* ## [00:45] Plugins을 통한 skills 배포 Plugins는 단일 프로젝트를 넘어 이동하도록 설계된 맞춤 기능으로 Claude Code를 확장한다. Plugin 프로젝트 내부에서 `skills/` 디렉토리는 `.claude/`의 구조 — skill 이름, `SKILL.md` — 를 그대로 반영한다. Marketplace에 게시되면 어떤 Claude Code 사용자든 plugin을 다운로드해 활성화할 수 있다. 한 팀의 관례보다 더 넓은 커뮤니티를 위할 만큼 범용적인 skills에 적합한 채널이다. > *"Think of plugins as ways to extend Claude Code with custom functionality, but designed to be shared across teams and projects."* ## [01:26] Managed settings로 전사 배포 관리자는 managed settings를 통해 조직의 모든 개발자에게 skills를 배포할 수 있다. Enterprise skills는 최고 우선순위를 가진다: 같은 이름의 개인, 프로젝트, plugin skills를 모두 덮어쓴다. 의도된 용도는 필수 기준 — 보안 요구사항, 컴플라이언스 워크플로, 균일해야 하는 코딩 관행 — 이다. 진행자는 "반드시"라는 표현을 명시적으로 강조한다: 제안이 아니다. > *"This is for mandatory standards, security requirements, compliance workflows, or coding practices that must be consistent across the organization."* ## [01:52] Custom sub-agents와 명시적 skill 로딩 Sub-agents는 메인 대화의 skills를 상속하지 않는다. 내장 agents(explorer, planner, verify)는 skills에 전혀 접근할 수 없다. `.claude/agents`의 `agent.md` 파일로 정의된 custom sub-agents만 skills를 사용할 수 있으며, 그것도 해당 파일의 `skills:` 필드에 명시적으로 나열된 것만 가능하다. Skills는 sub-agent가 시작될 때 로드되며 필요할 때가 아니므로, 목록은 간결하게 유지해야 한다: 에이전트의 목적에 항상 필요한 skills만 포함해야 한다. 튜토리얼은 Claude Code sub-agent 생성기로 sub-agent를 만들고 기존 `agent.md`에 skills를 연결하는 방법을 시연한다. > *"Built-in agents like the explorer, planner, and verify can't access skills at all. Only custom sub-agents you define can use them, and only when you explicitly list them."* ## [03:18] 마무리: 올바른 배포 방법 선택하기 마지막 부분은 각 방법을 해당 시나리오에 매핑한다: 팀 접근을 위한 프로젝트 디렉토리, 저장소 간 공유를 위한 plugins, 전사 필수 기준을 위한 enterprise 배포, 격리된 작업 위임을 위한 명시적 sub-agent skill 목록. Sub-agent 주의사항이 다시 한번 나온다 — 특정 에이전트의 업무에 항상 필요한 skills만 나열해야 한다. 시작 시 로드되지, 지연 로딩되지 않기 때문이다. > *"Share skills through project directories for team access, plugins for cross-repository distribution, or enterprise deployment for organization-wide standards."* ## 등장인물 - **Anthropic Tutorial Narrator** (인물): Claude Code skills 튜토리얼 시리즈의 단독 진행자 - **Claude Code** (소프트웨어): Anthropic의 AI 코딩 어시스턴트; skills가 작성되고 배포되는 런타임 환경 - **Skills** (개념): `.claude/skills`에 배치된 재사용 가능한 명령어 집합으로 Claude Code의 동작을 확장 - **Plugins** (개념): 팀과 marketplace 사용자 간 공유를 위해 skills를 번들로 묶는 배포 가능한 패키지 - **Managed settings** (개념): 최고 우선순위 재정의로 skills를 조직 전체에 배포하는 enterprise 관리자 메커니즘 - **Sub-agents** (개념): `.claude/agents`의 `agent.md`로 정의된 맞춤형 Claude Code 에이전트; skills를 로드할 수 있는 유일한 에이전트 유형이며, 명시적으로 나열된 경우에만 가능 - **Anthropic** (조직): Claude Code를 만들고 Claude Code skills 튜토리얼 시리즈를 제작하는 회사

Claude Code skills 시리즈의 4분짜리 튜토리얼로, 기본 스킬을 신뢰할 수 있고 컨텍스트를 효율적으로 사용하는 도구로 만들어주는 고급 설정 필드를 다룬다. agentskills.io 표준의 전체 필드 세트 — `name`, `description`, `allowed_tools`, `model` — 를 살펴보고, progressive disclosure를 이용해 대형 스킬을 구조화하는 방법을 설명한다. 참조 자료와 스크립트가 매번 호출될 때마다가 아니라 실제로 필요할 때만 로드되도록 하는 방식이다. ## [00:02] 고급 스킬 필드 개요 agentskills.io 오픈 스탠다드는 필수 `name`과 `description` 외에도 여러 필드를 정의한다. `name`은 소문자와 하이픈으로 구성하고 64자 이하여야 하며, 디렉터리 이름과 일치해야 한다. `description`은 최대 1,024자로, Claude가 스킬 매칭에 사용하는 핵심 신호다. 두 개의 선택적 필드가 설정을 완성한다: 스킬이 호출할 수 있는 도구를 제한하는 `allowed_tools`와, 스킬을 특정 Claude 버전에 고정하는 `model`이다. > *"A basic skill works with just a name and description, but here are some other advanced tips that can make your skills really effective in Claude Code."* ## [00:39] 효과적인 description 작성하기 "강아지 도움"처럼 모호한 description은 Claude가 범위와 트리거를 추측하게 만든다. 좋은 description은 딱 두 가지 질문에 답한다: 이 스킬은 무엇을 하는가, 그리고 Claude는 언제 이를 사용해야 하는가? 사용자 요청의 자연스러운 표현에 맞는 키워드를 선택하는 것이 트리거되지 않는 스킬을 고치는 핵심이다. > *"A good description answers two questions. What does this skill do? And when should Claude use it?"* ## [01:20] allowed_tools로 도구 제한하기 `allowed_tools`는 스킬을 정해진 범위로 제한하는 메커니즘이다. 예를 들어 보안에 민감한 워크플로에서 읽기 전용 접근만 허용할 수 있다. 이 필드를 설정하면 Claude는 권한 요청 없이 해당 도구만 호출할 수 있으며, 편집·쓰기·Bash는 불가능하다. 필드를 생략하면 Claude의 기본 권한 모델이 그대로 유지된다. > *"When this skill is active, Claude can only use those tools without asking permission. No editing, no writing, no bash commands."* ## [01:49] 멀티 파일 스킬을 위한 progressive disclosure 스킬은 진행 중인 대화와 Claude의 컨텍스트 윈도우를 함께 사용한다. 모든 내용을 2만 줄짜리 `SKILL.md` 하나에 몰아넣으면 매번 호출 시 컨텍스트가 부풀고 파일 유지보수도 힘들어진다. 해결책: 핵심 지침은 `SKILL.md`에 두고, 참조 자료는 사용자 요청이 실제로 필요로 할 때만 Claude가 읽는 별도 파일로 옮기는 것이다. 스탠다드는 세 가지 지원 디렉터리를 제안한다 — 실행 코드용 `scripts/`, 문서용 `references/`, 이미지와 템플릿용 `assets/`. `SKILL.md`의 링크는 목차 항목처럼 작동하며, 해당 주제가 나오지 않으면 파일은 로드되지 않는다. 스킬 디렉터리의 스크립트는 소스 코드를 컨텍스트에 로드하지 않고 실행되어 출력만 토큰을 소비한다. `SKILL.md`를 500줄 이하로 유지하길 권장하며, 초과하면 스킬을 분할해야 한다는 신호다. > *"It's like having a table of contents in the context window rather than fitting the whole entire document in there."* ## [03:18] 정리: 스킬 메타데이터와 모범 사례 튜토리얼은 전체 설정 면을 다시 정리하며 마무리한다: `name`과 `description`은 필수, `allowed_tools`는 도구 범위를 제한, `model`은 Claude 버전을 고정한다. description에는 구체적인 행동 동사와 트리거 문구가 있어야 안정적으로 매칭된다. 대형 스킬에는 progressive disclosure로 `SKILL.md`를 500줄 이하로 유지하고 지원 파일은 실제 필요 시까지 미룬다. 스크립트는 소스를 로드하지 않고 실행되어 컨텍스트를 가볍게 유지한다. > *"Scripts can execute without loading their contents, keeping context efficient."* ## 엔티티 - **Anthropic Tutorial Narrator** (인물): Claude Code 스킬 설정을 설명하는 이 튜토리얼 시리즈의 단독 진행자. - **Claude Code** (소프트웨어): agentskills.io 표준에 따라 스킬을 로드하고 실행하는 Anthropic의 CLI 도구. - **agentskills.io** (조직): `name`, `description`, `allowed_tools`, `model` 및 디렉터리 규칙을 포함한 스킬 매니페스트 스키마를 정의하는 오픈 스탠다드. - **SKILL.md** (개념): Claude Code 스킬의 기본 매니페스트 파일. 지원 파일 링크를 포함해 500줄 이하를 유지해야 한다. - **allowed_tools** (개념): 특정 Claude 도구를 화이트리스트에 올려 읽기 전용 또는 샌드박스 스킬 모드를 가능하게 하는 선택적 스킬 필드. - **Progressive disclosure** (개념): 멀티 파일 스킬을 구조화하는 방식으로, 참조 파일과 스크립트가 활성 요청에서 실제로 필요할 때만 컨텍스트에 로드된다. - **Context window** (개념): 대화와 Claude가 로드하는 스킬 파일 간에 공유되는 토큰 예산. progressive disclosure가 절약하도록 설계된 핵심 자원.

이 3분짜리 튜토리얼은 Claude Code 개인 스킬을 처음부터 만드는 과정을 안내합니다. SKILL.md 파일이 담긴 디렉터리를 생성하고, 시작 시 스킬이 로드되는지 확인하고, Claude가 실제 요청에 스킬을 적용하는 모습을 직접 확인할 수 있습니다. 후반부에서는 Claude의 스킬 로딩 파이프라인이 어떻게 동작하는지 상세히 설명합니다. 네 가지 스캔 위치와 이름 전용 시작 패스, 확인 게이트, 이름 충돌을 해결하는 4단계 우선순위 체계까지 다룹니다. ## [00:03] 이 튜토리얼에서 만드는 것 진행자는 구체적인 목표로 시작합니다. 시각적 다이어그램과 비유를 사용해 코드를 설명하도록 Claude를 가르치는 스킬입니다. 스킬을 만든 뒤 Claude가 스킬을 인식하고 실행할 때 내부에서 어떤 일이 벌어지는지도 따라가 봅니다. > *"이 스킬은 Claude가 시각적 다이어그램과 비유를 사용해 코드를 설명하는 방법을 가르쳐 줄 것입니다."* ## [00:18] 스킬 파일 만들기 개인 스킬은 프로젝트 안이 아닌 홈 디렉터리에 위치합니다. 따라서 첫 번째 단계는 `~/.claude/skills/` 안에 스킬 이름으로 새 디렉터리를 만드는 것입니다. 그 안에 `SKILL.md` 파일 하나가 들어갑니다. 세 섹션이 핵심입니다. `name`(시작 시 Claude가 저장하는 식별자), `description`(스킬 호출 여부를 판단하는 매칭 기준), 그리고 두 번째 `---` 구분자 이후의 모든 내용(스킬이 발동될 때 Claude가 따르는 실제 지침)입니다. > *"skills 디렉터리 안에 스킬 이름으로 디렉터리를 만들고 있다는 점을 염두에 두세요."* ## [00:52] 스킬 로드 및 테스트 Claude Code는 요청이 들어올 때가 아닌 시작 시에 스킬을 스캔합니다. 따라서 파일을 만든 후 세션을 재시작해야 합니다. `/skills`를 실행하면 "PR description"(또는 방금 만든 스킬)이 목록에 표시되어야 합니다. 테스트하려면 몇 가지 변경 사항이 담긴 브랜치를 만들고 "Write a PR description for my changes."라고 요청을 보내세요. Claude는 PR description 스킬을 호출하고 있다고 알리고, diff를 읽은 뒤 매번 동일한 형식으로 설명을 작성합니다. > *"그러면 Claude가 PR description 스킬을 사용하고 있다고 보여줄 것입니다."* ## [01:25] Claude의 스킬 로드 내부 구조 시작 시 Claude Code는 네 곳을 스캔합니다. 엔터프라이즈 관리 설정, 개인 `~/.claude/skills/`, 프로젝트의 `.claude/` 디렉터리, 설치된 플러그인입니다. 전체 내용이 아닌 `name`과 `description`만 로드합니다. 요청이 들어오면 Claude는 저장된 설명과 비교합니다. "이 함수가 하는 일을 설명해 줘"는 "시각적 다이어그램으로 코드 설명하기"와 겹치므로 스킬이 매칭됩니다. 전체 SKILL.md를 읽기 전에 Claude는 확인을 요청해 어떤 컨텍스트가 주입되는지 사용자가 인지할 수 있게 합니다. > *"각 스킬의 이름과 설명만 로드합니다. 전체 내용은 로드하지 않습니다. 이 점이 나중에 중요합니다."* ## [02:02] 우선순위 규칙과 이름 충돌 자체 스킬이 포함된 저장소를 클론하면 이름 충돌이 생길 수 있습니다. Claude는 고정된 우선순위 체계로 이를 해결합니다. 엔터프라이즈(최상위) → 개인 → 프로젝트 → 플러그인(최하위) 순입니다. 엔터프라이즈 `code-review` 스킬은 항상 개인 `code-review` 스킬보다 우선합니다. 현실적인 해결책은 설명적인 이름을 사용하는 것입니다. 범용적인 `review` 대신 `security-review`나 `frontend-pr-review`처럼 구체적으로 지으면 충돌 자체를 방지할 수 있습니다. > *"회사에 엔터프라이즈 code review 스킬이 있고 개인 code review 스킬을 만든다면, 엔터프라이즈 버전이 우선합니다."* ## [02:52] 스킬 업데이트와 삭제 스킬 업데이트는 파일을 직접 편집하면 됩니다. SKILL.md를 열어 수정하고 저장합니다. 스킬 삭제는 해당 디렉터리를 지우면 됩니다. 두 작업 모두 변경 사항을 적용하려면 Claude Code를 재시작해야 합니다. 스킬 목록은 세션 시작 시 한 번 만들어지며 실시간 변경 사항은 감지되지 않습니다. > *"스킬을 업데이트하려면 skill.md 파일을 편집하고 변경 사항을 적용하려면 Claude Code를 재시작하세요."* ## 엔티티 - **Anthropic 튜토리얼 진행자** (인물): Claude Code skills 시리즈의 스킬 생성 튜토리얼을 진행하는 단독 호스트 - **Claude Code** (소프트웨어): Claude를 위한 Anthropic의 CLI. 시작 시 스킬을 스캔하고 사용자 요청이 스킬 설명과 일치하면 적용함 - **SKILL.md** (개념): 스킬을 정의하는 단일 파일. YAML 프론트매터(name, description)와 두 번째 `---` 구분자 이후의 자유형 지침 텍스트로 구성됨 - **Skills** (개념): Claude에게 일관된 행동 패턴을 가르치는 재사용 가능한 이름 있는 지침 세트. SKILL.md 파일이 들어있는 디렉터리 형태로 저장됨 - **Enterprise Skills** (개념): 4단계 우선순위 체계의 최상위를 차지하는 조직 관리 스킬. 개인, 프로젝트, 플러그인 스킬을 모두 재정의함 - **Anthropic** (조직): Claude와 Claude Code의 창시자. claude.com/resources/courses에서 이 튜토리얼 시리즈를 제공함

Claude Code는 개발자에게 Skills, CLAUDE.md, subagents, hooks, MCP 서버라는 다섯 가지 커스터마이징 수단을 제공한다. 각각 다른 용도로 설계된 도구들이다. 이 3분짜리 튜토리얼은 각 옵션을 올바른 사용 사례에 연결해서, Skills가 필요한 자리에 CLAUDE.md를 쓰거나 subagent가 필요한 자리에 hook을 연결하는 실수를 막아준다. ## [00:02] 다섯 가지 커스터마이징 옵션, 하나의 선택 문제 Claude Code가 동작 방식을 조정하는 다섯 가지 방법은 Skills, CLAUDE.md, subagents, hooks, MCP 서버다. 나레이터는 이 다섯 가지를 빠르게 나열하고 곧바로 질문의 초점을 "이게 뭔가요?"에서 "여기서 어떤 게 맞나요?"로 옮긴다. > *"각각 다른 문제를 해결합니다. 언제 무엇을 쓸지 알면 잘못된 것을 만드는 실수를 피할 수 있습니다."* 튜토리얼의 나머지는 본질적으로 이 한 문장에 대한 답이다. ## [00:18] CLAUDE.md vs Skills: 항상 켜짐 vs 필요할 때만 CLAUDE.md는 Claude가 모든 대화 시작 시 자동으로 읽는 파일이다. 별도 활성화가 필요 없다. 절대 잊어서는 안 되는 프로젝트 전반의 제약 — 프레임워크 선택, 코딩 스타일, 데이터베이스 규칙 — 을 담아두기에 적합하다. Skills는 반대로 필요할 때 로드된다. PR 리뷰 체크리스트는 실제로 리뷰를 요청할 때만 컨텍스트에 들어오고, 새 코드를 작성하는 동안에는 끼어들지 않는다. > *"Claude MD는 항상 적용되는 프로젝트 전반의 기준에 쓰세요 — 데이터베이스 스키마를 절대 수정하지 않기, 프레임워크 선호도, 코딩 스타일 같은 제약들이요."* 경계선은 영속성 대 관련성이다. 프로젝트의 모든 프롬프트에서 지켜져야 하는 지침은 CLAUDE.md에, 가끔만 유용한 것은 Skill에 넣는다. ## [01:03] Skills vs Subagents: 공유 컨텍스트 vs 독립 실행 Skills는 현재 대화에 지식을 주입한다 — 지침이 기존 컨텍스트와 합쳐진다. Subagents는 다르게 작동한다. 작업을 받아서 별도 실행 컨텍스트를 만들고, 독립적으로 작업한 뒤 메인 대화를 건드리지 않고 결과를 돌려준다. > *"작업을 별도 실행 컨텍스트에 위임하고 싶을 때 subagents를 쓰세요. 메인 대화와 다른 도구 접근이 필요하거나, 위임한 작업과 메인 컨텍스트 사이의 격리가 필요할 때도 마찬가지입니다."* 진행 중인 대화 전반에 걸쳐 Claude의 추론에 전문성을 불어넣고 싶을 때는 Skills를 쓴다. 메인 세션과 위임 작업 사이에 명확한 경계가 필요할 때 — 다른 도구, 오염 없음 — 는 subagents를 쓴다. ## [01:42] Hooks vs Skills: 이벤트 기반 vs 요청 기반 Hooks는 이벤트에 자동으로 반응한다 — Claude가 파일을 저장할 때마다 linter 실행, 특정 도구 호출 전 입력 검증. 사용자가 무엇을 요청하느냐가 아니라 Claude가 무엇을 하느냐가 트리거다. Skills는 정반대다. 요청 기반으로, 질의가 매칭될 때 활성화된다. > *"hook은 Claude가 파일을 저장할 때마다 linter를 실행하거나 특정 도구 호출 전에 입력을 검증할 수 있습니다. 모두 이벤트 기반이고, skills는 요청 기반입니다. 사용자가 무엇을 묻느냐에 따라 활성화됩니다."* 시스템 이벤트에 무조건 실행되어야 하는 동작이라면 hook이다. Claude가 질문을 받을 때 사고 방식을 형성해야 한다면 Skill이다. ## [02:15] 다섯 가지를 조합해 완전한 커스터마이징 완성하기 잘 설정된 Claude Code 환경은 각 도구를 제 역할에 맞게 쓴다. CLAUDE.md는 항상 켜져 있는 프로젝트 기준, Skills는 매 프롬프트를 어지럽히지 않아야 하는 작업별 전문성, hooks는 자동화된 사이드 이펙트, subagents는 격리된 위임 작업, MCP 서버는 외부 도구 접근. 이들은 대안이 아니라 조합해서 쓰는 것이다. > *"다른 옵션이 더 잘 맞을 때 모든 것을 skills에 욱여넣지 마세요. 여러 개를 동시에 쓸 수 있습니다."* Skills는 관련 주제가 나올 때 자동으로 활성화되고, CLAUDE.md는 항상 존재하며, subagents는 격리된 상태로 실행되고, hooks는 이벤트에 반응하며, MCP는 외부 도구를 제공한다. 각 관심사에 맞는 레이어를 고르고 자유롭게 조합하면 된다. ## 엔티티 - **Anthropic Tutorial Narrator** (인물): Anthropic을 대표해 이 Claude Code skills 튜토리얼 시리즈를 진행하는 호스트. - **Claude Code** (소프트웨어): Anthropic의 AI 기반 코딩 어시스턴트; 튜토리얼 시리즈의 주제. - **Skills** (개념): Claude가 사용자 요청을 인식할 때 활성화되는 온디맨드 지식 패키지; 현재 대화 컨텍스트에 지침을 주입한다. - **CLAUDE.md** (개념): 모든 Claude Code 대화에 자동으로 로드되는 설정 파일; 항상 켜져 있는 프로젝트 전반의 기준과 제약에 사용된다. - **Subagents** (개념): 메인 대화와 격리된 상태로 위임 작업을 처리하기 위해 생성되는 별도 실행 컨텍스트. - **Hooks** (개념): Claude의 특정 동작 — 파일 저장이나 도구 호출 등 — 에 반응하는 이벤트 기반 자동화. 사용자 요청과 무관하게 실행된다. - **MCP Servers** (소프트웨어): Claude Code 세션에 외부 도구를 제공하는 Model Context Protocol 서버. - **Anthropic** (조직): Claude Code의 개발사이자 Claude Code skills 튜토리얼 시리즈의 발행자.