# Claude CLI 완전 가이드 v5: Skills 개념 및 사용법 ## Skills이란? Skills는 Claude의 기능을 확장하는 재사용 가능한 지식 패키지입니다. `SKILL.md` 파일에 전문 지식과 지시사항을 담아 Claude가 특정 작업을 더 잘 수행하도록 합니다. ### 핵심 특징: 자동 활성화 Skills는 **모델이 호출**합니다. 사용자가 직접 명령하지 않아도 Claude가 요청을 분석하여 적절한 Skill을 자동으로 활성화합니다. ``` 사용자: "이 PDF에서 데이터를 추출해줘" Claude: [PDF Processing Skill 자동 활성화] ``` --- ## Skills vs 슬래시 명령어 | 구분 | Skills | 슬래시 명령어 | |------|--------|--------------| | 호출 방식 | 자동 (Claude가 판단) | 수동 (`/command`) | | 활성화 | 요청 내용 기반 | 명시적 명령 | | 용도 | 전문 지식 패키지 | 특정 작업 실행 | | 파일 | `SKILL.md` | `command-name.md` | --- ## Skills의 장점 - **워크플로우 확장**: 프로젝트별 맞춤 기능 - **팀 협업**: Git으로 전문 지식 공유 - **일관성**: 팀원들이 동일한 프로세스 따름 - **효율성**: 반복적인 프롬프트 작성 불필요 - **조합 가능**: 여러 Skills를 복합적으로 활용 --- ## Skills 저장 위치 Claude는 세 위치에서 Skills를 자동 탐색합니다: | 위치 | 범위 | |------|------| | `~/.claude/skills/` | 개인 (모든 프로젝트) | | `.claude/skills/` | 프로젝트 (팀과 Git 공유) | | 플러그인 Skills | 설치된 플러그인 제공 | --- ## Skill 디렉토리 구조 ``` .claude/skills/skill-name/ ├── SKILL.md # 필수: 메인 지시사항 ├── examples/ # 선택: 예제 파일 │ ├── example1.txt │ └── example2.json ├── templates/ # 선택: 템플릿 │ └── template.sql └── scripts/ # 선택: 헬퍼 스크립트 └── helper.js ``` --- ## SKILL.md 작성법 ### 기본 템플릿 ```markdown --- name: skill-name description: 이 Skill이 하는 일과 언제 사용되는지 version: 1.0 tags: - category - use-case --- # Skill 이름 ## 개요 이 Skill이 무엇을 하는지 설명합니다. ## 사용 시점 Claude가 이 Skill을 언제 활성화해야 하는지 명시합니다. ## 단계별 프로세스 1. 첫 번째 단계 2. 두 번째 단계 3. 세 번째 단계 ## 예시 입력과 출력 예시를 제공합니다. ## 주의사항 제한사항이나 특별한 고려사항을 기록합니다. ``` --- ## 프론트매터 옵션 ```yaml --- name: my-skill # Skill 이름 description: 상세 설명 # 활성화 트리거에 중요 version: 1.0 # 버전 tags: # 분류 태그 - database - sql - analytics author: team-name # 작성자 (선택) --- ``` ### description 작성이 핵심 Claude가 Skill을 활성화할지 판단하는 핵심 요소입니다. **나쁜 예:** ```yaml description: 문서 관련 작업 ``` **좋은 예:** ```yaml description: PDF, Word, 이미지 문서에서 구조화된 데이터를 추출합니다. 문서 요약, 데이터 추출, 문서 분석 요청 시 활성화됩니다. ``` --- ## 실전 Skill 예제 ### 예제 1: API 문서 생성 Skill `.claude/skills/api-documenter/SKILL.md`: ```markdown --- name: api-documenter description: Express/Fastify 라우터에서 OpenAPI 스펙 문서를 생성합니다. API 문서화, Swagger 생성, 엔드포인트 문서화 요청 시 활성화됩니다. version: 1.0 tags: - documentation - api - openapi --- # API 문서 생성기 ## 개요 Express 또는 Fastify 라우터 파일을 분석하여 OpenAPI 3.0 스펙을 생성합니다. ## 사용 시점 - "API 문서를 생성해줘" - "Swagger 스펙을 만들어줘" - "엔드포인트를 문서화해줘" ## 프로세스 ### 1. 라우터 파일 분석 - 모든 라우트 핸들러 식별 - HTTP 메서드, 경로, 파라미터 추출 - 요청/응답 스키마 추론 ### 2. OpenAPI 스펙 생성 - paths 섹션 구성 - components/schemas 정의 - 인증 정보 포함 ### 3. 출력 형식 ```yaml openapi: 3.0.0 info: title: API Name version: 1.0.0 paths: /endpoint: get: summary: 설명 parameters: [] responses: '200': description: 성공 ``` ## 주의사항 - TypeScript 타입이 있으면 스키마가 더 정확함 - JSDoc 주석이 있으면 설명에 활용 ``` ### 예제 2: 데이터베이스 쿼리 Skill `.claude/skills/sql-analyzer/SKILL.md`: ```markdown --- name: sql-analyzer description: SQL 쿼리를 분석하고 최적화합니다. 쿼리 성능 개선, 인덱스 제안, 실행 계획 분석 요청 시 활성화됩니다. version: 1.0 tags: - database - sql - optimization --- # SQL 쿼리 분석기 ## 개요 SQL 쿼리의 성능을 분석하고 최적화 방안을 제시합니다. ## 사용 시점 - "이 쿼리가 느린 이유를 분석해줘" - "쿼리 최적화해줘" - "인덱스 추천해줘" ## 분석 프로세스 ### 1. 쿼리 구조 분석 - SELECT, JOIN, WHERE 절 분석 - 서브쿼리 식별 - 테이블 스캔 패턴 확인 ### 2. 성능 병목 식별 - Full table scan 감지 - N+1 쿼리 패턴 - 불필요한 컬럼 선택 - 비효율적인 JOIN ### 3. 최적화 제안 - 인덱스 생성 권장 - 쿼리 리팩토링 - 캐싱 전략 ## 출력 형식 ``` ## 분석 결과 ### 문제점 1. [문제 설명] 2. [문제 설명] ### 권장 인덱스 CREATE INDEX idx_name ON table(column); ### 최적화된 쿼리 [개선된 쿼리] ### 예상 개선 - 실행 시간: 50% 감소 - 메모리 사용: 30% 감소 ``` ``` ### 예제 3: 테스트 전략 Skill `.claude/skills/test-strategist/SKILL.md`: ```markdown --- name: test-strategist description: 코드에 대한 테스트 전략을 수립하고 테스트 케이스를 설계합니다. 테스트 계획, 테스트 커버리지, 테스트 설계 요청 시 활성화됩니다. version: 1.0 tags: - testing - quality - tdd --- # 테스트 전략가 ## 개요 코드를 분석하여 효과적인 테스트 전략을 수립합니다. ## 사용 시점 - "이 함수의 테스트 케이스를 설계해줘" - "테스트 커버리지를 높이려면?" - "어떤 테스트가 필요해?" ## 테스트 설계 프로세스 ### 1. 코드 분석 - 공개 인터페이스 식별 - 의존성 매핑 - 분기점 및 경계값 식별 ### 2. 테스트 유형 결정 | 유형 | 대상 | 도구 | |------|------|------| | 단위 테스트 | 개별 함수/클래스 | Jest, Mocha | | 통합 테스트 | 모듈 간 상호작용 | Jest, Supertest | | E2E 테스트 | 전체 흐름 | Playwright, Cypress | ### 3. 테스트 케이스 설계 각 테스트 케이스 포함: - 설명 (describe/it) - 준비 (Arrange) - 실행 (Act) - 검증 (Assert) ### 4. 우선순위 결정 높음: - 핵심 비즈니스 로직 - 자주 변경되는 코드 - 버그가 발생했던 영역 중간: - 유틸리티 함수 - API 엔드포인트 낮음: - 설정 파일 - 상수 정의 ## 출력 형식 ```markdown ## 테스트 전략 ### 단위 테스트 (12개) - [ ] 정상 입력 처리 - [ ] 빈 입력 처리 - [ ] 경계값 테스트 ... ### 통합 테스트 (5개) - [ ] API-DB 연동 - [ ] 인증 흐름 ... ### 예상 커버리지: 85% ``` ``` ### 예제 4: 코드 리뷰 Skill `.claude/skills/code-reviewer/SKILL.md`: ```markdown --- name: code-reviewer description: 코드의 품질, 보안, 성능을 종합적으로 리뷰합니다. 코드 리뷰, PR 리뷰, 코드 품질 검사 요청 시 활성화됩니다. version: 1.0 tags: - review - quality - security --- # 코드 리뷰어 ## 개요 코드를 다각도로 분석하여 개선점을 제시합니다. ## 사용 시점 - "이 코드를 리뷰해줘" - "PR 검토해줘" - "코드 품질을 확인해줘" ## 리뷰 체크리스트 ### 1. 코드 품질 - [ ] 가독성 - [ ] 네이밍 컨벤션 - [ ] 함수/클래스 크기 - [ ] 중복 코드 - [ ] 주석 품질 ### 2. 보안 - [ ] 입력 검증 - [ ] SQL Injection - [ ] XSS - [ ] 인증/인가 - [ ] 민감 정보 노출 ### 3. 성능 - [ ] 불필요한 연산 - [ ] 메모리 누수 - [ ] N+1 쿼리 - [ ] 캐싱 기회 ### 4. 유지보수성 - [ ] 테스트 용이성 - [ ] 의존성 관리 - [ ] 에러 처리 ## 리뷰 출력 형식 ```markdown ## 코드 리뷰 결과 ### 요약 - 전체 점수: 7/10 - 주요 이슈: 3개 - 제안 사항: 5개 ### 🔴 심각 (즉시 수정 필요) 1. [파일:라인] 이슈 설명 ### 🟡 주의 (개선 권장) 1. [파일:라인] 이슈 설명 ### 💡 제안 (선택적 개선) 1. [파일:라인] 제안 내용 ``` ``` --- ## Skills 활용 팁 ### 1. 명확한 트리거 설명 description에 "~할 때 활성화됩니다"를 명시: ```yaml description: > React 컴포넌트의 성능을 분석합니다. 렌더링 최적화, 메모이제이션, 컴포넌트 성능 관련 요청 시 활성화됩니다. ``` ### 2. 구체적인 출력 형식 정의 일관된 결과를 위해 출력 형식을 템플릿으로 제공: ```markdown ## 출력 형식 항상 다음 형식으로 결과를 제공하세요: ### 분석 결과 ... ### 권장 조치 ... ``` ### 3. 예제 파일 활용 `examples/` 디렉토리에 참고 자료 포함: ``` .claude/skills/my-skill/ ├── SKILL.md └── examples/ ├── good-example.js └── bad-example.js ``` SKILL.md에서 참조: ```markdown ## 좋은 예시 @examples/good-example.js 를 참고하세요. ``` ### 4. 팀 공유 프로젝트 Skills는 Git으로 버전 관리: ```bash git add .claude/skills/ git commit -m "Add SQL analyzer skill" ``` --- ## 다음 단계 v5에서는 Skills의 개념과 작성법을 다뤘습니다. **다음 v6에서는**: - MCP (Model Context Protocol) 서버란? - MCP 서버 설정 방법 - 외부 서비스 연동 (GitHub, Notion 등) 를 상세히 알아봅니다. --- ## 빠른 참조 ``` Skills 위치: 개인: ~/.claude/skills/skill-name/SKILL.md 프로젝트: .claude/skills/skill-name/SKILL.md SKILL.md 구조: --- name: skill-name description: 상세한 설명과 활성화 트리거 version: 1.0 tags: [tag1, tag2] --- # 개요 # 사용 시점 # 프로세스 # 예시 # 주의사항 핵심: description이 자동 활성화의 핵심! ``` --- *Claude CLI 완전 가이드 시리즈 v5/10*