Anthropic이 마침내 공식 Agent Skills 튜토리얼 영상을 공개했습니다. 총 6개의 레슨으로 구성되어 있으며, 전체 길이는 22분입니다. Skills가 무엇인지부터 시작하여 생성 방법, 멀티 파일 설정, 다른 기능과의 차이점, 공유 방법, 문제 해결까지 Skills의 전체 라이프사이클을 다룹니다.
이 튜토리얼의 가장 큰 가치는 Skill을 작성하는 방법을 가르쳐주는 것뿐만 아니라, Skills의 설계 철학과 기본 메커니즘을 설명한다는 점입니다. 사람들이 Skills를 사용할 때 겪는 많은 문제는 이러한 메커니즘에 대한 이해 부족에서 비롯됩니다.
Skills는 어떤 문제를 해결하나요?
팀의 코딩 표준을 Claude에게 매번 설명할 때마다, 같은 말을 반복하고 있습니다. PR 리뷰를 할 때마다, 피드백을 어떻게 정리해줬으면 하는지 다시 설명해야 합니다. 커밋 메시지를 작성할 때마다, 선호하는 형식을 Claude에게 다시 알려줘야 합니다.
Skills는 이러한 반복을 없애기 위해 설계되었습니다. Skill은 Claude에게 어떤 작업을 한 번만 가르쳐주는 Markdown 파일이며, Claude는 관련 상황에서 해당 지식을 자동으로 적용합니다.
더 정확히 말하면, Agent Skill은 명령어, 스크립트, 리소스를 포함하는 폴더입니다. Claude는 이를 자동으로 발견하고 활용하여 작업을 더 정확하고 효율적으로 완료할 수 있습니다.
핵심 메커니즘은 description 필드입니다. Claude가 시작되면 모든 Skills의 이름과 설명을 로드합니다. 사용자가 요청을 보내면, Claude는 요청과 사용 가능한 모든 Skills의 설명을 의미적으로 비교하여 일치하는 Skill을 찾아 활성화합니다. 활성화된 후에야 전체 Skill 콘텐츠가 컨텍스트 창에 로드됩니다.
이는 claude.md와 근본적으로 다릅니다. claude.md의 콘텐츠는 사용자가 무엇을 하든 모든 대화에 로드됩니다. Skill은 필요할 때만 로드됩니다. PR 리뷰 체크리스트는 디버깅 중에는 컨텍스트에 있을 필요가 없으며, 실제로 리뷰를 요청할 때만 나타납니다.
그렇다면 Skill은 언제 사용해야 할까요? Claude에게 같은 내용을 반복해서 설명하고 있다면, 그때가 바로 Skill을 개발해야 할 때입니다.
처음부터 첫 번째 Skill 만들기
Skill을 만드는 데는 디렉토리 생성과 파일 작성, 단 두 단계만 필요합니다.
1단계: ~/.claude/skills/ 아래에 Skill 이름으로 디렉토리를 생성합니다. 여기에 배치하면 개인 수준의 Skill이 되어 모든 프로젝트에서 사용할 수 있습니다.
2단계: 디렉토리 안에 SKILL.md 파일을 생성합니다. 파일은 세 개의 대시로 구분된 두 부분으로 나뉩니다. 상단 부분은 name과 description을 포함하는 YAML 메타데이터입니다. 하단 부분에는 Claude가 따라야 할 구체적인 지침이 포함됩니다.
Claude Code가 시작되면 엔터프라이즈 경로, 개인 Skills 디렉토리, 프로젝트 Skills 디렉토리, 설치된 플러그인의 네 가지 위치에서 Skills를 스캔합니다. 각 Skill의 이름과 설명만 로드할 뿐, 전체 콘텐츠는 로드하지 않습니다.
사용자가 요청을 보내면, Claude는 요청을 모든 Skill 설명과 비교합니다. 의도가 일치하면 먼저 사용자에게 Skill을 로드할지 확인을 요청합니다. 확인 후에야 전체 파일을 읽고 지침을 실행합니다. 이 확인 단계를 통해 사용자는 Claude가 어떤 컨텍스트를 사용하고 있는지 항상 인지할 수 있습니다.
동일한 이름의 Skills가 존재하는 경우, 우선순위는 높은 순서대로 엔터프라이즈 수준(managed-settings.json), 개인 수준(~/.claude/skills), 프로젝트 수준(project/.claude/skills), 플러그인 수준(project/.claude-plugins/skills)입니다.
즉, 회사는 엔터프라이즈 수준의 Skills를 통해 표준을 강제할 수 있으며, 개인은 다른 이름의 Skills를 통해 맞춤 설정할 수 있습니다. 회사에 엔터프라이즈 코드 리뷰 Skill이 있다면, front-end-pr-review라는 개인 Skill을 만들어 덮어쓰지 않고 보완할 수 있습니다.
고급 설정: 메타데이터 필드와 점진적 공개
기본 Skills에는 name과 description만 필요하지만, 몇 가지 고급 설정을 통해 Skills를 더욱 강력하게 만들 수 있습니다.
allowed-tools 필드는 Skill이 활성화되었을 때 Claude가 사용할 수 있는 도구를 제한할 수 있습니다. 예를 들어, 읽기 전용 분석 Skill이 있다면 편집, 쓰기, Bash 명령을 금지할 수 있습니다. 이 필드를 생략하면 Skill은 제한을 두지 않으며, Claude는 일반 권한 모델을 사용합니다.
model 필드는 사용할 Claude 모델 버전을 지정할 수 있습니다.
description을 작성하는 방식은 Skill이 올바르게 트리거될 수 있는지 직접적으로 결정합니다. 좋은 설명은 두 가지 질문에 답해야 합니다. 이 Skill은 무엇을 하는가? Claude는 언제 이것을 사용해야 하는가? Skill이 트리거되지 않는다면, 요청 문구와 일치하는 키워드를 더 추가하세요.
가장 중요한 고급 개념은 점진적 공개입니다. Skills는 대화와 컨텍스트 창을 공유합니다. 모든 것을 20,000줄짜리 SKILL.md에 집어넣으면 엄청난 컨텍스트 공간을 소모하게 됩니다.
올바른 접근 방식은 다음과 같습니다. 필수 지침은 SKILL.md에 넣고, 상세 참고 자료는 별도 파일에 넣어 Claude가 필요할 때만 읽도록 합니다. 권장되는 디렉토리 구조는 다음과 같습니다. scripts 폴더에는 실행 가능한 코드, references에는 참고 문서, resources에는 이미지 및 템플릿과 같은 데이터 파일을 넣습니다. SKILL.md에서 링크를 사용하여 이러한 파일을 참조하세요.
핵심 규칙: SKILL.md는 500줄을 넘지 않아야 합니다. 넘는다면 분할해야 합니다. 스크립트는 컨텍스트에 내용을 로드하지 않고 직접 실행할 수 있습니다. 출력만 토큰을 소비합니다. 따라서 Claude에게 스크립트를 읽으라고 말하지 말고 실행하라고 지시하세요. 이는 환경 검증 및 데이터 변환에 특히 유용하며, 테스트된 스크립트 코드가 즉석 생성보다 더 안정적입니다.
Skills와 다른 Claude Code 기능의 차이점
Skills vs. claude.md: claude.md는 항상 모든 대화에 로드되어 항상 적용되는 프로젝트 표준 및 규칙(예: "이 프로젝트는 TypeScript strict mode를 사용합니다")을 위한 것입니다. Skills는 필요에 따라 로드되며, Claude가 요청을 일치시킬 때만 활성화됩니다.
Skills vs. Sub Agents: Skills는 현재 대화에 지식을 추가합니다. 활성화되면 지침이 기존 컨텍스트에 추가됩니다. Sub Agents는 독립적인 컨텍스트에서 실행되어 작업을 완료하고 결과를 별도로 제출하며, 메인 대화와 완전히 분리됩니다.
Skills vs. Hooks: Hooks는 이벤트 기반입니다. 파일이 저장될 때마다 Claude가 Linter를 실행하는 것과 같은 특정 이벤트가 발생할 때 트리거됩니다. Skills는 요청 기반이며, 사용자가 묻는 질문에 따라 활성화됩니다.
Skills vs. MCP: MCP는 외부 도구 연결을 제공하여 Claude가 Gmail이나 Notion과 같은 서비스를 호출할 수 있게 합니다. Skills는 지식과 워크플로우를 제공하여 Claude가 해당 도구를 사용하여 특정 작업을 완료하는 방법을 알려줍니다.
한 문장으로 요약하면 다음과 같습니다. claude.md는 항상 켜져 있는 지침, Skills는 자동 일치되는 전문 지식, Sub Agents는 격리된 컨텍스트에서 위임된 작업 실행, Hooks는 이벤트에 응답, MCP는 외부 도구 연결을 담당합니다. 이들은 함께 사용할 수 있습니다.
Skills 공유: 개인에서 팀, 조직으로
Skills의 가치는 공유에 있습니다. 혼자만 사용하는 PR 리뷰 Skill도 도움이 되지만, 팀이 공유하는 Skill은 코드 리뷰를 표준화하고 일관된 경험을 제공할 수 있습니다.
세 가지 공유 방법이 있습니다.
첫 번째는 프로젝트 디렉토리입니다. Skill을 코드 저장소의 .claude/skills 디렉토리에 커밋합니다. 저장소를 클론하는 모든 사람은 추가 설치 없이 자동으로 이러한 Skills를 받게 됩니다. 다음 풀에서 업데이트를 받습니다. 이는 팀 코딩 표준 및 프로젝트별 워크플로우에 적합합니다.
두 번째는 플러그인입니다. 플러그인은 Skills를 프로젝트 간에 배포하는 방법으로 생각할 수 있습니다. 앱 스토어에 업로드되면 다른 사용자가 다운로드하여 설치할 수 있습니다. Skill이 일반적이고 프로젝트별로 특화되지 않은 경우, 커뮤니티 구성원에게 가장 좋은 선택입니다.
세 번째는 엔터프라이즈 배포입니다. 관리자가 관리 설정을 통해 전체 조직에 Skills를 푸시합니다. 엔터프라이즈 수준의 Skills는 가장 높은 우선순위를 가지며 동일한 이름의 개인 및 프로젝트 Skills를 덮어씁니다. 이는 필수 표준, 보안 요구 사항 및 규정 준수 워크플로우에 사용됩니다.
중요한 참고 사항: Sub Agents는 사용자의 Skills를 자동으로 상속하지 않습니다. 작업을 하위 에이전트에 위임하면 새로운 컨텍스트로 시작합니다. 내장 에이전트(Explorer, Plan, Verify)는 Skills에 전혀 액세스할 수 없습니다. 사용자가 정의한 사용자 정의 하위 에이전트만 사용할 수 있으며, agent.md에 명시적으로 나열되어야 합니다.
Skills를 사용하는 사용자 정의 하위 에이전트를 만들려면 .claude/agents 디렉토리에 agent.md 파일을 만들고 필요한 Skill 이름을 나열하는 skills 필드를 추가하세요. 하위 에이전트의 목표와 항상 관련된 Skills만 나열하세요. 이러한 Skills는 하위 에이전트가 시작될 때 로드됩니다.
문제 해결 가이드: Skills 실패의 여섯 가지 이유와 해결 방법
Skill 문제는 일반적으로 여섯 가지 범주로 나뉩니다.
- Skill이 트리거되지 않음: 거의 항상
description이 잘못 작성되었기 때문입니다. Claude는 의미적 일치를 사용합니다. 사용자의 요청이 설명의 의미와 일치해야 합니다. 겹치는 부분이 충분하지 않으면 일치하지 않습니다. 해결 방법: 설명을 요청 문구와 비교하고 사용자가 실제로 사용하는 트리거 문구(예: "분석해줘", "왜 느리지", "속도 높여줘")를 추가하세요.
- Skill 로드 실패: 경로와 파일 이름을 확인하세요.
SKILL.md는 skills 루트에 직접 있지 않고 이름이 지정된 디렉토리 안에 있어야 합니다. 파일 이름은 정확히 대문자로SKILL.md여야 합니다.claude --debug를 실행하여 로드 오류를 확인하세요.
- Claude가 잘못된 Skill을 사용함: 설명이 너무 유사하여 Claude가 구분할 수 없는 여러 개의 Skills가 있다는 의미입니다. 해결 방법: 각 설명을 가능한 한 구체적으로 만들어 Claude가 언제 어떤 것을 사용해야 할지 결정하도록 도와주세요.
- 개인 Skill이 무시됨: 동일한 이름의 우선순위가 더 높은 Skill(예: 엔터프라이즈 Skill)이 덮어쓰고 있을 수 있습니다. 네 가지 우선순위 수준을 확인하세요. 해결 방법: Skill 이름을 더 고유하게 변경하세요.
- 플러그인이 설치되었지만 Skill이 표시되지 않음:
rm ~/.claude/plugins/cache로 캐시를 지우고 Claude Code를 다시 시작한 후 재설치하세요. 그래도 작동하지 않으면 플러그인의 디렉토리 구조가 잘못되었을 수 있습니다. 유효성 검사 도구skills-ref validate를 사용하여 확인하세요.
- Skill이 로드되었지만 실행 중 실패함: Skill이 외부 패키지를 사용하는 경우, 해당 패키지가 설치되었는지 확인하세요. Skill 설명에 종속성 정보를 추가하세요.
Anthropic은 또한 Skill의 파일 구조와 YAML 구문이 올바른지 확인하는 skills-ref라는 유효성 검사 도구를 제공합니다. 가장 빠른 방법은 uv를 통해 설치하는 것이 좋습니다.
