스킬 크리에이터: 효과적인 클로드 스킬 구축하기

--- name: skill-creator description: 효과적인 스킬을 만드는 방법에 대한 가이드입니다. 이 스킬은 사용자가 전문 지식, 워크플로우 또는 도구 통합을 통해 Claude의 기능을 확장하는 새 스킬(또는 기존 스킬 업데이트)을 만들고자 할 때 사용해야 합니다. license: 전체 약관은 LICENSE.txt에 있습니다 --- # Skill Creator 이 스킬은 효과적인 스킬을 만드는 방법에 대한 지침을 제공합니다. ## 스킬에 대하여 스킬은 전문 지식, 워크플로우 및 도구를 제공하여 Claude의 기능을 확장하는 모듈식의 독립적인 패키지입니다. 특정 도메인이나 작업을 위한 "온보딩 가이드"로 생각하면 됩니다 - 즉, Claude를 범용 에이전트에서 특정 도메인이나 작업을 위한 절차적 지식을 갖춘 전문 에이전트로 변환합니다. 이 지식은 어떤 모델도 완전히 보유할 수 없습니다. ### 스킬이 제공하는 것 1. 전문 워크플로우 - 특정 도메인을 위한 다단계 절차 2. 도구 통합 - 특정 파일 형식 또는 API 작업을 위한 지침 3. 도메인 전문성 - 회사별 지식, 스키마, 비즈니스 로직 4. 번들 리소스 - 복잡하고 반복적인 작업을 위한 스크립트, 참조 자료 및 에셋 ## 핵심 원칙 ### 간결함이 핵심 컨텍스트 창은 공공재입니다. 스킬은 시스템 프롬프트, 대화 기록, 다른 스킬의 메타데이터, 실제 사용자 요청 등 Claude가 필요로 하는 모든 것과 컨텍스트 창을 공유합니다. **기본 가정: Claude는 이미 매우 똑똑합니다.** Claude가 아직 가지고 있지 않은 컨텍스트만 추가하세요. 각 정보에 대해 의문을 제기하세요: "Claude가 정말 이 설명이 필요한가?" 그리고 "이 문단이 토큰 비용을 정당화하는가?" 장황한 설명보다 간결한 예시를 선호하세요. ### 적절한 자유도 설정 작업의 취약성과 가변성에 맞춰 특정성 수준을 조정하세요: **높은 자유도(텍스트 기반 지침)**: 여러 접근 방식이 유효하고, 결정이 컨텍스트에 의존하거나, 휴리스틱이 접근 방식을 안내할 때 사용합니다. **중간 자유도(매개변수가 있는 의사코드 또는 스크립트)**: 선호하는 패턴이 존재하고, 약간의 변형이 허용되거나, 구성이 동작에 영향을 미칠 때 사용합니다. **낮은 자유도(특정 스크립트, 적은 매개변수)**: 작업이 취약하고 오류가 발생하기 쉬우며, 일관성이 중요하거나, 특정 순서를 따라야 할 때 사용합니다. Claude가 경로를 탐색하는 것으로 생각하세요: 절벽이 있는 좁은 다리는 특정 가드레일(낮은 자유도)이 필요하고, 열린 들판은 많은 경로(높은 자유도)를 허용합니다. ### 스킬의 구조 모든 스킬은 필수 SKILL.md 파일과 선택적 번들 리소스로 구성됩니다: ``` skill-name/ ├── SKILL.md (필수) │ ├── YAML 프론트매터 메타데이터 (필수) │ │ ├── name: (필수) │ │ └── description: (필수) │ └── Markdown 지침 (필수) └── 번들 리소스 (선택) ├── scripts/ - 실행 가능한 코드 (Python/Bash 등) ├── references/ - 필요에 따라 컨텍스트에 로드되는 문서 └── assets/ - 출력에 사용되는 파일 (템플릿, 아이콘, 글꼴 등) ``` #### SKILL.md (필수) 모든 SKILL.md는 다음으로 구성됩니다: - **프론트매터** (YAML): `name` 및 `description` 필드를 포함합니다. 이 필드는 Claude가 스킬이 사용되는 시기를 결정하기 위해 읽는 유일한 필드이므로, 스킬이 무엇인지와 언제 사용해야 하는지에 대해 명확하고 포괄적으로 설명하는 것이 매우 중요합니다. - **본문** (Markdown): 스킬 사용을 위한 지침 및 안내입니다. 스킬이 트리거된 후에만 로드됩니다(로드되는 경우). #### 번들 리소스 (선택) ##### 스크립트 (`scripts/`) 결정적 신뢰성이 필요하거나 반복적으로 다시 작성되는 작업을 위한 실행 가능한 코드(Python/Bash 등)입니다. - **포함 시기**: 동일한 코드가 반복적으로 다시 작성되거나 결정적 신뢰성이 필요할 때 - **예시**: PDF 회전 작업을 위한 `scripts/rotate_pdf.py` - **이점**: 토큰 효율적, 결정적, 컨텍스트에 로드하지 않고 실행 가능 - **참고**: 스크립트는 패치 또는 환경별 조정을 위해 Claude가 여전히 읽어야 할 수 있습니다. ##### 참조 자료 (`references/`) Claude의 프로세스와 사고를 안내하기 위해 필요에 따라 컨텍스트에 로드되는 문서 및 참조 자료입니다. - **포함 시기**: Claude가 작업 중 참조해야 하는 문서의 경우 - **예시**: 금융 스키마용 `references/finance.md`, 회사 NDA 템플릿용 `references/mnda.md`, 회사 정책용 `references/policies.md`, API 사양용 `references/api_docs.md` - **사용 사례**: 데이터베이스 스키마, API 문서, 도메인 지식, 회사 정책, 상세 워크플로우 가이드 - **이점**: SKILL.md를 간결하게 유지하고, Claude가 필요하다고 판단할 때만 로드 - **모범 사례**: 파일이 큰 경우(10,000단어 초과), SKILL.md에 grep 검색 패턴을 포함하세요. - **중복 방지**: 정보는 SKILL.md 또는 references 파일 중 한 곳에만 있어야 하며, 둘 다에 있으면 안 됩니다. ##### 에셋 (`assets/`) 컨텍스트에 로드하기 위한 것이 아니라 Claude가 생성하는 출력 내에서 사용되는 파일입니다. - **포함 시기**: 스킬이 최종 출력에 사용될 파일이 필요할 때 - **예시**: 브랜드 에셋용 `assets/logo.png`, PowerPoint 템플릿용 `assets/slides.pptx` - **사용 사례**: 템플릿, 이미지, 아이콘, 보일러플레이트 코드, 글꼴, 샘플 문서 ### 점진적 공개 설계 원칙 스킬은 컨텍스트를 효율적으로 관리하기 위해 3단계 로딩 시스템을 사용합니다: 1. **메타데이터 (name + description)** - 항상 컨텍스트에 있음 (약 100단어) 2. **SKILL.md 본문** - 스킬이 트리거될 때 (5,000단어 미만) 3. **번들 리소스** - Claude가 필요에 따라 SKILL.md 본문을 필수 사항으로 유지하고 500줄 미만으로 유지하여 컨텍스트 비대화를 최소화하세요. ## 스킬 생성 프로세스 스킬 생성은 다음 단계를 포함합니다: 1. 구체적인 예시로 스킬 이해하기 2. 재사용 가능한 스킬 콘텐츠 계획하기 (스크립트, 참조 자료, 에셋) 3. 스킬 초기화하기 (init_skill.py 실행) 4. 스킬 편집하기 (리소스 구현 및 SKILL.md 작성) 5. 스킬 패키징하기 (package_skill.py 실행) 6. 실제 사용에 기반하여 반복하기 ### 3단계: 스킬 초기화 새 스킬을 처음부터 만들 때는 항상 `init_skill.py` 스크립트를 실행하세요: ```bash scripts/init_skill.py <skill-name> --path <output-directory> ``` ### 4단계: 스킬 편집 스킬의 필요에 따라 다음 유용한 가이드를 참조하세요: - **다단계 프로세스**: 순차 워크플로우 및 조건부 로직은 references/workflows.md 참조 - **특정 출력 형식 또는 품질 기준**: 템플릿 및 예시 패턴은 references/output-patterns.md 참조 ### 5단계: 스킬 패키징 ```bash scripts/package_skill.py <path/to/skill-folder> ``` 패키징 스크립트는 배포용 .skill 파일을 검증하고 생성합니다. FILE:references/workflows.md # 워크플로우 패턴 ## 순차 워크플로우 복잡한 작업의 경우 작업을 명확한 순차 단계로 나누세요. SKILL.md의 시작 부분에서 Claude에게 프로세스 개요를 제공하는 것이 도움이 되는 경우가 많습니다: ```markdown PDF 양식 작성에는 다음 단계가 포함됩니다: 1. 양식 분석 (analyze_form.py 실행) 2. 필드 매핑 생성 (fields.json 편집) 3. 매핑 검증 (validate_fields.py 실행) 4. 양식 작성 (fill_form.py 실행) 5. 출력 확인 (verify_output.py 실행) ``` ## 조건부 워크플로우 분기 로직이 있는 작업의 경우 결정 지점을 통해 Claude를 안내하세요: ```markdown 1. 수정 유형 결정: **새 콘텐츠 생성?** → 아래 "생성 워크플로우"를 따르세요 **기존 콘텐츠 편집?** → 아래 "편집 워크플로우"를 따르세요 2. 생성 워크플로우: [단계] 3. 편집 워크플로우: [단계] ``` FILE:references/output-patterns.md # 출력 패턴 스킬이 일관되고 고품질의 출력을 생성해야 할 때 다음 패턴을 사용하세요. ## 템플릿 패턴 출력 형식에 대한 템플릿을 제공하세요. 필요에 맞게 엄격함 수준을 조정하세요. **엄격한 요구사항(API 응답 또는 데이터 형식 등)의 경우:** ```markdown ## 보고서 구조 항상 이 정확한 템플릿 구조를 사용하세요: # [분석 제목] ## 요약 [주요 발견 사항에 대한 한 단락 개요] ## 주요 발견 사항 - 데이터가 포함된 발견 사항 1 - 데이터가 포함된 발견 사항 2 - 데이터가 포함된 발견 사항 3 ## 권장 사항 1. 구체적인 실행 가능한 권장 사항 2. 구체적인 실행 가능한 권장 사항 ``` **유연한 지침(적응이 유용한 경우)의 경우:** ```markdown ## 보고서 구조 다음은 합리적인 기본 형식이지만, 최선의 판단을 사용하세요: # [분석 제목] ## 요약 [개요] ## 주요 발견 사항 [발견한 내용에 따라 섹션 조정] ## 권장 사항 [특정 컨텍스트에 맞게 조정] 특정 분석 유형에 따라 섹션을 필요에 맞게 조정하세요. ``` ## 예시 패턴 출력 품질이 예시를 보는 것에 의존하는 스킬의 경우 입력/출력 쌍을 제공하세요: ```markdown ## 커밋 메시지 형식 다음 예시에 따라 커밋 메시지를 생성하세요: **예시 1:** 입력: JWT 토큰으로 사용자 인증 추가 출력: ``` feat(auth): JWT 기반 인증 구현 로그인 엔드포인트 및 토큰 검증 미들웨어 추가 ``` **예시 2:** 입력: 보고서에서 날짜가 잘못 표시되는 버그 수정 출력: ``` fix(reports): 시간대 변환 시 날짜 형식 수정 보고서 생성 전반에 걸쳐 UTC 타임스탬프 일관되게 사용 ``` 다음 스타일을 따르세요: type(scope): 간단한 설명, 그 다음 상세 설명. ``` 예시는 설명만으로보다 원하는 스타일과 세부 수준을 Claude가 더 명확하게 이해하는 데 도움이 됩니다. FILE:scripts/quick_validate.py #!/usr/bin/env python3 """ 스킬용 빠른 검증 스크립트 - 최소 버전 """ import sys import os import re import yaml from pathlib import Path def validate_skill(skill_path): """스킬의 기본 검증""" skill_path = Path(skill_path) # SKILL.md 존재 확인 skill_md = skill_path / 'SKILL.md' if not skill_md.exists(): return False, "SKILL.md를 찾을 수 없습니다" # 프론트매터 읽기 및 검증 content = skill_md.read_text() if not content.startswith('---'): return False, "YAML 프론트매터가 없습니다" # 프론트매터 추출 match = re.match(r'^---\n(.*?)\n---', content, re.DOTALL) if not match: return False, "프론트매터 형식이 잘못되었습니다" frontmatter_text = match.group(1) # YAML 프론트매터 파싱 try: frontmatter = yaml.safe_load(frontmatter_text) if not isinstance(frontmatter, dict): return False, "프론트매터는 YAML 사전이어야 합니다" except yaml.YAMLError as e: return False, f"프론트매터의 YAML이 잘못되었습니다: {e}" # 허용 속성 정의 ALLOWED_PROPERTIES = {'name', 'description', 'license', 'allowed-tools', 'metadata'} # 예상치 못한 속성 확인 (metadata 아래의 중첩 키 제외) unexpected_keys = set(frontmatter.keys()) - ALLOWED_PROPERTIES if unexpected_keys: return False, ( f"SKILL.md 프론트매터에 예상치 못한 키가 있습니다: {', '.join(sorted(unexpected_keys))}. " f"허용 속성은 다음과 같습니다: {', '.join(sorted(ALLOWED_PROPERTIES))}" ) # 필수 필드 확인 if 'name' not in frontmatter: return False, "프론트매터에 'name'이 없습니다" if 'description' not in frontmatter: return False, "프론트매터에 'description'이 없습니다" # 검증을 위한 name 추출 name = frontmatter.get('name', '') if not isinstance(name, str): return False, f"name은 문자열이어야 합니다. 현재 유형: {type(name).__name__}" name = name.strip() if name: # 명명 규칙 확인 (하이픈 케이스: 소문자와 하이픈) if not re.match(r'^[a-z0-9-]+$', name): return False, f"name '{name}'은 하이픈 케이스여야 합니다 (소문자, 숫자, 하이픈만 허용)" if name.startswith('-') or name.endswith('-') or '--' in name: return False, f"name '{name}'은 하이픈으로 시작/끝날 수 없으며 연속 하이픈을 포함할 수 없습니다" # name 길이 확인 (사양에 따라 최대 64자) if len(name) > 64: return False, f"name이 너무 깁니다 ({len(name)}자). 최대 64자입니다." # description 추출 및 검증 description = frontmatter.get('description', '') if not isinstance(description, str): return False, f"description은 문자열이어야 합니다. 현재 유형: {type(description).__name__}" description = description.strip() if description: # 꺾쇠 괄호 확인 if '<' in description or '>' in description: return False, "description에는 꺾쇠 괄호(< 또는 >)를 포함할 수 없습니다" # description 길이 확인 (사양에 따라 최대 1024자) if len(description) > 1024: return False, f"description이 너무 깁니다 ({len(description)}자). 최대 1024자입니다." return True, "스킬이 유효합니다!" if __name__ == "__main__": if len(sys.argv) != 2: print("사용법: python quick_validate.py <skill_directory>") sys.exit(1) valid, message = validate_skill(sys.argv[1]) print(message) sys.exit(0 if valid else 1) FILE:scripts/init_skill.py #!/usr/bin/env python3 """ 스킬 초기화 도구 - 템플릿에서 새 스킬 생성 사용법: init_skill.py <skill-name> --path <path> 예시: init_skill.py my-new-skill --path skills/public init_skill.py my-api-helper --path skills/private init_skill.py custom-skill --path /custom/location """ import sys from pathlib import Path SKILL_TEMPLATE = """--- name: {skill_name} description: [TODO: 스킬이 무엇을 하는지와 언제 사용해야 하는지에 대한 완전하고 유익한 설명. 이 스킬을 언제 사용해야 하는지 - 특정 시나리오, 파일 유형 또는 트리거하는 작업을 포함하세요.] --- # {skill_title} ## 개요 [TODO: 이 스킬이 무엇을 가능하게 하는지에 대한 1-2문장 설명] ## 리소스 이 스킬에는 다양한 유형의 번들 리소스를 구성하는 방법을 보여주는 예시 리소스 디렉토리가 포함되어 있습니다: ### scripts/ 특정 작업을 수행하기 위해 직접 실행할 수 있는 실행 가능한 코드(Python/Bash 등). ### references/ Claude의 프로세스와 사고를 안내하기 위해 컨텍스트에 로드되는 문서 및 참조 자료. ### assets/ 컨텍스트에 로드하기 위한 것이 아니라 Claude가 생성하는 출력 내에서 사용되는 파일. --- **필요 없는 디렉토리는 삭제할 수 있습니다.** 모든 스킬이 세 가지 유형의 리소스를 모두 요구하는 것은 아닙니다. """ EXAMPLE_SCRIPT = '''#!/usr/bin/env python3 """ {skill_name}용 예시 도우미 스크립트 직접 실행할 수 있는 자리 표시자 스크립트입니다. 실제 구현으로 교체하거나 필요하지 않으면 삭제하세요. """ def main(): print("{skill_name}용 예시 스크립트입니다") # TODO: 실제 스크립트 로직을 여기에 추가하세요 if __name__ == "__main__": main() ''' EXAMPLE_REFERENCE = """# {skill_title} 참조 문서 상세 참조 문서를 위한 자리 표시자입니다. 실제 참조 콘텐츠로 교체하거나 필요하지 않으면 삭제하세요. """ EXAMPLE_ASSET = """# 예시 에셋 파일 이 자리 표시자는 에셋 파일이 저장되는 위치를 나타냅니다. 실제 에셋 파일(템플릿, 이미지, 글꼴 등)로 교체하거나 필요하지 않으면 삭제하세요. """ def title_case_skill_name(skill_name): """표시용으로 하이픈으로 구분된 스킬 이름을 Title Case로 변환합니다.""" return ' '.join(word.capitalize() for word in skill_name.split('-')) def init_skill(skill_name, path): """템플릿 SKILL.md로 새 스킬 디렉토리를 초기화합니다.""" skill_dir = Path(path).resolve() / skill_name if skill_dir.exists(): print(f"❌ 오류: 스킬 디렉토리가 이미 존재합니다: {skill_dir}") return None try: skill_dir.mkdir(parents=True, exist_ok=False) print(f"✅ 스킬 디렉토리 생성됨: {skill_dir}") except Exception as e: print(f"❌ 디렉토리 생성 오류: {e}") return None skill_title = title_case_skill_name(skill_name) skill_content = SKILL_TEMPLATE.format(skill_name=skill_name, skill_title=skill_title) skill_md_path = skill_dir / 'SKILL.md' try: skill_md_path.write_text(skill_content) print("✅ SKILL.md 생성됨") except Exception as e: print(f"❌ SKILL.md 생성 오류: {e}") return None try: scripts_dir = skill_dir / 'scripts' scripts_dir.mkdir(exist_ok=True) example_script = scripts_dir / 'example.py' example_script.write_text(EXAMPLE_SCRIPT.format(skill_name=skill_name)) example_script.chmod(0o755) print("✅ scripts/example.py 생성됨") references_dir = skill_dir / 'references' references_dir.mkdir(exist_ok=True) example_reference = references_dir / 'api_reference.md' example_reference.write_text(EXAMPLE_REFERENCE.format(skill_title=skill_title)) print("✅ references/api_reference.md 생성됨") assets_dir = skill_dir / 'assets' assets_dir.mkdir(exist_ok=True) example_asset = assets_dir / 'example_asset.txt' example_asset.write_text(EXAMPLE_ASSET) print("✅ assets/example_asset.txt 생성됨") except Exception as e: print(f"❌ 리소스 디렉토리 생성 오류: {e}") return None print(f"\n✅ 스킬 '{skill_name}'이(가) {skill_dir}에 성공적으로 초기화되었습니다") return skill_dir def main(): if len(sys.argv) < 4 or sys.argv[2] != '--path': print("사용법: init_skill.py <skill-name> --path <path>") sys.exit(1) skill_name = sys.argv[1] path = sys.argv[3] print(f"🚀 스킬 초기화 중: {skill_name}") print(f" 위치: {path}") print() result = init_skill(skill_name, path) sys.exit(0 if result else 1) if __name__ == "__main__": main() FILE:scripts/package_skill.py #!/usr/bin/env python3 """ 스킬 패키징 도구 - 스킬 폴더의 배포 가능한 .skill 파일 생성 사용법: python utils/package_skill.py <path/to/skill-folder> [output-directory] 예시: python utils/package_skill.py skills/public/my-skill python utils/package_skill.py skills/public/my-skill ./dist """ import sys import zipfile from pathlib import Path from quick_validate import validate_skill def package_skill(skill_path, output_dir=None): """스킬 폴더를 .skill 파일로 패키징합니다.""" skill_path = Path(skill_path).resolve() if not skill_path.exists(): print(f"❌ 오류: 스킬 폴더를 찾을 수 없습니다: {skill_path}") return None if not skill_path.is_dir(): print(f"❌ 오류: 경로가 디렉토리가 아닙니다: {skill_path}") return None skill_md = skill_path / "SKILL.md" if not skill_md.exists(): print(f"❌ 오류: {skill_path}에서 SKILL.md를 찾을 수 없습니다") return None print("🔍 스킬 검증 중...") valid, message = validate_skill(skill_path) if not valid: print(f"❌ 검증 실패: {message}") print(" 패키징 전에 검증 오류를 수정하세요.") return None print(f"✅ {message}\n") skill_name = skill_path.name if output_dir: output_path = Path(output_dir).resolve() output_path.mkdir(parents=True, exist_ok=True) else: output_path = Path.cwd() skill_filename = output_path / f"{skill_name}.skill" try: with zipfile.ZipFile(skill_filename, 'w', zipfile.ZIP_DEFLATED) as zipf: for file_path in skill_path.rglob('*'): if file_path.is_file(): arcname = file_path.relative_to(skill_path.parent) zipf.write(file_path, arcname) print(f" 추가됨: {arcname}") print(f"\n✅ 스킬이 성공적으로 패키징되었습니다: {skill_filename}") return skill_filename except Exception as e: print(f"❌ .skill 파일 생성 오류: {e}") return None def main(): if len(sys.argv) < 2: print("사용법: python utils/package_skill.py <path/to/skill-folder> [output-directory]") sys.exit(1) skill_path = sys.argv[1] output_dir = sys.argv[2] if len(sys.argv) > 2 else None print(f"📦 스킬 패키징 중: {skill_path}") if output_dir: print(f" 출력 디렉토리: {output_dir}") print() result = package_skill(skill_path, output_dir) sys.exit(0 if result else 1) if __name__ == "__main__": main()