[AI] 앤트로픽(Anthropic)이 알려주는 좋은 클로드 코드 스킬(Claude Code Skill)

앤트로픽은 좋은 스킬을 작성하는 방법에 대한 내용을 33쪽의 분량에 걸친 PDF 자료로 제공하고 있다. 보다 상세하고 구체적인 내용을 원한다면, 해당 PDF 파일을 참고하기를 권장한다.

 

 

 

1. 앤트로픽(Anthropic)이 알려주는 좋은 클로드 코드 스킬(Claude Code Skill)

---

[ Skill의 개념과 작성 예시 ]

Skill의 개념과 범주

Skill은 Claude의 기능을 확장하는 기술로, 일회성 프롬프트가 아닌, 반복 사용 가능한 워크플로 자산이자 지식의 저장소이다. 따라서 반복 가능하고 구조화된 작업에서 가장 유용하다. Skill은 하나의 폴더 단위로 존재하며, 다음과 같이 구성된다.

• 필수 구성:
  • SKILL.md: YAML frontmatter와 Markdown 지침을 포함한 핵심 파일
• 선택 구성:
  • scripts/: Python, Bash 등 실행 코드
  • references/: 필요 시 참조되는 문서와 가이드
  • assets/: 출력물에 사용되는 템플릿, 리소스

 

 

SKILL.md 파일에 지침을 작성하면, Claude가 이를 도구 모음에 추가한다. 그러면 Claude는 관련 상황에서 스킬을 자동으로 사용하며, 설정에 따라 사용자가 /skill-name으로 직접 호출할 수도 있다. Claude Code가 제공하는 Skill은 여러 AI 도구에서 통용되는 Agent Skills 오픈 표준을 따르며, 호출 제어와 서브에이전트 실행, 동적 컨텍스트 주입 등과 같은 추가 기능을 제공한다. 참고로 커스텀 커맨드는 Claude의 초기 기술로, 프론트매터 자동 로딩 등이 추가되며 스킬로 통합되었다.

 

Skill에는 크게 4가지 범주가 존재하며, 다음과 같이 구분할 수 있다. 

위치	경로	적용 범위
Enterprise	See managed settings	Organization에 속한 모든 사용자
Personal	~/.claude/skills/<skill-name>/SKILL.md	모든 프로젝트
Project	.claude/skills/<skill-name>/SKILL.md	현재의 프로젝트만
Plugin	<plugin>/skills/<skill-name>/SKILL.md	플러그인이 활성화되었을 경우에만

 

 

동일한 이름의 Skill 이 존재할 경우에는 높은 우선순위(enterprise > personal > project)의 구역이 우선 채택되며, plugin의 Skill 은 plugin-name:skill-name에 해당하는 namespace를 갖기 때문에, 충돌이 나지 않는다. Personal 또는 Project Skill은 자동 로드되며, 라이브 변경 감지도 되므로 세션을 재시작하지 않고도 수정할 수 있다.

 

 

 

Skill의 Frontmatters 항목들과 작성 예시

Skill 내용이 작성되는 SKILL.md는 “YAML Frontmatter + Markdown 본문” 구조를 따른다. Frontmatter에는 메타데이터를, 본문에는 실제 작업 절차와 기준을 적는다. Frontmatter에는 다음의 항목들이 존재한다.

필드명	필수 여부	설명
name	No	스킬 이름, 없으면 디렉터리명을 사용함. 소문자/숫자/하이픈만 허용(최대 64자)
description	Recommended	스킬이 무엇을 하고 언제 쓰는지에 대한 설명. Claude가 자동 적용 여부를 판단할 때 사용하며, 없으면 마크다운 첫 문단을 사용함
argument-hint	No	자동완성 시 기대 인자를 힌트로 표시. 예: [issue-number] 또는 [filename] [format]
disable-model-invocation	No	true면 Claude가 자동으로 로드/호출하지 않음. /name으로 수동 실행만. 기본값 false
user-invocable	No	false면 / 메뉴에서 숨김(사용자 직접 호출 불가). 백그라운드 지식용. 기본값 true
allowed-tools	No	스킬 활성 시 Claude가 추가 승인 없이 사용할 수 있는 도구
model	No	스킬 활성 시 사용할 모델
context	No	fork면 분리된 서브에이전트 컨텍스트에서 실행
agent	No	context: fork일 때 사용할 서브에이전트 타입
hooks	No	스킬 라이프사이클에 스코프된 훅. 형식은 Hooks in skills and agents 참고.

 

 

예를 들어 코드를 설명하는 explain-code Skill을 작성한다고 하면, ~/.claude/skills/explain-code/SKILL.md를 다음과 같이 작성해줄 수 있다. 스킬은 디렉토리 이름이 스킬 이름에 해당하며, SKILL.md가 그 내용을 채워준다.

---
name: explain-code
description: Explains code with visual diagrams and analogies. Use when explaining how code works, teaching about a codebase, or when the user asks "how does this work?"
---

When explaining code, always include:

1. **Start with an analogy**: Compare the code to something from everyday life
2. **Draw a diagram**: Use ASCII art to show the flow, structure, or relationships
3. **Walk through the code**: Explain step-by-step what happens
4. **Highlight a gotcha**: What's a common mistake or misconception?

Keep explanations conversational. For complex concepts, use multiple analogies.

 

 

만약 스킬에 파라미터가 필요하다면 다음과 같은 방식으로 전달할 수 있다.

변수명	설명
$ARGUMENTS	스킬 호출 시 전달된 모든 인자. 본문에 $ARGUMENTS가 없으면 ARGUMENTS: <value> 형태로 자동 추가됨.
$ARGUMENTS[N]	0부터 시작하는 인덱스로 특정 인자 접근. 예: 첫 인자는 $ARGUMENTS[0].
$N	$ARGUMENTS[N]의 축약형. 예: $0, $1.
${CLAUDE_SESSION_ID}	현재 세션 ID. 로그 파일 생성 등 세션 단위 작업에 유용.

 

 

 

[ Skill 작성 관련 고급 팁 ]

SKILL.md 안에서 Bash 명령어 사용하기

클로드에서 !를 가장 앞에 입력하면 Bash 모드로 전환이 된다.

 

 

스킬에도 Bash 모드를 활용할 수 있는데, 스킬에서는 각 !command는 전처리(preprocessing) 단계로, Claude가 어떤 내용도 보기 전에 즉시 실행된다. 따라서 ! 명령의 출력이 스킬 콘텐츠 안의 플레이스 홀더를 대체하며, Claude는 실제 Bash 실행 결과가 포함된, 완전히 렌더링된 프롬프트를 최종 결과물로 받는다.

---
name: pr-summary
description: Summarize changes in a pull request
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---

## Pull request context
- PR diff: !`gh pr diff`
- PR comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`

## Your task
Summarize this pull request...

 

 

예를 들어 위와같이 PR에 대한 요약본을 설명해주는 스킬이 있다고 하면, 위의 !로 시작되는 명령어는, 스킬이 실행되기 전에 실제 gh pr diff 등의 실행 결과로 치환되며 클로드에게 전달이 된다.

 

 

 

서브에이전트에서 Skill 실행하기

Frontmatter에 context: fork를 추가하면, 격리된 상태에서 스킬이 실행된다. 또한 이때 해당 스킬을 수행할 Agent 타입도 agent로 지정해줄 수 있다. context: fork가 설정되면 스킬의 내용 전체가 서브에이전트를 구동하는 프롬프트가 되며, 이 서브에이전트는 현재 대화 기록에 접근할 수 없이 분리된 상태에서 실행된다. 즉, 서브에이전트는 스킬을 실행하고 결과만 주고 끝나므로, 해당 기능은 명시적인 지시(작업)이 존재하는 스킬에서만 의미가 있다.

접근	시스템 프롬프트	작업	함께 불러와지는 내용들
context: fork가 있는 스킬	에이전트 타입(Explore, Plan 등)에서 옴	SKILL.md 내용	CLAUDE.md
skills 필드가 있는 서브에이전트	서브에이전트의 마크다운 본문	Claude의 위임 메시지	사전 로드된 스킬들 + CLAUDE.md

 

 

 

Skill의 트리거 조건 설정하기

뒤에서 설명하겠지만 스킬은 적당량이 유지되는 것이 중요하다. 따라서 어떠한 스킬을 클로드에게 항상 선택지 중 하나로 전달하는 것은 컨텍스트를 낭비하게 되므로, 사용자가 직접 트리거 하기만을 원하는 경우에는 disable-model-invocation와 user-invocable를 조정해주면 된다.

 

 

 

[ 좋은 Skill에 대하여 ]

좋은 Skill을 작성하는 과정

Skills 구축의 성패는 작성 단계 이전의 설계 품질에서 거의 결정된다고 한다. 잘 설계된 Skill은 구현이 단순해지고, 테스트와 유지보수 비용도 크게 줄게 되는데, 앤트로픽은 좋은 Skill을 작성하기 전에, 반드시 2~3개의 구체적인 사용 사례(use case) 를 정의할 것을 권장한다. 사용 사례는 추상적인 목적이 아니라, 실제 사용자가 말할 문장과 결과까지 포함해야 하며, 좋은 사용 사례는 다음의 요소들이 포함되어야 한다.

• 사용자가 달성하고자 하는 목표
• 사용자가 말할 법한 트리거 문장
• 내부적으로 수행해야 할 단계적 작업
• 사용되는 도구(Claude 기본 기능 또는 MCP)
• 최종 결과 상태

 

또한 앤트로픽은 테스트의 중요성 역시 강조하는데, 크게 3가지 핵심 테스트 영역을 구성하여 활용할 것을 권장한다.

• 트리거 테스트
  • 목적: 스킬이 적절한 상황에서만 자동 로드되는지 검증
  • ex) 표현이 바뀐 요청에서도 스킬이 트리거 되는지 검증함
• 기능 테스트
  • 목적: 스킬이 의도한 결과를 정확히 생성하는지 확인
  • ex) 출력 결과의 정확성, 엣지 케이스 대응 등
• 성능 비교 테스트
  • 목적: 스킬 사용 전후의 실질적 개선 효과 확인
  • ex) 메시지 왕복 횟수, 총 토큰 사용량 등

 

 

skill-creator를 활용한 Skill의 생성과 품질 평가 및 개선

이전 포스팅에서 설명하였듯, Skill Creator는 Anthropic(앤트로픽)이 기본으로 제공하는 도구 중 하나로, 다음의 주요 기능들을 제공한다.

• 자연어 설명 기반 스킬 초안 생성
• SKILL.md 형식과 frontmatter 자동 생성
• 트리거 과다/부족 위험 탐지
• 목적에 맞는 테스트 케이스 제안
• 실행 테스트나 정량 평가를 대신하지는 않음

 

 

Skill Creator는 스킬을 잘 만드는 방법에 대한 가이드와 템플릿을 제공한다. 에이전트에게 특정 도메인 지식 + 워크플로 + 도구 사용법을 넣어서 “일반 에이전트 → 전문 에이전트”로 바꿔주며, 생성한 스킬들을 평가할 수 있는 항목들도 포함하여 그 성능을 극대화시킨다. 스킬을 새롭게 생성하고, 기존에 존재하는 스킬들을 평가 및 개선하고자 할 때면 반드시 Skill Creator를 활용할 것을 권장한다.

 

 

 

적정량의 Skill의 수 유지하기

클로드는 “사용 가능한 스킬 목록”을 관리하기 위해 문자 예산(character budget)이라는 개념을 활용한다. 클로드는 각 스킬의 설명(description)들을 대화 컨텍스트에 같이 로드하는데, 문자 예산은 컨텍스트 윈도우의 2% 차지하며, 컨텍스트 윈도우가 너무 작을 경우를 대비해 최소 하한선으로 16000자가 지정되어 있다. 스킬이 많으면 문자 예산(character budget)을 초과하며 일부 스킬이 제외될 수 있기에, 적절한 양의 스킬과 스킬의 설명들로 관리가 필요하다.

 

 

 

Skill의 실행 순서와 description

앞서 설명하였듯 Skill은 프롬프트처럼 대화에 바로 주입되지 않고, name과 description 만이 시스템 프롬프트에 올라간다. 그리고 '단계별 공개'(progressive disclosure) 방식을 따라 처리된다.

1. 메타데이터(name + description)를 시스템 프롬프트에 상시 로딩함(Skill 하나당 약 100토큰)
2. 사용자 명령이 SKILL의 description에 부합하는 경우, Bash 도구로 SKILL.md 전문을 읽어들임
3. 처리를 하다가 scripts 와 references 폴더 파일이 필요해지면, 실제 참조 시점에 로딩함
4. 스크립트 실행 시 코드 자체는 맥락에 올라가지 않고 출력값만 소비함

 

 

그렇기 때문에 본문 내용(Body)에 자주 들어가는 “When to Use This Skill”은 이미 Skill 이 발동되고 읽히므로 낭비일 뿐이다.

컨텍스트 윈도우는 공공재이기 때문에, Skill은 대화 기록이나 시스템 프롬프트와 SKILL의 body가 함께 공존한다. 따라서 가급적 500줄 이하로 작성하고, 클로드가 이미 아는 내용은 작성할 필요가 없다. 또한 500줄보다 길어질 경우 상세 파일로 분리해야 하며, 2단계 이상의 중첩 참조는 지양해야 한다. 참조 파일이 길어질 경우, Claude가 head -100으로 일부만 읽을 수 있으므로 목차를 맨 위에 넣어야 한다.

 

 

 

검증 루프 작성하기

그 다음은 Skill의 성능과 정확도를 가장 끌어올릴 수 있는 기술로, 검증 루프를 작성하는 것이다. 실행 → 검증 → 수정 후에는 재검증 루프를 추가해주어 Claude가 문제를 재발하지 않도록 해야 한다. 이를 위해 체크리스트를 body 에 넣고 Claude에게 검증하라고 하면, Skill의 질을 극대화할 수 있다. 실제로 검증 루프에 대한 체감은 상당히 크기 때문에, 반드시 작성할 것이 권장된다.

 

 

 

[ Skill의 트리거에 대하여 ]

Skill 발동을 위한 훅

스킬이 잘 발동되지 않는 이유는, 클로드에 스킬 정보가 없는 것이 아니라, 그 지시를 제대로 읽지 못하기 때문이다. 이를 위해 스킬 트리거를 위한 Hook을 사용하면, 스킬의 호출률을 높일 수 있다. 이 동작은 Claude가 프롬프트를 보기 직전에 사용자의 입력을 가로채서, 스킬 추천을 메시지에 직접 덧붙이는 방식이다.

• ASIS:
  • 기능 구현 좀 도와줘
• TOBE:
  • 기능 구현 좀 도와줘CRITICAL SKILLS (REQUIRED): session-managementACTION: Use Skill tool BEFORE responding
  • RECOMMENDED SKILLS: git-commits
  • 
    --- SKILL ACTIVATION CHECK ---

 

 

 

앤트로픽은 좋은 스킬을 작성하는 방법에 대한 내용을 33쪽의 분량에 걸친 PDF 자료로 제공하고 있다. 보다 상세하고 구체적인 내용을 원한다면, 해당 PDF 파일을 참고하기를 권장한다.

 

 

 

참고 자료

• https://code.claude.com/docs/en/skills
• https://www.linkedin.com/posts/jyoung105_anthropic-이-공개한-skillmd-body-작성-규칙-5가지-activity-7428729561946722304-O3kE
• https://medium.com/coding-nexus/claude-code-skill-activation-hook-force-skills-to-load-every-time-no-memory-required-e2bdfba37656
• https://news.hada.io/topic?id=26328