AI/Claude Code Doc(공식문서) 번역본

Claude Code 공식문서 리뷰-Build with Claude Code[4] : Agent Skills

안녕하세요! 갓대희입니다.

Claude Code Docs 공식 문서 >> Build with Claude Code 섹션의 내용 중 [Agent Skills]를 살펴 보려고 합니다.

https://code.claude.com/docs/en/skills

Agent Skills - Claude Code Docs

Create, manage, and share Skills to extend Claude's capabilities in Claude Code.

code.claude.com

이 카테고리의 글은 편하게 공식 문서 위주의 내용을 눈으로 쭉 살펴 보고 넘어가는 목적을 갖고 시작 하게 되었습니다.

저도 초심으로 돌아가 기초적읜 글을 살펴보다보니, 지금와서 클로드에서 강조 하고자 하는 원칙이 어떤건지 되돌아볼 수 있는 계기가 되기도 하는 것 같아, 다른 분들도 꼭 한번 눈으로라도 이해 하고 넘어가는것이 좋다고 생각하여 공식 문서의 내용을 억지로 리뷰해보게 되었습니다.

안녕하세요! 갓대희입니다.

Claude Code Docs 공식 문서 >> Build with Claude Code 섹션의 내용 중 [Agent Skills]를 살펴 보려고 합니다.

https://code.claude.com/docs/en/skills

Agent Skills - Claude Code Docs

Create, manage, and share Skills to extend Claude's capabilities in Claude Code.

code.claude.com

이 카테고리의 글은 편하게 공식 문서 위주의 내용을 눈으로 쭉 살펴 보고 넘어가는 목적을 갖고 시작 하게 되었습니다.

30초 요약

1. 스킬 = 지식

Claude에게 언제, 어떻게
행동할지 가르침

2. 자동 활성화

Claude가 자율적으로
언제 사용할지 결정

3. SKILL.md

마크다운 파일 하나로
스킬 완성

Quick Start: mkdir -p ~/.claude/skills/my-skill && touch ~/.claude/skills/my-skill/SKILL.md

에이전트 스킬 (Agent Skills)

정의: Claude Code에서 Claude의 기능을 확장하는 모듈형 기능
구성: SKILL.md 파일 + 선택적 지원 파일(스크립트, 템플릿)
핵심 특징: 모델 호출형(model-invoked) - Claude가 언제 사용할지 자율적으로 결정
원본: code.claude.com/docs/en/skills

개요 (Overview)

에이전트 스킬은 Claude Code에서 Claude의 기능을 확장하는 모듈형 기능이다. SKILL.md 파일에 지침이 담기고, 스크립트나 템플릿 같은 선택적 지원 파일이 함께할 수 있다.

핵심 개념
슬래시 명령은 "이 작업을 해줘"라고 직접 요청하는 것이고, 스킬은 "이런 상황에서 이렇게 행동해"라고 Claude에게 가르치는 것이다. Claude가 description을 보고 언제 사용할지 자율적으로 판단한다.

스킬 우선순위

동일한 이름의 스킬이 여러 곳에 있을 때, 다음 우선순위가 적용된다:

Enterprise

조직 전체

Personal

~/.claude/skills/

Project

.claude/skills/

Plugin

플러그인 내

위치	경로	범위	우선순위
Enterprise	[플랫폼별 지정]	조직 전체	최고
Personal	`~/.claude/skills/`	모든 프로젝트	높음
Project	`.claude/skills/`	현재 저장소	중간
Plugin	플러그인 내 `skills/`	플러그인 설치 사용자	낮음

스킬 만들기 (Creating Skills)

디렉토리 구조

스킬 저장 위치

# 개인 스킬 (모든 프로젝트에서 사용)
~/.claude/skills/
   └── my-skill/
       └── SKILL.md

# 프로젝트 스킬 (git 커밋, 팀 공유)
.claude/skills/
   └── team-skill/
       └── SKILL.md

# 플러그인 스킬 (플러그인에 번들)
my-plugin/
   ├── .claude-plugin/
   │   └── plugin.json
   └── skills/
       └── plugin-skill/
           └── SKILL.md

SKILL.md 형식

---
name: your-skill-name
description: 이 스킬이 무엇을 하고 언제 사용해야 하는지에 대한 간단한 설명
---

# Your Skill Name

## Instructions
Claude에게 명확한 단계별 가이드를 제공한다.

## Examples
이 스킬 사용의 구체적인 예시를 보여준다.

필드 요구사항

필수 필드:

필드	타입	제약조건	설명
`name`	string	소문자, 숫자, 하이픈만 최대 64자	스킬 식별자 (디렉토리명과 일치 권장)
`description`	string	최대 1024자	핵심! Claude가 이걸 보고 스킬 사용 여부 결정

선택 필드:

필드	타입	기본값	설명
`allowed-tools`	string (쉼표 구분)	제한 없음	스킬 활성화 시 사용 가능한 도구 제한 예: `Read, Grep, Glob`
`model`	string	대화의 모델	스킬 활성화 시 사용할 Claude 모델 예: `claude-sonnet-4-20250514`

model 필드 사용 예시

---
name: complex-analysis
description: 깊은 코드 분석을 수행. 복잡한 아키텍처 리뷰나 보안 분석 시 사용.
model: claude-sonnet-4-20250514
---

복잡한 분석 작업에는 더 강력한 모델을, 간단한 작업에는 빠른 모델을 지정할 수 있다.

description 작성 핵심 (Claude가 스킬을 찾는 방법)

Claude는 description을 보고 스킬 사용 여부를 결정한다. 따라서:

무엇을 하는지: "PDF 파일에서 텍스트와 표를 추출"
언제 사용하는지: "PDF 파일, 양식, 문서 추출 작업 시 사용"
트리거 키워드: 사용자가 말할 법한 단어 포함

지원 파일 (Supporting Files)

my-skill/
├── SKILL.md          # 필수 - 개요와 빠른 시작
├── reference.md      # 선택 - 상세 API 레퍼런스
├── examples.md       # 선택 - 추가 예제
├── scripts/
│   └── helper.py     # 선택 - 유틸리티 스크립트
└── templates/
    └── template.txt  # 선택 - 템플릿 파일

SKILL.md에서 파일 참조:

고급 사용법은 [reference.md](reference.md)를 참조하세요.

헬퍼 스크립트 실행:
```bash
python scripts/helper.py input.txt
```

권장사항
SKILL.md는 500줄 이하로 유지하는 것이 좋다. 복잡한 내용은 별도 파일로 분리하고 참조한다. 스크립트는 실행만 되고 코드가 컨텍스트에 로드되지 않아 토큰을 절약할 수 있다.

도구 접근 제한 (Restricting Tool Access)

allowed-tools 프론트매터를 사용하여 Claude의 도구 접근을 제한한다:

---
name: safe-file-reader
description: 변경 없이 파일을 읽는다. 읽기 전용 파일 접근이 필요할 때 사용.
allowed-tools: Read, Grep, Glob
---

지정하면 Claude는 권한 요청 없이 해당 도구만 사용할 수 있다. 다음 경우에 유용하다:

읽기 전용 스킬
보안에 민감한 워크플로우
제한된 범위의 기능

Bash 명령 필터링

특정 명령만 허용하도록 세밀하게 제어할 수 있다:

---
name: python-only-runner
description: Python 스크립트만 실행. 안전한 Python 실행 환경이 필요할 때 사용.
allowed-tools: Read, Bash(python:*), Glob
---

위 설정은 Read, Glob은 자유롭게, Bash는 python 명령만 허용한다.

참고
allowed-tools는 Claude Code의 스킬에서만 지원되며, 플러그인에서는 지원되지 않는다.

스킬 관리 (Managing Skills)

사용 가능한 스킬 보기

Claude에게 직접 물어본다:

What Skills are available?

또는 파일시스템을 통해 나열:

# 개인 스킬
ls ~/.claude/skills/

# 프로젝트 스킬
ls .claude/skills/

# 특정 스킬 보기
cat ~/.claude/skills/my-skill/SKILL.md

스킬 테스트

설명(description)과 일치하는 질문을 한다. Claude는 관련이 있으면 자율적으로 사용하기로 결정한다.

# explaining-code 스킬 테스트
How does this code work?

# commit-helper 스킬 테스트
Generate a commit message for my staged changes

# pdf-processing 스킬 테스트
이 PDF에서 텍스트를 추출해줄 수 있어?

디버그 모드로 스킬 로딩 확인:

claude --debug

스킬 업데이트

SKILL.md를 직접 편집한다. 변경사항은 Claude Code 재시작 후 적용된다.

스킬 제거

# 개인 스킬 제거
rm -rf ~/.claude/skills/my-skill

# 프로젝트 스킬 제거
rm -rf .claude/skills/my-skill
git commit -m "Remove unused skill"

스킬 공유 (Sharing Skills)

프로젝트 저장소를 통해

스킬 생성

.claude/skills/에 추가

→

Git 커밋

git add & commit

→

팀원 Pull

자동으로 스킬 사용 가능

# 1단계: 프로젝트에 스킬 추가
mkdir -p .claude/skills/team-skill
# SKILL.md 생성...

# 2단계: git에 커밋
git add .claude/skills/
git commit -m "Add team skill for PDF processing"
git push

# 3단계: 팀원이 풀
git pull
claude  # 이제 스킬 사용 가능!

플러그인을 통해

skills/ 디렉토리에 스킬이 포함된 플러그인 생성
마켓플레이스에 플러그인 게시
팀원이 플러그인 설치: /plugin install plugin-name@marketplace

Enterprise를 통해

조직 전체에 스킬을 배포하려면 managed settings를 사용한다.

모범 사례 (Best Practices)

하나의 목적에 집중

O 좋은 스킬

하나의 기능에 집중
"PDF 양식 채우기"
"Git 커밋 메시지 생성"
"Excel 데이터 분석"

X 나쁜 스킬

너무 광범위함
"문서 처리"
"데이터 도구"
"개발 헬퍼"

명확한 설명 작성

포함해야 할 내용:

스킬이 무엇을 하는지
Claude가 언제 사용해야 하는지
특정 트리거 키워드

버전 문서화

# My Skill

## 버전 이력
- v2.0.0 (2025-10-01): API 호환성 깨지는 변경
- v1.1.0 (2025-09-15): 새 기능 추가
- v1.0.0 (2025-09-01): 초기 릴리스

팀과 테스트

확인 사항:

예상대로 스킬이 활성화되는지
지침이 명확한지
예제가 엣지 케이스를 다루는지

예제 (Examples)

1. 코드 설명 스킬 (explaining-code)

~/.claude/skills/explaining-code/SKILL.md:

---
name: explaining-code
description: 시각적 다이어그램과 비유로 코드를 설명. 코드 동작 설명, 코드베이스 교육, "이게 어떻게 동작해?" 질문 시 사용.
---

# 코드 설명하기

코드를 설명할 때 항상 다음을 포함한다:

1. **비유로 시작**: 코드를 일상생활의 무언가에 비유
2. **다이어그램 그리기**: ASCII 아트로 흐름, 구조, 관계를 표현
3. **단계별 설명**: 무슨 일이 일어나는지 순서대로 설명
4. **주의점 강조**: 흔한 실수나 오해는 무엇인지

설명은 대화체로 유지한다. 복잡한 개념은 여러 비유를 사용한다.

사용 예시
사용자: "이 함수가 어떻게 동작해?"
→ Claude가 자동으로 explaining-code 스킬을 활성화하여 비유와 다이어그램으로 설명

2. 커밋 메시지 생성 (commit-helper)

~/.claude/skills/generating-commit-messages/SKILL.md:

---
name: generating-commit-messages
description: git diff에서 명확한 커밋 메시지를 생성. 커밋 메시지 작성이나 스테이징된 변경사항 검토 시 사용.
---

# 커밋 메시지 생성

## 지침

1. `git diff --staged`를 실행하여 변경사항 확인
2. 다음을 포함한 커밋 메시지 제안:
   - 50자 이하의 요약
   - 상세 설명
   - 영향받는 컴포넌트

## 형식
```
feat: 새 기능
fix: 버그 수정
docs: 문서 변경
refactor: 리팩토링
```

## 모범 사례

- 현재 시제 사용
- 무엇을, 왜를 설명하고 어떻게는 제외

3. 코드 리뷰어 (도구 제한 적용)

.claude/skills/code-reviewer/SKILL.md:

---
name: code-reviewer
description: 모범 사례와 잠재적 문제에 대해 코드를 검토. 코드 리뷰, PR 확인, 코드 품질 분석 시 사용.
allowed-tools: Read, Grep, Glob
---

# 코드 리뷰어

## 검토 체크리스트

1. 코드 구성과 구조
2. 에러 처리
3. 성능 고려사항
4. 보안 우려사항
5. 테스트 커버리지

## 지침

1. Read 도구로 파일 읽기
2. Grep으로 패턴 검색
3. Glob으로 관련 파일 찾기
4. 상세한 피드백 제공

allowed-tools 효과

이 스킬이 활성화되면 Claude는 Read, Grep, Glob만 사용 가능하다. 파일 수정이나 명령 실행은 불가능하므로 안전한 읽기 전용 리뷰가 보장된다.

4. PDF 처리 (다중 파일 스킬)

구조:

pdf-processing/
├── SKILL.md           # 개요와 빠른 시작
├── FORMS.md           # 양식 필드 매핑
├── REFERENCE.md       # API 상세
└── scripts/
    ├── fill_form.py
    └── validate.py

pdf-processing/SKILL.md:

---
name: pdf-processing
description: 텍스트 추출, 양식 채우기, PDF 병합. PDF 파일, 양식, 문서 추출 작업 시 사용. pypdf와 pdfplumber 패키지 필요.
allowed-tools: Read, Bash(python:*)
---

# PDF 처리

## 빠른 시작

텍스트 추출:
```python
import pdfplumber
with pdfplumber.open("doc.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

양식 채우기는 [FORMS.md](FORMS.md) 참조.
상세 API 레퍼런스는 [REFERENCE.md](REFERENCE.md) 참조.

## 유틸리티 스크립트

입력 파일 검증:
```bash
python scripts/validate.py input.pdf
```

## 요구사항

```bash
pip install pypdf pdfplumber
```

워크플로우 시나리오 예시

시나리오 1 커밋 메시지 자동 생성

스킬 없이

매번 "커밋 메시지 작성해줘"
형식이 매번 달라짐
컨벤션 기억해야 함

→

스킬 사용

"변경사항 커밋하자"
Claude가 자동으로 스킬 활성화
일관된 형식 보장

시나리오 2 팀 코딩 컨벤션 자동 적용

스킬 없이

새 팀원마다 컨벤션 설명
문서 찾아다니기
일관성 없는 코드

→

스킬 사용

.claude/skills/에 컨벤션 정의
git pull만 하면 자동 적용
팀 전체 일관성 유지

고급 기능 (Advanced Features)

Subagent 통합

커스텀 서브에이전트에 특정 스킬을 연결할 수 있다:

# .claude/agents/AGENT.md
---
name: security-reviewer
description: 보안 관점에서 코드를 검토
skills: security-check, code-reviewer
---

# Security Reviewer Agent

이 에이전트는 security-check과 code-reviewer 스킬을 사용하여
보안 취약점을 분석합니다.

참고
내장 에이전트(Explore, Plan, Verify)와 Task 도구는 스킬을 상속받지 않는다. 커스텀 에이전트에만 스킬을 연결할 수 있다.

ex)

Progressive Disclosure (점진적 공개)

스크립트는 실행만 되고 코드가 컨텍스트에 로드되지 않는다. 즉, 토큰을 절약할 수 있다:

양식을 검증하려면 다음을 실행:
```bash
python scripts/validate_form.py input.pdf
```

Claude가 스크립트를 실행하면 출력만 토큰을 소비하고, 스크립트 코드 자체는 소비하지 않는다.

문제 해결 (Troubleshooting)

Claude가 내 스킬을 사용하지 않음

가장 흔한 원인: 모호한 description

X	`description: 문서 처리를 돕는다`
O	`description: PDF 파일에서 텍스트와 표를 추출하고, 양식을 채우고, 문서를 병합한다. PDF 파일, 양식, 문서 추출 작업 시 사용.`

확인 방법:

# 1. 파일 경로 확인
ls ~/.claude/skills/my-skill/SKILL.md

# 2. YAML 문법 확인
cat SKILL.md | head -n 10

# 3. 디버그 모드로 확인
claude --debug

스킬이 로드되지 않음

체크리스트:

파일 이름이 정확히 SKILL.md인가? (대소문자 구분)
YAML 프론트매터가 ---로 1번 줄에서 시작하는가?
들여쓰기가 올바른가? (스페이스 vs 탭 혼용 금지)
경로가 맞는가?
- 개인: ~/.claude/skills/my-skill/SKILL.md
- 프로젝트: .claude/skills/my-skill/SKILL.md

여러 스킬이 충돌함

설명에 구별되는 트리거 용어를 사용한다:

# 스킬 1 - 영업 분석
description: Excel 파일과 CRM 내보내기에서 영업 데이터를 분석.
            영업 보고서, 파이프라인 분석, 수익 추적에 사용.

# 스킬 2 - 시스템 분석
description: 로그 파일과 시스템 메트릭 데이터를 분석.
            성능 모니터링, 디버깅, 시스템 진단에 사용.

YAML 문법 오류