Introduction to agent skills
시리즈 소개
스킬은 같은 설명을 반복하는 대신, Claude에게 한 번 가르쳐 두고 계속 활용하는 방법이자 도구입니다. 이 코스에서는 스킬(Skills)이 무엇인지, 그리고 CLAUDE.md, 훅(hooks), 서브에이전트(subagents) 같은 Claude Code의 다른 커스터마이징 옵션과 스킬이 어떻게 다른지 알아봅니다.
이후 나만의 스킬을 직접 만들어 보며, SKILL.md의 프론트매터(frontmatter)를 작성해 프롬프트와 매칭되는 스킬이 안정적으로 트리거(자동 실행)되도록 하는 설계법을 알아봅니다. 또한 컨텍스트 윈도우를 효율적으로 유지하기 위해 점진적 공개(progressive disclosure) 방식으로 스킬 디렉터리를 구성하는 방법을 익힙니다. 더 나아가 allowed-tools로 도구 접근을 제한하거나, 컨텍스트를 소비하지 않고 실행되는 스크립트를 사용하는 등 고급 설정 옵션도 살펴봅니다.
나만 쓰는 개별 스킬을 만드는 것을 넘어, 스킬을 저장소에 커밋해 팀과 공유하는 방법, 플러그인을 통해 외부로 스킬을 배포하는 방법, 엔터프라이즈 관리 설정을 통해 조직 전체에 배포하는 방법도 배웁니다.
또한 스킬을 커스텀 서브에이전트에 연결해 별도로 전문 작업을 위임하는 방법을 알아보고, 스킬이 트리거되지 않는 문제부터 우선순위 충돌, 런타임 오류까지 진단하는 완전한 트러블슈팅 가이드를 따라가 봅니다. 코스를 마치면 Claude를 일관되게 유지하고, 컨텍스트 효율을 높이며, 팀의 표준에 맞게 정렬된 스킬 기반 워크플로를 구축하는 데 필요한 지식을 갖추게 됩니다.
원본 강의는 Anthropic의 Introduction to agent skills(Skilljar)입니다. 번역에 그치지 않고 원본 강의 공개 이후 추가된 규칙 파일(rules), 하위 디렉터리 CLAUDE.md 같은 새 기능 비교를 모던웹연구소가 보강해 함께 다룹니다.
자주 묻는 질문
Claude Code 스킬(Skills)이란 무엇인가요?
스킬은 Claude Code에 특정 작업의 절차와 기준을 한 번 가르쳐 두고 재사용하는 마크다운 기반 커스터마이징 기능입니다. 사용자의 요청이 스킬의 description과 매칭되면 자동으로 활성화되므로 같은 지시를 반복해 입력할 필요가 없어집니다.
스킬은 어디에 저장하나요?
개인 스킬은 홈 디렉터리의 ~/.claude/skills에, 프로젝트 스킬은 저장소 루트의 .claude/skills에 둡니다. 각 스킬은 폴더 하나와 그 안의 SKILL.md 파일로 구성되며 폴더 이름이 곧 스킬 이름이 됩니다.
스킬과 CLAUDE.md는 어떻게 다른가요?
CLAUDE.md는 모든 대화에 항상 로드되므로 언제나 적용될 규칙에 적합합니다. 스킬은 요청과 매칭될 때만 로드되므로 작업별 절차와 전문 지식에 적합합니다. 컨텍스트 소비 방식이 달라 두 기능의 역할을 나눠 쓰는 것이 좋습니다.
스킬이 트리거되지 않을 때는 어떻게 하나요?
먼저 Skills Validator를 실행해 구조 오류를 확인하고, 실제 요청에 쓰는 표현과 키워드를 description에 보강합니다. 파일명이 정확히 SKILL.md인지, 스킬이 이름 있는 디렉터리 안에 있는지, 새 스킬을 만든 뒤 세션을 재시작했는지도 함께 점검합니다.
allowed-tools는 왜 설정하나요?
allowed-tools는 스킬이 활성화됐을 때 Claude가 쓸 수 있는 도구를 제한하는 프론트매터 필드입니다. 읽기 전용 작업이나 보안이 민감한 작업에서 의도하지 않은 파일 수정과 명령 실행을 막는 안전장치로 씁니다.
점진적 공개(progressive disclosure)란 무엇인가요?
스킬의 모든 내용을 SKILL.md 하나에 담지 않고 참고 문서를 별도 파일로 분리해 필요한 시점에만 로드하게 하는 구성 방식입니다. 컨텍스트 창을 목차와 부록처럼 운용해 토큰을 절약하면서 정확도를 유지합니다.
팀과 스킬을 공유하려면 어떻게 하나요?
저장소의 .claude/skills에 커밋하면 클론하는 모든 팀원이 같은 스킬을 쓰게 됩니다. 여러 저장소나 팀 밖으로 배포하려면 플러그인의 skills 디렉터리에 담아 마켓플레이스로 배포하고, 조직 전체에 강제 적용하려면 엔터프라이즈 관리 설정을 사용합니다.
규칙 파일(rules)과 스킬 중 무엇을 써야 하나요?
트리거 기준으로 고르면 됩니다. 사용자의 요청에 반응해야 하는 절차라면 스킬이 맞고, 특정 경로의 파일을 다룰 때마다 적용될 규칙이라면 .claude/rules/의 경로 지정 규칙 파일이 맞습니다. 규칙 파일 비교는 원본 강의 이후 추가된 기능이라 모던웹연구소가 강의에 보강한 내용입니다.