Claude Code에서 Agent Skills 활용하기 - Public Skill부터 커스텀 n8n 워크플로우 생성까지
Claude Desktop에서 Skill을 활용하는 방법에 대해 이전 글에서 다루었다면, 이번에는 개발자들이 더 자주 사용하는 Claude Code 환경에서 Skill을 활용하는 방법을 상세히 알아보겠습니다. Claude Code는 터미널 기반의 에이전틱 코딩 도구로, 파일시스템에 직접 접근할 수 있어 Skill 활용 방식이 Claude Desktop과는 상당히 다릅니다. 이 글에서는 Anthropic이 제공하는 Public Skill의 설치부터 사용자가 직접 작성하는 커스텀 Skill, 그리고 n8n 워크플로우를 자연어로 생성하는 실전 예제까지 단계별로 안내해 드리겠습니다.
목 차
1. 들어가며: Claude Desktop vs Claude Code의 Skill 활용 차이
SKILL의 간단한 이해 | AI에서의 SOP라고 할 수 있어요.
표준 운영 절차(SOP, Standard Operating Procedure)는 업무의 일관성을 확보하기 위해 업무 프로세스를 문서로 정의한 것입니다. 특정 업무 상황에서 무엇을 해야 하는지 알 수 있도록 단계별 지침을 매뉴얼로 만든 것으로, 작업자들이 일관성 있고 효율적인 업무 처리를 할 수 있도록 도와줍니다.
SKILL(SOP)은 왜 필요할까요?
AI에게 작업을 요청할 때도 SOP와 같은 규칙을 미리 정의해 준다면, SOP를 통해서 얻을 수 있는 다양한 이점을 가져올 수 있습니다.
오류는 감소시키고, 생산성을 향상시켜요
우리가 사용하는 업무 자동화는 시스템과의 연결이 필수이기 때문에 , 한번 잘못 처리하면 이를 되돌리는데 많은 시간과 비용이 소요됩니다. 같은 업무를 다시 처리하다 보면 그다음 업무가 지연되어서 다른 전체의 업무가 예정보다 늦어지기 마련이죠.
SOP는 업무 중 일정한 기준과 절차를 준수할 수 있도록 보장해줍니다. 정해진 과정에 따라 업무를 수행하니, 자연스럽게 실수는 줄어들고 좋은 퀄리티의 결과를 낼 수 있습니다. 또한 모든 직원이 각자 무슨 일을 해야 할지 명확하게 알 수 있어서, 프로젝트가 보다 순조롭고 효율적으로 진행됩니다.
업무교육 및 습득 시간을 단축해줘요
SOP는 때로 신입 직원 교육이나 기존 직원 업무 분장에 유용한 자료가 됩니다. 보다 일관성 있는 교육과 학습이 가능해서, 담당 직원이 바뀌더라도 동일한 방식으로 정확하게 작업을 수행할 수 있습니다. 이해하기 쉬운 자료이기 때문에 교육의 속도 역시 빨라집니다.
또한 새로운 일을 지시할 때마다 새롭게 알려주고 도와주려면 상당한 어려움이 따르는 데 반해, 모르는 것이 있을 때나 필요할 때마다 SOP를 참고할 수 있습니다. 작업지시자에게 질문하고 피드백을 받는 데 소요되는 시간도 줄어들고, 빠른 시간내에 주어진 업무 처리에 집중할 수 있습니다.
작업지시에 대한 일관성과 표준을 유지할 수 있어요. 물론 지식 손실도 방지할 수 있습니다.
어떠한 업무를 매일 하는 것이 아니라 어쩌다 한 번씩 하는 일은 지난 번에는 어떻게했지, 기억도 잘 나지않고 이미 처리되었던 업무를 다시 들춰봐야 하는 문제가 있습니다. 또는 집에서 또는 회사에서의 작업기준이 달라지면 당연히 결과도 달라지겠죠. 무조건 AI의 역량과 재량에만 의존하면 스스로의 지식 손실을 초래할 수 있습니다.
이를 방지하기 위해서는 내가 경험했던 지식들을 문서화해 SOP를 제작할 필요가 있습니다. SOP를 통해 작업이 공유되면, 노하우가 특정시점과 위치에 국한되지 않고 전반적인 작업에 전달되어 나만의 표준화되고 일관성이 유지되는 지식 기반을 확장하는 데 기여할 수 있습니다.
브랜드 충성도를 강화해요
일관성은 브랜드 충성도에 가장 크게 기여하는 요소 중 하나입니다. 나의 작업물에 대한 브랜드가 가미된 결과물을 기대할 수 있으며, 앞으로도 그 모습이 이어질 것이라고 믿을 때 나의 지식과 결과물은 일정한 품질안에서 지속성을 유질 할 수 있습니다.
Claude Desktop과 Claude Code에서의 Agent Skill의 차이점
Claude Desktop과 Claude Code는 모두 Agent Skills를 지원하지만, Skill을 등록하고 활용하는 방식에서 근본적인 차이가 있습니다. Claude Desktop은 GUI 기반으로 Settings 메뉴에서 ZIP 파일을 업로드하는 방식을 사용하는 반면, Claude Code는 파일시스템에 직접 Skill 폴더를 배치하는 방식을 사용합니다. 이러한 차이는 각 도구의 특성을 반영한 것으로, 터미널 환경에서 작업하는 개발자들에게 Claude Code의 방식이 더 자연스럽고 버전 관리와의 통합도 용이합니다.
두 환경의 주요 차이점을 표로 정리하면 다음과 같습니다.
| 구분 | Claude Desktop | Claude Code |
| Skill 등록 방식 | ZIP 파일 업로드 (GUI) | 파일시스템 폴더 배치 |
| 저장 위치 | 앱 내부 관리 | ~/.claude/skills/, .claude/skills/ |
| 버전 관리 | 어려움 | Git과 자연스러운 통합 |
| 팀 공유 | 개인별 업로드 필요 | 프로젝트 저장소에 포함 가능 |
| Plugin 지원 | 제한적 | 마켓플레이스 연동 |
Claude Code에서 Skill을 사용하면 프로젝트 저장소의 .claude/skills/ 디렉토리에 Skill을 커밋하여 팀 전체가 동일한 Skill을 사용할 수 있습니다. 또한 Plugin 마켓플레이스를 통해 커뮤니티가 만든 다양한 Skill을 손쉽게 설치하고 관리할 수 있어, 개발 워크플로우 자동화에 매우 유용합니다.
2. Claude Code의 Skill 아키텍처 이해
Claude Code의 Skill 시스템은 Progressive Disclosure라는 핵심 설계 원칙을 따릅니다. 이 원칙은 필요한 정보만 단계적으로 로드하여 컨텍스트 윈도우를 효율적으로 사용하는 것을 의미합니다. Claude가 모든 Skill의 전체 내용을 한 번에 로드하면 토큰 낭비가 심해지므로, 처음에는 Skill의 이름과 설명만 로드하고 실제로 해당 Skill이 필요할 때 전체 내용을 로드하는 방식으로 동작합니다.
Progressive Disclosure란 사용자에게 처음에는 핵심 정보만 보여주고, 필요에 따라 점진적으로 세부 정보를 공개하는 정보 설계 원칙입니다. Claude의 Skill 시스템에서는 이를 통해 수십 개의 Skill이 설치되어 있어도 실제 토큰 사용량을 최소화할 수 있습니다.
Skill 저장 위치와 우선순위
Claude Code는 여러 위치에서 Skill을 검색하며, 동일한 이름의 Skill이 여러 곳에 있을 경우 다음 우선순위에 따라 적용됩니다.
우선순위 (높음 -> 낮음)
|
+-- 1. Managed Skills (조직 관리자가 배포)
|
+-- 2. Personal Skills (~/.claude/skills/)
|
+-- 3. Project Skills (.claude/skills/)
|
+-- 4. Plugin Skills (마켓플레이스 설치)
각 저장 위치의 특성은 다음과 같습니다.
- Managed Skills는 Enterprise 플랜에서 조직 관리자가 전사적으로 배포하는 Skill입니다.
- Personal Skills는 개인 홈 디렉토리에 저장되어 모든 프로젝트에서 사용할 수 있습니다.
- Project Skills는 특정 프로젝트의 .claude/skills/ 디렉토리에 저장되어 해당 프로젝트에서만 사용됩니다.
- Plugin Skills는 마켓플레이스에서 설치한 Skill로, 플러그인 형태로 관리됩니다.
Progressive Disclosure의 3단계
Skill이 로드되는 과정은 다음 세 단계로 이루어집니다.
1단계: Frontmatter 스캔 (~100 tokens)
- name, description만 로드
- 모든 설치된 Skill에 대해 수행
2단계: SKILL.md 전체 로드 (~5,000 tokens)
- Skill이 관련성 있다고 판단되면 전체 내용 로드
- 상세 지침, 예시 포함
3단계: 부속 리소스 로드 (필요시)
- scripts/, references/, assets/ 폴더의 파일
- 작업 수행에 필요한 경우에만 로드
이러한 단계적 로드 방식 덕분에 수십 개의 Skill이 설치되어 있어도 실제로 사용되는 토큰은 현재 작업에 필요한 Skill의 내용만큼입니다.
Skill vs /Command vs Subagent
Claude Code에서 사용할 수 있는 세 가지 확장 메커니즘의 차이를 이해하는 것이 중요합니다.
| 구분 | Skill | /Command | SubAgent |
| 활성화 방식 | Claude가 자동 판단 | 사용자가 /명령어 입력 | context: fork로 호출 |
| 컨텍스트 | 메인 대화에 주입 | 메인 대화에 주입 | 별도 컨텍스트 윈도우 |
| 용도 | 도메인 지식 제공 | 반복 작업 자동화 | 독립 작업 위임 |
| 복잡도 | 중간 | 낮음 | 높음 |
Skill은 Claude가 사용자의 요청을 분석하여 관련 Skill을 자동으로 활성화하므로 사용자가 명시적으로 호출할 필요가 없습니다. 반면 Slash Command는 /pr-description처럼 사용자가 직접 명령어를 입력해야 실행됩니다.
3. Anthropic Public Skill 설치 및 활용
Anthropic은 문서 작업에 유용한 여러 Public Skill을 제공합니다. 이 Skill들은 Claude Code의 Plugin 마켓플레이스를 통해 손쉽게 설치할 수 있으며, Word 문서, PDF, PowerPoint, Excel 파일을 전문가 수준으로 다룰 수 있게 해줍니다.
마켓플레이스 등록 및 설치
Anthropic의 공식 Skill 저장소를 마켓플레이스로 등록하려면 다음 명령어를 사용합니다.
# Anthropic 공식 Skill 저장소를 마켓플레이스로 등록
/plugin marketplace add anthropics/skills
마켓플레이스 등록 후 원하는 Skill 패키지를 설치할 수 있습니다.
# 문서 관련 Skill 설치 (docx, pdf, pptx, xlsx)
/plugin install document-skills@anthropic-agent-skills
# 예제 Skill 설치 (algorithmic-art, canvas-design 등)
/plugin install example-skills@anthropic-agent-skills
설치가 완료되면 Claude Code가 자동으로 해당 Skill들을 인식합니다. 별도의 설정 없이 관련 작업을 요청하면 적절한 Skill이 활성화됩니다. 재설치를 원하면 기존에 설치된 Skill의 디렉토리를 삭제한 후 처음 설치부터 다시하시면 됩니다.
제공되는 Public Skill 종류
Anthropic이 제공하는 주요 Public Skill은 다음과 같습니다.
| Skill이름 | 설명 | 활성화 트리거 |
| docx | Word 문서 생성, 편집, 변경 추적, 코멘트 지원 | Word 문서, docx 파일 작업 요청 |
| PDF 텍스트 추출, 폼 필드 처리, 병합/분할 | PDF 파일 처리 요청 | |
| pptx | PowerPoint 프레젠테이션 생성 및 편집 | 프레젠테이션, 슬라이드 작업 요청 |
| xlsx | Excel 스프레드시트, 수식, 차트 생성 | 스프레드시트, 엑셀 작업 요청 |
실제 사용 예시
PDF Skill을 사용하여 폼 필드를 추출하는 예시입니다.
사용자: "Use the PDF skill to extract the form fields from ./contract.pdf"
Claude의 처리 과정:
1. pdf Skill의 frontmatter 확인
2. 관련성 판단 후 SKILL.md 전체 로드
3. 번들된 Python 스크립트 실행
4. 추출된 폼 필드 정보 반환
Skill이 포함하는 스크립트는 Claude가 직접 실행하며, 스크립트 코드 자체는 컨텍스트에 로드되지 않고 실행 결과만 반환됩니다. 이는 토큰을 절약하면서도 복잡한 작업을 수행할 수 있게 해주는 중요한 설계입니다.
4. 커스텀 Skill 작성 가이드
자신만의 Skill을 작성하면 반복적인 작업 패턴을 자동화하고, 팀의 코딩 표준이나 워크플로우를 Claude에게 가르칠 수 있습니다. Skill 작성은 생각보다 간단하며, 최소한 SKILL.md 파일 하나만 있으면 됩니다. 특히 Anthropic이 제공하는 skill-creator Skill을 활용하면 체계적이고 효율적으로 Skill을 만들 수 있습니다.
skill-creator Skill 설치 및 활용
Anthropic은 Skill 생성을 도와주는 공식 skill-creator Skill을 제공합니다. 이 Skill을 먼저 설치하면 Claude가 Skill 작성의 베스트 프랙티스를 따르도록 안내받을 수 있으며, 초기화 스크립트와 패키징 도구를 활용할 수 있습니다. 물론 Claude Code를 활용한 자연어를 통하여 Skill을 만들 수 있습니다.
skill-creator 설치 방법
Anthropic 공식 저장소에서 skill-creator를 복사하여 개인 Skill로 등록합니다. skll-creator에는 템플릿을 자동으로 생성하고, 생성된 skill에 대한 검증 및 배포를 위한 패키징용 python 스크립트를 포함합니다. 해당 Python 스크립트는 pyyaml과 관련된 의존성을 가지고 있으며, 이를 대응하기 위하여 'pip install pyyaml' 패키지를 설치하는것도 잊으면 안됩니다.
# 1. Anthropic 공식 Skills 저장소 클론
git clone https://github.com/anthropics/skills.git /tmp/anthropic-skills
# 2. skill-creator를 개인 Skill 디렉토리로 복사
mkdir -p ~/.claude/skills
cp -r /tmp/anthropic-skills/skills/skill-creator ~/.claude/skills/
# 3. 임시 파일 정리
rm -rf /tmp/anthropic-skills
# 4. Python 의존성 설치 (검증/패키징 스크립트에 필요)
pip install pyyaml
# 5. 설치 확인
ls ~/.claude/skills/skill-creator/
설치가 완료되면 다음과 같은 파일 구조를 확인할 수 있습니다.
~/.claude/skills/skill-creator/
|-- SKILL.md # Skill 생성 가이드 및 지침
|-- LICENSE.txt # 라이선스 정보
|-- scripts/
| |-- init_skill.py # Skill 초기화 스크립트
| |-- package_skill.py # Skill 패키징 스크립트
| +-- quick_validate.py # Skill 검증 스크립트
+-- references/
|-- output-patterns.md # 출력 패턴 가이드
+-- workflows.md # 워크플로우 패턴 가이드skill-creator가 제공하는 핵심 도구
| 스크립트 | 용도 | 실행방법 | 의존성 |
| init_skill.py | 새 Skill 템플릿 생성 | python scripts/init_skill.py <name> --path <dir> | 없음 |
| package_skill.py | Skill을 .skill 파일로 패키징 | python scripts/package_skill.py <skill-folder> | pyyaml |
| quick_validate.py | Skill 구조 및 문법 검증 | python scripts/quick_validate.py <skill-folder> | pyyaml |
skill-creator를 활용한 Skill 생성 워크플로우
skill-creator Skill이 설치되면 Claude Code에서 자연어로 Skill 생성을 요청할 수 있습니다. Claude는 skill-creator의 지침을 따라 체계적으로 Skill을 만들어줍니다.
Step 1 | Skill 초기화
새 Skill을 만들 때는 init_skill.py 스크립트를 사용하여 템플릿을 생성합니다.
# skill-creator 디렉토리에서 실행
cd ~/.claude/skills/skill-creator
# 새 Skill 초기화 (예: api-docs-generator)
python scripts/init_skill.py api-docs-generator --path ~/.claude/skills
실행 결과 다음과 같은 구조가 생성됩니다.
~/.claude/skills/api-docs-generator/
|-- SKILL.md # TODO 플레이스홀더가 포함된 템플릿
|-- scripts/
| +-- example.py # 예제 스크립트
|-- references/
| +-- api_reference.md # 예제 참조 문서
+-- assets/
+-- example_asset.txt # 예제 에셋 파일Step 2 | SKILL.md 편집
생성된 SKILL.md 파일을 열어 TODO 항목을 실제 내용으로 채웁니다.
---
name: api-docs-generator
description: [TODO: 이 부분을 채워야 합니다]
---
# Api Docs Generator
## Overview
[TODO: 1-2 sentences explaining what this skill enables]
skill-creator는 description 작성에 대해 다음과 같은 가이드를 제공합니다.
description 작성 가이드:
- 무엇을 하는지 (What): "API 문서를 자동 생성합니다"
- 언제 사용하는지 (When): "OpenAPI 스펙 분석, REST API 문서화 시"
- 트리거 키워드: 사용자가 자연스럽게 말할 표현 포함
완성된 예시는 다음과 같습니다.
---
name: api-docs-generator
description: OpenAPI/Swagger 스펙을 분석하여 마크다운 형식의 API 문서를
자동 생성합니다. API 문서화, REST API 문서 작성,
OpenAPI 스펙 분석 시 사용합니다.
---Step 3 | 리소스 파일 구성
필요에 따라 scripts, references, assets 폴더에 파일을 추가하거나 불필요한 예제 파일을 삭제합니다.
# 불필요한 예제 파일 삭제
rm ~/.claude/skills/api-docs-generator/scripts/example.py
rm ~/.claude/skills/api-docs-generator/references/api_reference.md
rm ~/.claude/skills/api-docs-generator/assets/example_asset.txt
# 실제 필요한 스크립트 추가
cat > ~/.claude/skills/api-docs-generator/scripts/parse_openapi.py << 'EOF'
#!/usr/bin/env python3
"""OpenAPI 스펙 파싱 스크립트"""
import json
import sys
import yaml
def parse_spec(filepath):
with open(filepath, 'r') as f:
if filepath.endswith('.yaml') or filepath.endswith('.yml'):
return yaml.safe_load(f)
return json.load(f)
if __name__ == "__main__":
if len(sys.argv) < 2:
print("Usage: parse_openapi.py <spec-file>")
sys.exit(1)
spec = parse_spec(sys.argv[1])
print(json.dumps(spec, indent=2))
EOF
chmod +x ~/.claude/skills/api-docs-generator/scripts/parse_openapi.pyStep 4 | Skill 검증
작성한 Skill이 올바른 구조를 가지고 있는지 검증합니다. 검증 스크립트는 pyyaml 패키지를 필요로 하므로 먼저 설치해야 합니다.
# PyYAML 의존성 설치 (최초 1회)
pip install pyyaml
# Skill 검증 실행
cd ~/.claude/skills/skill-creator
python scripts/quick_validate.py ~/.claude/skills/api-docs-generatorquick_validate.py와 package_skill.py 스크립트는 YAML 파싱을 위해 pyyaml 패키지가 필요합니다. ModuleNotFoundError: No module named 'yaml' 에러가 발생하면 pip install pyyaml 명령으로 설치하세요.
검증 결과 예시는 다음과 같습니다.
Validating skill: api-docs-generator
[v] SKILL.md exists
[v] YAML frontmatter valid
[v] name field present (api-docs-generator)
[v] description field present (127 chars)
[v] Directory structure valid
Validation passed!Step 5 | Skill 패키징 (선택사항)
다른 사람과 공유하거나 Claude Desktop에 업로드할 경우 .skill 파일로 패키징합니다.
cd ~/.claude/skills/skill-creator
python scripts/package_skill.py ~/.claude/skills/api-docs-generator
# 결과: api-docs-generator.skill 파일 생성
생성된 .skill 파일은 ZIP 형식이며, Claude Desktop의 Settings > Capabilities > Skills에서 업로드하여 사용할 수 있습니다.
Claude Code에서 skill-creator 활용하기
skill-creator Skill이 설치된 상태에서 Claude Code에게 자연어로 요청하면 더욱 편리하게 Skill을 만들 수 있습니다.
사용자: "n8n 스크래핑 작업을 위한 새 Skill을 만들어줘.
Browserless 컨테이너 연동과 Cloudflare 우회 방법을 포함해야 해."
Claude: (skill-creator Skill 활성화)
먼저 Skill의 용도를 명확히 하기 위해 몇 가지 질문드리겠습니다.
1. 이 Skill이 트리거되어야 하는 상황은 어떤 것들이 있나요?
(예: "웹 스크래핑", "Cloudflare 우회", "Browserless 사용")
2. 스크래핑 대상 사이트의 특성이 있나요?
(예: 특정 국가 사이트, 이커머스 등)
[사용자 답변 후]
init_skill.py를 실행하여 n8n-scraping Skill을 초기화하겠습니다.
[Skill 생성 및 SKILL.md 작성]
이처럼 skill-creator를 활용하면 Claude가 6단계 워크플로우를 안내하며 체계적으로 Skill을 만들어줍니다.
skill-creator의 6단계 워크플로우:
1. 구체적인 사용 예시 수집 (Understanding)
2. 재사용 가능한 리소스 계획 (Planning)
3. init_skill.py로 초기화 (Initializing)
4. SKILL.md 및 리소스 편집 (Editing)
5. package_skill.py로 패키징 (Packaging)
6. 테스트 및 반복 개선 (Iterating)SKILL.md 파일 구조
모든 Skill의 핵심은 SKILL.md 파일입니다. 이 파일은 YAML frontmatter와 Markdown 본문으로 구성됩니다.
---
name: my-custom-skill
description: 이 스킬이 언제 활성화되어야 하는지 명확하게 설명합니다.
사용자가 자연스럽게 말할 키워드를 포함하세요.
allowed-tools: Read, Write, Bash
---
# 스킬 제목
## 개요
이 스킬이 무엇을 하는지 간략히 설명합니다.
## 지침
1. 첫 번째 단계에 대한 상세 설명
2. 두 번째 단계에 대한 상세 설명
3. 세 번째 단계에 대한 상세 설명
## 예시
입력과 출력 예시를 제공하여 Claude가 기대되는 동작을 이해할 수 있게 합니다.
## 주의사항
- 피해야 할 패턴
- 엣지 케이스 처리 방법Frontmatter 필수 필드
YAML frontmatter에서 반드시 포함해야 하는 필드는 다음과 같습니다.
| 필드 | 최대 길이 | 설명 |
| name | 64자 | Skill의 고유 식별자, 영문 소문자와 하이픈 권장 |
| description | 200자 | Claude가 Skill 활성화 여부를 판단하는 핵심 정보 |
description 필드는 특히 중요합니다. Claude는 이 설명을 읽고 현재 사용자의 요청에 해당 Skill이 적합한지 판단합니다. 따라서 사용자가 자연스럽게 사용할 키워드를 포함해야 합니다.
# 좋은 예시
description: Git diff를 분석하여 커밋 메시지를 생성합니다.
커밋 메시지 작성, staged changes 검토 시 사용합니다.
# 나쁜 예시
description: 유용한 개발 도구입니다.선택적 Frontmatter 필드
추가적인 제어가 필요한 경우 다음 필드들을 사용할 수 있습니다.
---
name: secure-file-reader
description: 파일을 읽기 전용으로 안전하게 접근합니다.
allowed-tools: Read, Grep, Glob
dependencies:
- python3
- jq
---
allowed-tools 필드를 사용하면 해당 Skill이 활성화되었을 때 Claude가 사용할 수 있는 도구를 제한할 수 있습니다. 이는 보안이 중요한 워크플로우에서 유용합니다.
디렉토리 구조 설계
복잡한 Skill은 여러 파일로 구성될 수 있습니다. 권장되는 디렉토리 구조는 다음과 같습니다.
my-skill/
|-- SKILL.md # 필수: 메인 Skill 파일
|-- scripts/ # 선택: 실행 가능한 스크립트
| |-- validate.py
| +-- process.sh
|-- references/ # 선택: 참조 문서
| |-- api-spec.md
| +-- examples.json
+-- assets/ # 선택: 템플릿, 이미지 등
|-- template.html
+-- logo.png
scripts 폴더의 파일은 Claude가 직접 실행할 수 있으며, 실행 결과만 컨텍스트에 포함됩니다. references 폴더의 파일은 Claude가 필요할 때 읽어서 컨텍스트에 로드합니다. assets 폴더는 출력물 생성에 사용되는 템플릿이나 리소스를 담습니다.
Skill 작성 베스트 프랙티스
효과적인 Skill을 작성하기 위한 핵심 원칙들입니다.
명확한 트리거 키워드 포함
description에 사용자가 자연스럽게 말할 키워드를 포함합니다.
# 좋음: 구체적인 트리거 키워드 포함
description: PR 설명 작성, pull request description 생성,
변경사항 요약 시 사용합니다.
# 나쁨: 모호한 설명
description: GitHub 관련 작업을 도와줍니다.Progressive Disclosure 활용
모든 정보를 SKILL.md에 담지 말고, 상세 정보는 별도 파일로 분리합니다.
## 데이터베이스 스키마
상세 스키마 정보는 `references/schema.md`를 참조하세요.예시 포함
Claude가 기대되는 동작을 이해할 수 있도록 구체적인 예시를 제공합니다.
## 예시
### 입력
"fix: 로그인 버튼 클릭 시 발생하는 에러 수정"
### 출력
커밋 메시지가 Conventional Commits 형식을 따르고 있습니다.
- 타입: fix (버그 수정)
- 설명: 명확하고 간결함
- 권장사항: 이슈 번호 추가 고려 (예: fix: 로그인 버튼 에러 수정 #123)5. 커스텀 Skill 등록 방법
작성한 Skill을 Claude Code에서 사용하려면 적절한 위치에 배치해야 합니다. 용도에 따라 개인 Skill, 프로젝트 Skill, 또는 Plugin으로 등록할 수 있습니다.
개인 Skill 등록
모든 프로젝트에서 사용할 Skill은 홈 디렉토리의 .claude/skills/ 폴더에 배치합니다.
# macOS/Linux
mkdir -p ~/.claude/skills/my-skill
cp SKILL.md ~/.claude/skills/my-skill/
# Windows
mkdir %USERPROFILE%\.claude\skills\my-skill
copy SKILL.md %USERPROFILE%\.claude\skills\my-skill\
이렇게 등록된 Skill은 어느 프로젝트에서든 Claude Code를 실행하면 자동으로 인식됩니다.
프로젝트 Skill 등록
특정 프로젝트에서만 사용할 Skill은 프로젝트 루트의 .claude/skills/ 폴더에 배치합니다.
# 프로젝트 디렉토리에서
mkdir -p .claude/skills/project-conventions
cp SKILL.md .claude/skills/project-conventions/
# Git에 커밋하여 팀과 공유
git add .claude/skills/
git commit -m "feat: 프로젝트 코딩 컨벤션 Skill 추가"
프로젝트 Skill의 장점은 버전 관리가 가능하고 팀원 모두가 동일한 Skill을 사용할 수 있다는 것입니다. 코딩 표준, 아키텍처 가이드, 배포 절차 등을 Skill로 만들어 공유하면 팀 전체의 일관성을 유지할 수 있습니다.
모노레포 지원
Claude Code는 모노레포 구조도 지원합니다. 하위 패키지에서 작업할 때 해당 패키지의 .claude/skills/ 디렉토리도 자동으로 검색합니다.
monorepo/
|-- .claude/skills/ # 전체 프로젝트 공통 Skill
|-- packages/
| |-- frontend/
| | +-- .claude/skills/ # 프론트엔드 전용 Skill
| +-- backend/
| +-- .claude/skills/ # 백엔드 전용 Skill
실습 | 커밋 메시지 생성 Skill 만들기
간단한 커밋 메시지 생성 Skill을 직접 만들어 보겠습니다.
# 1. Skill 디렉토리 생성
mkdir -p ~/.claude/skills/commit-message
# 2. SKILL.md 파일 생성
cat > ~/.claude/skills/commit-message/SKILL.md << 'EOF'
---
name: commit-message-generator
description: Git diff를 분석하여 Conventional Commits 형식의 커밋 메시지를
생성합니다. 커밋 메시지 작성, staged changes 검토 시 사용합니다.
allowed-tools: Bash, Read
---
# 커밋 메시지 생성기
## 개요
staged된 변경사항을 분석하여 Conventional Commits 형식의 커밋 메시지를
제안합니다.
## 지침
1. `git diff --staged` 명령을 실행하여 변경사항 확인
2. 변경 내용을 분석하여 적절한 커밋 타입 결정
3. 50자 이내의 제목과 상세 설명 작성
## 커밋 타입
- feat: 새로운 기능 추가
- fix: 버그 수정
- docs: 문서 변경
- style: 코드 포맷팅 (기능 변경 없음)
- refactor: 리팩토링 (기능 변경 없음)
- test: 테스트 추가/수정
- chore: 빌드, 설정 파일 변경
## 출력 형식
<타입>(<범위>): <제목>
<본문>
<꼬리말>
## 예시
### 입력 (git diff --staged 결과)
src/auth/login.ts 파일에서 에러 핸들링 로직 추가
### 출력
fix(auth): 로그인 실패 시 에러 메시지 표시 추가
try-catch 블록으로 API 호출 감싸기
사용자에게 친화적인 에러 메시지 표시
에러 로깅 추가
Closes #42
EOF
# 3. Claude Code 재시작 또는 새 세션 시작
echo "Skill 등록 완료! Claude Code에서 '커밋 메시지 작성해줘'라고 요청해보세요."
등록 후 Claude Code에서 다음과 같이 사용할 수 있습니다.
사용자: "staged된 변경사항에 대한 커밋 메시지 작성해줘"
Claude: (commit-message-generator Skill 자동 활성화)
git diff --staged를 실행하여 변경사항을 확인하겠습니다.
[분석 결과를 바탕으로 커밋 메시지 제안]
6. n8n 워크플로우 생성을 위한 Skill 활용
n8n은 강력한 워크플로우 자동화 플랫폼이지만, 노드 구성과 JSON 설정이 복잡할 수 있습니다. Claude Code와 전문 Skill을 활용하면 자연어로 워크플로우를 설명하고 즉시 사용 가능한 JSON을 생성할 수 있습니다. 이 섹션에서는 n8n 워크플로우 생성에 특화된 Skill들을 소개합니다.
n8n-mcp : MCP 서버 소개
n8n 워크플로우를 AI로 생성하려면 먼저 n8n-mcp MCP 서버를 설치해야 합니다. 이 서버는 Claude에게 n8n의 1,084개 노드에 대한 완전한 지식을 제공합니다.
MCP(Model Context Protocol)는 AI 모델이 외부 도구와 데이터 소스에 접근할 수 있게 해주는 프로토콜입니다. n8n-mcp는 이 프로토콜을 통해 Claude가 n8n 노드를 검색하고, 설정을 검증하고, 템플릿을 참조할 수 있게 합니다.
n8n-mcp가 제공하는 주요 기능은 다음과 같습니다.
| 기능 | 설명 |
| 노드 검색 | 1,084개 노드 (537 코어 + 547 커뮤니티) 검색 |
| 속성 정보 | 99% 커버리지의 상세 스키마 제공 |
| 작업 정보 | 63.6% 커버리지의 가용 액션 정보 |
| 문서화 | 87% 커버리지의 공식 문서 연동 |
| 실제 예시 | 2,646개의 실제 템플릿에서 추출한 설정 예시 |
n8n-skills 설치 방법
n8n-skills는 n8n-mcp와 함께 사용하면 더욱 강력해지는 7가지 전문 Skill 모음입니다. 설치 방법은 두 가지가 있습니다.
방법 1: Plugin 마켓플레이스 사용
# 마켓플레이스 등록
/plugin marketplace add czlonkowski/n8n-skills
# 플러그인 설치
/plugin install n8n-mcp-skills
방법 2: 수동 설치
# 저장소 클론
git clone https://github.com/czlonkowski/n8n-skills.git
# Skill 파일 복사
cp -r n8n-skills/skills/* ~/.claude/skills/
# Claude Code 재시작7가지 n8n Skills 상세 | n8n-mcp-skill
각 Skill은 특정 상황에서 자동으로 활성화됩니다. n8n-mcp-skill에 대해서는 다른 글에서 보다 상세히 다룰 예정입니다.
n8n Expression Syntax
n8n 표현식 문법을 가르치는 Skill입니다. {{ }} 문법 사용, $json, $node 변수 접근, 표현식 오류 해결 시 활성화됩니다.
활성화 트리거 예시:
- "n8n 표현식 어떻게 작성해?"
- "{{}} 문법 사용법 알려줘"
- "$json 변수 접근 방법은?"
n8n MCP Tools Expert (최우선 순위)
n8n-mcp 도구를 효과적으로 사용하는 방법을 안내합니다. 노드 검색, 설정 검증, 템플릿 참조 시 활성화됩니다.
활성화 트리거 예시:
- "Slack 노드 찾아줘"
- "HTTP Request 노드 설정 방법은?"
- "워크플로우 템플릿 있어?"
n8n Workflow Patterns
5가지 검증된 아키텍처 패턴으로 워크플로우를 구성합니다. 워크플로우 생성, 노드 연결, 자동화 설계 시 활성화됩니다.
5가지 핵심 패턴:
1. Webhook -> Process -> Output
2. Schedule -> Fetch -> Transform -> Store
3. Trigger -> Branch -> Multiple Actions
4. Error Handling with Fallback
5. Batch Processing with Loopn8n Validation Expert
검증 오류를 해석하고 수정 방법을 안내합니다. 설정 오류 발생, 워크플로우 검증 실패 시 활성화됩니다.
n8n Node Configuration
개별 노드의 상세 설정 방법을 안내합니다. 특정 노드 설정, 속성 이해가 필요할 때 활성화됩니다.
n8n Code JavaScript
JavaScript Code 노드 작성을 지원합니다. 95%의 사용 사례에서 권장되는 방식입니다.
n8n Code Python
Python Code 노드 작성을 지원합니다. 단, Python은 n8n에서 제한사항이 많아 JavaScript를 우선 권장합니다.
!! n8n의 Python Code 노드는 pandas 등 외부 라이브러리 사용에 제한이 있습니다. 가능하면 JavaScript Code 노드를 사용하는 것이 좋습니다. 물론 제한이 있다고 해서 사용할 수 없는 것은 아니며, n8n 커스텀 이미지 제작과정에서 필요한 라이브러리를 포함해서 만들어서 포팅된다면 사용하는데 문제는 없습니다.
7. 실전 예제 | Claude Code로 n8n 워크플로우 생성하기
이제 실제로 Claude Code와 n8n Skills를 사용하여 워크플로우를 생성해 보겠습니다. 자연어 요청부터 완성된 워크플로우 JSON까지의 전체 과정을 살펴봅니다.
MCP 서버와 Skill의 시너지
n8n-mcp(MCP 서버)와 n8n-skills(Skill)는 서로 다른 역할을 수행하며 함께 사용할 때 시너지를 발휘합니다.
+------------------+ +------------------+
| n8n-mcp | | n8n-skills |
| (MCP 서버) | | (Skills) |
+------------------+ +------------------+
| |
v v
[도구 제공] [지식 제공]
- 노드 검색 - 표현식 문법
- 설정 검증 - 워크플로우 패턴
- 템플릿 조회 - 베스트 프랙티스
- API 연동 - 오류 해결 방법
| |
+----------+-------------+
|
v
[완벽한 워크플로우 생성]
MCP는 "무엇을 할 수 있는가"를 제공하고, Skill은 "어떻게 해야 하는가"를 가르칩니다.
자연어로 워크플로우 생성 프로세스
웹훅을 받아서 Slack으로 알림을 보내는 워크플로우를 만드는 예시입니다.
사용자 요청:
"웹훅으로 주문 데이터를 받아서, 주문 금액이 10만원 이상이면
Slack #high-value-orders 채널에 알림을 보내는 워크플로우 만들어줘"
Claude의 처리 과정은 다음과 같습니다.
1. n8n Workflow Patterns Skill 활성화
-> Webhook -> Branch -> Output 패턴 선택
2. n8n MCP Tools Expert Skill 활성화
-> search_nodes로 Webhook, IF, Slack 노드 검색
-> get_node로 각 노드의 필수 속성 확인
3. n8n Expression Syntax Skill 활성화
-> $json.body.orderAmount 표현식 작성
-> IF 조건 설정
4. n8n Validation Expert Skill 활성화
-> 생성된 설정 검증
-> 오류 있으면 수정
생성된 워크플로우 JSON 예시
위 요청에 대해 생성되는 워크플로우 JSON의 핵심 구조입니다.
{
"name": "High Value Order Notification",
"nodes": [
{
"parameters": {
"httpMethod": "POST",
"path": "orders",
"responseMode": "onReceived"
},
"name": "Webhook",
"type": "n8n-nodes-base.webhook",
"position": [250, 300]
},
{
"parameters": {
"conditions": {
"number": [
{
"value1": "={{ $json.body.orderAmount }}",
"operation": "largerEqual",
"value2": 100000
}
]
}
},
"name": "Check Amount",
"type": "n8n-nodes-base.if",
"position": [450, 300]
},
{
"parameters": {
"channel": "#high-value-orders",
"text": "=고액 주문 알림!\n주문번호: {{ $json.body.orderId }}\n금액: {{ $json.body.orderAmount }}원",
"otherOptions": {}
},
"name": "Slack Notification",
"type": "n8n-nodes-base.slack",
"position": [650, 200]
}
],
"connections": {
"Webhook": {
"main": [[{ "node": "Check Amount", "type": "main", "index": 0 }]]
},
"Check Amount": {
"main": [
[{ "node": "Slack Notification", "type": "main", "index": 0 }],
[]
]
}
}
}워크플로우 검증 및 배포
생성된 워크플로우는 n8n-mcp의 검증 도구를 통해 확인할 수 있습니다.
사용자: "생성된 워크플로우 검증해줘"
Claude: (n8n Validation Expert Skill 활성화)
validate_workflow 도구로 검증을 수행합니다.
검증 결과:
[v] 모든 노드 연결 유효
[v] 필수 속성 설정 완료
[v] 표현식 문법 정상
[!] 권장: Slack 노드에 credential 설정 필요
[!INFO] Credential 설정은 n8n UI에서 직접 해야 합니다. 보안상의 이유로 API 키와 같은 민감한 정보는 워크플로우 JSON에 포함하지 않습니다.
8. Skill과 MCP의 조합 전략
Skill과 MCP는 Claude의 기능을 확장하는 두 가지 주요 메커니즘입니다. 이 둘을 효과적으로 조합하면 Claude를 특정 도메인의 전문가로 만들 수 있습니다.
Skill이 MCP를 활용하는 방식
Skill은 Claude에게 "어떻게" 해야 하는지를 가르치고, MCP는 "무엇을" 할 수 있는지를 제공합니다. n8n 예시에서 이 관계를 명확히 볼 수 있습니다.
Skill의 역할 (지식 제공):
- n8n 표현식 문법 규칙
- 워크플로우 설계 패턴
- 일반적인 실수와 해결 방법
- 베스트 프랙티스
MCP의 역할 (도구 제공):
- 실제 노드 검색 API
- 노드 속성 스키마 조회
- 워크플로우 검증 실행
- 템플릿 데이터베이스 접근
n8n-mcp + n8n-skills 조합의 장점
두 시스템을 함께 사용하면 다음과 같은 장점이 있습니다.
| 항목 | MCP만 사용 | Skill만 사용 | MCP + Skill |
| 노드 정보 | 정확함 | 학습 데이터 기반 | 정확함 |
| 표현식 문법 | 없음 | 있음 | 있음 |
| 패턴 지식 | 없음 | 있음 | 있음 |
| 실시간 검증 | 가능 | 불가능 | 가능 |
| 일관성 | 높음 | 중간 | 높음 |
커스텀 MCP 서버와 Skill 연동 아이디어
자체 MCP 서버를 만들고 이를 활용하는 Skill을 작성하면 조직 특화 자동화가 가능합니다.
예시 1 | 내부 API 연동
# company-api-skill/SKILL.md
---
name: company-api-expert
description: 회사 내부 API를 사용한 데이터 조회 및 처리.
직원 정보, 프로젝트 데이터, 리소스 할당 시 사용합니다.
---
# 회사 API 전문가
## 개요
company-api MCP 서버를 통해 내부 시스템에 접근합니다.
## 사용 가능한 MCP 도구
- get_employee: 직원 정보 조회
- list_projects: 프로젝트 목록
- allocate_resource: 리소스 할당
## 주의사항
- 개인정보 조회 시 권한 확인 필수
- 리소스 할당은 매니저 승인 후 진행예시 2 | 데이터베이스 쿼리 자동화
# db-query-skill/SKILL.md
---
name: db-query-assistant
description: 데이터베이스 쿼리 작성 및 최적화. SQL 작성,
쿼리 성능 개선, 스키마 분석 시 사용합니다.
---
# 데이터베이스 쿼리 어시스턴트
## MCP 연동
postgres-mcp 서버를 통해 데이터베이스에 접근합니다.
## 쿼리 작성 원칙
1. SELECT 시 필요한 컬럼만 명시
2. JOIN 사용 시 인덱스 활용 확인
3. WHERE 절 최적화9. 문제 해결 및 팁
Skill 사용 중 발생할 수 있는 일반적인 문제들과 해결 방법을 정리했습니다.
Skill이 인식되지 않을 때
증상: Claude Code에서 "어떤 Skill이 있어?"라고 물어도 새로 추가한 Skill이 나타나지 않습니다.
해결 방법:
# 1. 파일 위치 확인
ls -la ~/.claude/skills/my-skill/SKILL.md
# 2. SKILL.md 파일명 확인 (대소문자 정확히)
# 올바름: SKILL.md
# 틀림: skill.md, Skill.md
# 3. YAML frontmatter 문법 확인
# ---로 시작하고 ---로 끝나야 함
# 4. Claude Code 재시작
# 터미널에서 claude 명령으로 새 세션 시작Plugin 캐시 초기화
증상: 마켓플레이스에서 설치한 Skill이 업데이트되지 않거나 오작동합니다.
해결 방법:
# Plugin 캐시 삭제 및 재설치
/plugin uninstall <plugin-name>
/plugin cache clear
/plugin install <plugin-name>allowed-tools 설정 주의사항
allowed-tools를 설정하면 해당 Skill 활성화 시 Claude가 사용할 수 있는 도구가 제한됩니다. 필요한 도구를 빠뜨리지 않도록 주의해야 합니다.
# 파일 읽기만 허용 (쓰기 불가)
allowed-tools: Read, Grep, Glob
# Bash 포함 (스크립트 실행 필요 시)
allowed-tools: Read, Write, Bash
# 제한 없음 (생략하면 모든 도구 사용 가능)
# allowed-tools 필드 자체를 생략보안 고려사항
Skill은 Claude가 실행하는 코드와 지침을 포함할 수 있으므로 보안에 주의해야 합니다.
[!] 신뢰할 수 있는 소스의 Skill만 설치
[!] 설치 전 SKILL.md와 스크립트 내용 검토
[!] API 키, 비밀번호 등 민감 정보를 Skill에 하드코딩하지 않기
[!] allowed-tools로 필요한 권한만 부여자주 묻는 질문
Q: Skill과 CLAUDE.md의 차이는 무엇인가요?
A: CLAUDE.md는 항상 로드되는 프로젝트 컨텍스트이고, Skill은 필요할 때만 동적으로 로드됩니다. 짧은 프로젝트 규칙은 CLAUDE.md에, 상세한 워크플로우는 Skill에 작성합니다.
Q: 무료 플랜에서도 Skill을 사용할 수 있나요?
A: 아니요, Skill은 Pro, Max, Team, Enterprise 플랜에서만 사용할 수 있습니다.
Q: 여러 Skill이 동시에 활성화될 수 있나요?
A: 네, Claude는 요청에 관련된 여러 Skill을 동시에 활성화할 수 있습니다. 각 Skill은 모듈식으로 설계되어 함께 작동합니다.
10. 마무리 및 다음 단계
Claude Code에서 Agent Skills를 활용하면 반복적인 설명 없이도 전문적인 작업을 수행할 수 있습니다. 파일시스템 기반의 Skill 관리는 버전 관리와 팀 협업에 최적화되어 있으며, MCP와의 조합을 통해 강력한 자동화 워크플로우를 구축할 수 있습니다.
Skill 생태계의 성장
Agent Skills 생태계는 빠르게 성장하고 있습니다. SkillsMP 같은 마켓플레이스에는 이미 63,000개 이상의 Skill이 등록되어 있으며, 다양한 도메인을 커버합니다.
커뮤니티 Skill 카테고리:
- 개발 도구: 코드 리뷰, 테스트 작성, 문서화
- 자동화: n8n, Zapier, Make 통합
- 디자인: Figma, UI 컴포넌트 생성
- 데이터: SQL 최적화, 분석 리포트
- 커뮤니케이션: PR 작성, 이메일 템플릿
SKILL.md 오픈 표준
Anthropic은 Agent Skills를 오픈 표준으로 공개했습니다. 이는 SKILL.md 형식이 Claude Code뿐만 아니라 OpenAI Codex CLI, ChatGPT 등 다른 AI 도구에서도 호환된다는 것을 의미합니다.
호환 플랫폼:
- Claude Code
- OpenAI Codex CLI
- ChatGPT (일부 지원)
- 기타 SKILL.md 표준 채택 도구
앞으로의 활용 아이디어
Skill 시스템을 활용한 몇 가지 아이디어를 제안합니다.
팀 온보딩 Skill
새로운 팀원이 프로젝트에 빠르게 적응할 수 있도록 코드베이스 구조, 개발 환경 설정, 코딩 컨벤션을 담은 Skill을 만들 수 있습니다.
배포 자동화 Skill
배포 전 체크리스트, 환경별 설정, 롤백 절차를 Skill로 문서화하여 안전한 배포를 지원할 수 있습니다.
도메인 지식 Skill
회사의 비즈니스 로직, API 스펙, 데이터 모델을 Skill로 만들어 Claude가 도메인 전문가처럼 동작하게 할 수 있습니다.
참고 자료
'AI 활용' 카테고리의 다른 글
| n8n-mcp-skill을 위한 n8n-mcp 완벽 설정 가이드 (0) | 2026.01.19 |
|---|---|
| [claude] n8n-mcp-skill로 실전 워크플로우 작성해 볼까요? (1) | 2026.01.18 |
| n8n Code 노드에서 정규표현식(Regex)을 알고 씁시다 (0) | 2026.01.17 |
| n8n 워크플로우 생성을 위한 Claude Skill 활용하기 - Desktop (0) | 2026.01.17 |
| n8n에서 Python Code노드 실행하기 (2/2) - External Mode (1) | 2026.01.12 |
