Skill 중급 — 실전 스킬 만들기

이 페이지를 보기 전에

이 페이지는 Skill 입문 페이지를 먼저 읽었다는 전제로 작성되었습니다.
Claude Code가 설치되어 있어야 합니다. 아직이라면 23단계 체크리스트에서 설치 방법을 확인하세요.

STEP 01 : TYPES

두 가지 스킬 유형 이해하기

Claude Code 스킬은 "참고서"와 "레시피" 두 종류가 있습니다

Reference 스킬 (참고서)

"이건 우리 회사 규칙이야. 참고해서 일해."
Claude가 읽고 참고만 합니다.

비유: 새로 들어온 직원에게 주는 회사 매뉴얼.
직원이 매번 펼쳐보면서 일하는 것.

코딩 스타일 가이드, 브랜드 톤앤매너, 프로젝트 구조 설명

Task 스킬 (레시피)

"이 명령어를 치면, 이 순서대로 실행해."
Claude가 직접 행동합니다.

비유: 요리 레시피. "/볶음밥"이라고 하면
재료 준비부터 완성까지 순서대로 실행.

/report 치면 보고서 생성, /deploy 치면 배포 실행

한눈에 비교

구분	Reference 스킬 (참고서)	Task 스킬 (레시피)
작동 방식	Claude가 자동으로 읽고 참고	사용자가 명령어를 입력하면 실행
호출 방법	자동 (별도 명령 불필요)	`/명령어` 입력
비유	회사 매뉴얼을 항상 옆에 두기	"이거 해줘"라고 시키기
실제 예시	코딩 컨벤션, 브랜드 가이드	보고서 생성, 코드 리뷰, 배포

어떤 걸 써야 할까?

"Claude가 항상 알고 있어야 하는 규칙" → Reference 스킬
"특정 명령어를 치면 실행되는 작업" → Task 스킬

STEP 02 : SKILL.MD

Reference 스킬 작성법

frontmatter(머리글)의 각 필드를 제대로 이해하면 스킬 품질이 달라집니다

--- name: 프론트엔드 코딩 컨벤션 description: | 우리 팀의 프론트엔드 코딩 규칙입니다. React 컴포넌트 작성, 네이밍, 폴더 구조를 이 규칙에 맞춰 작업하세요. --- # 프론트엔드 코딩 컨벤션 ## 네이밍 규칙 - 컴포넌트: PascalCase (UserProfile.tsx) - 함수: camelCase (getUserData) - 상수: UPPER_SNAKE (MAX_RETRY_COUNT) ## 폴더 구조 - components/ → 재사용 UI 컴포넌트 - pages/ → 라우팅 페이지 - hooks/ → 커스텀 훅 - utils/ → 유틸리티 함수

핵심 포인트

Reference 스킬에는 command 필드가 없습니다.
Claude가 관련 작업을 할 때 자동으로 참고합니다.

Task 스킬 작성법

command, arguments, allowed-tools 필드를 활용하면 강력한 자동화가 가능합니다

--- name: 주간 보고서 생성기 description: 팀의 주간 업무를 양식에 맞춰 보고서로 정리합니다 command: /report # ← 이 명령어로 실행! arguments: # ← 사용자가 추가로 넘기는 정보 - name: period description: 보고 기간 (예: "2월 3주차") required: true allowed-tools: # ← Claude가 쓸 수 있는 도구 제한 - Read - Write - Bash(git log*) --- # 주간 보고서 생성기 ## Instructions 1. git log로 이번 주 커밋 내역을 수집합니다 2. 수집한 내용을 아래 양식으로 정리합니다 3. reports/ 폴더에 마크다운 파일로 저장합니다 ## Output Format # 주간 보고서 - {period} ## 완료된 작업 ## 진행 중인 작업 ## 다음 주 계획

⚡

command

실행 명령어
예: /report

📋

arguments

사용자 입력 정보
선택/필수 지정 가능

🔒

allowed-tools

Claude 도구 제한
보안에 유용

STEP 03 : STRUCTURE

스킬 폴더 구조 설계하기

SKILL.md 파일 하나가 아니라, 폴더째로 관리하면 더 강력합니다

.claude/ └── skills/ ← 모든 스킬이 들어가는 폴더 ├── weekly-report/ ← 주간 보고서 스킬 │ ├── SKILL.md ← 스킬 정의 파일 (필수!) │ └── template.md ← 보고서 양식 템플릿 ├── code-review/ ← 코드 리뷰 스킬 │ ├── SKILL.md │ └── checklist.md ← 리뷰 체크리스트 └── coding-convention/ ← Reference 스킬 (자동 참고) └── SKILL.md

왜 폴더 구조가 중요한가?

SKILL.md 안에 모든 내용을 넣으면 너무 길어집니다. 양식 파일, 예시 파일 등을 별도 파일로 분리하면 SKILL.md에서 "template.md를 참고해서 작성해"라고만 쓰면 됩니다.

프로젝트 vs 전역 스킬

스킬을 어디에 넣느냐에 따라 적용 범위가 달라집니다

프로젝트 스킬

프로젝트 폴더 안 .claude/skills/에 넣으면
이 프로젝트에서만 작동합니다.

프로젝트별 보고서 양식, 코딩 규칙

전역 스킬

홈 폴더 ~/.claude/skills/에 넣으면
모든 프로젝트에서 작동합니다.

이메일 양식, 개인 작업 스타일

STEP 04 : PRACTICE

실전 실습: /todo 스킬 만들기

따라하면서 첫 Task 스킬을 완성합니다. 5분이면 됩니다.

스킬 폴더 생성

Claude Code에서 아래 명령어를 입력합니다.

mkdir -p .claude/skills/todo-manager

SKILL.md 파일 생성

Claude Code에서 이렇게 요청하세요.

.claude/skills/todo-manager/SKILL.md 파일을 만들어줘. 내용: --- name: TODO 관리자 description: 프로젝트의 할 일 목록을 관리합니다 command: /todo arguments: - name: action description: "add, list, done 중 하나" required: true - name: task description: "할 일 내용 (add 시 필수)" required: false --- # TODO 관리자 ## Instructions 1. action이 "add"이면: TODO.md 파일에 새 항목 추가 2. action이 "list"이면: TODO.md 파일의 현재 목록 표시 3. action이 "done"이면: 해당 항목에 체크 표시 ## Format - [ ] 미완료 항목 - [x] 완료된 항목

테스트해봅니다

각각 실행해보세요. TODO.md 파일이 자동으로 생성되고 관리됩니다!

/todo add "프로젝트 기획서 초안 작성" /todo list /todo done "프로젝트 기획서 초안 작성"

축하합니다!

첫 Task 스킬을 만들었습니다. 이제 /todo만 치면 할 일 관리가 자동으로 됩니다. 이 원리를 응용하면 어떤 반복 작업이든 스킬로 만들 수 있습니다.

STEP 05 : HOOKS

Hooks: 스킬 실행 전후에 자동 작업 추가

스킬이 실행될 때 자동으로 무언가를 하고 싶다면 Hooks를 사용합니다

Hooks가 뭔가요?

스킬이 실행되기 전(pre)이나 후(post)에 자동으로 실행되는 명령어입니다.
비유: 요리 레시피 실행 전에 "손 씻기"가 자동으로 실행되는 것과 같습니다.

Hooks 설정 방법

{ "hooks": { // 스킬 실행 전에 자동으로 할 일 "pre-skill": [ { "command": "echo '스킬 실행 시작: $(date)' >> .claude/skill-log.txt", "description": "스킬 실행 시각을 로그에 기록" } ], // 스킬 실행 후에 자동으로 할 일 "post-skill": [ { "command": "echo '스킬 실행 완료: $(date)' >> .claude/skill-log.txt", "description": "스킬 완료 시각을 로그에 기록" } ] } }

자주 쓰는 Hooks 패턴

📝

실행 로그 남기기

누가 언제 어떤 스킬을
실행했는지 기록

📋

결과물 자동 복사

스킬 실행 후 결과물을
클립보드에 자동 복사

🔍

입력값 검증

스킬 실행 전 필요한
파일/설정 자동 체크

참고

Hooks는 셸(터미널) 명령어입니다. 복잡한 로직이 필요하면 별도 스크립트 파일을 만들어서 실행하는 것을 추천합니다.

비개발자도 Hooks를 쓸 수 있어요!

위의 JSON 코드를 직접 쓸 필요 없습니다. Claude Code에 이렇게 요청하세요.

"스킬 실행할 때마다 시간과 이름을 로그 파일에 기록하는 hook을 설정해줘"

→ Claude가 settings.json을 자동으로 수정해 줍니다.

STEP 06 : DEBUG

스킬이 안 될 때: 디버깅 체크리스트

스킬이 예상대로 작동하지 않을 때 확인할 5가지

SKILL.md 위치가 맞나요?

반드시 .claude/skills/스킬이름/SKILL.md 경로에 있어야 합니다.
파일 이름은 정확히 SKILL.md (대문자)여야 합니다.

frontmatter 형식이 맞나요?

---로 시작하고 ---로 끝나야 합니다. YAML 문법 오류(들여쓰기, 콜론 빠짐)를 확인하세요.

command 필드가 있나요? (Task 스킬만)

Task 스킬은 command: /명령어가 반드시 있어야 합니다. 없으면 Reference 스킬로 취급됩니다.

Claude Code를 재시작해보세요

스킬 파일을 수정한 후에는 Claude Code를 재시작해야 변경사항이 반영될 수 있습니다.

"이 스킬 읽어봐"라고 물어보세요

Claude Code에 .claude/skills/ 폴더에 있는 스킬 목록을 보여줘라고 하면 인식된 스킬을 확인할 수 있습니다.

흔한 실수 TOP 3

❌ SKILL.md 파일 이름을 소문자로 쓴 경우 ▼

원인: skill.md, Skill.md 등 소문자로 쓰면 Claude가 인식하지 못합니다.
해결: 반드시 SKILL.md (모두 대문자)로 이름을 지정하세요.

❌ frontmatter에서 들여쓰기를 잘못한 경우 ▼

원인: YAML 문법에서는 탭이 아닌 스페이스로 들여쓰기해야 합니다.
해결: 들여쓰기를 스페이스 2칸으로 통일하고, 콜론(:) 뒤에 반드시 스페이스를 넣으세요.

❌ command에 / 를 빼먹은 경우 ▼

원인: command: report처럼 슬래시 없이 쓰면 명령어로 인식되지 않습니다.
해결: 반드시 command: /report처럼 슬래시(/)를 포함해서 적으세요.

스킬 만들기에 익숙해졌다면, 고급 패턴으로!

동적 컨텍스트 주입, 변수 치환, CI/CD 연동까지.
스킬을 진짜 자동화 도구로 만드는 방법을 배워보세요.

← 스킬 입문으로 돌아가기 🚀 스킬 고급으로 →