🛠️ 03. 클로드코드 스킬 활용

2편에서 skills.sh로 스킬을 설치했다면, 이제 진짜 중요한 단계는 “클로드코드에서 그 스킬을 어떻게 제대로 쓰는가”다. 핵심은 어렵지 않다. 스킬은 AI에게 주는 작전 카드라고 생각하면 된다. 필요할 때 자동으로 꺼내 쓰게 하거나, 내가 /스킬이름으로 직접 호출하면 된다.

안내: 본문에는 생성형 AI 도구를 활용한 요약/정리 내용이 포함되어 있습니다.

flowchart LR
A[2편: 스킬 설치] --> B[3편: 클로드코드에서 호출]
B --> C{호출 방식}
C -->|자동| D[설명문(description) 매칭]
C -->|수동| E[/skill-name]
D --> F[결과 검증]
E --> F
F --> G[팀 표준으로 고정]

먼저 그림부터: 스킬은 “직업 카드”다

게임에서 캐릭터가 기본 공격만 하면 느리고 실수가 많다. 그런데 직업 카드(힐러, 탱커, 정찰병)를 붙이면 상황에 맞는 행동을 빠르게 한다.

클로드코드도 똑같다.

• 기본 모델: “두루두루 아는” 상태
• 스킬 적용: “이 상황에서는 이렇게 일해”가 붙은 상태

즉, 스킬은 모델을 교체하는 게 아니라 일하는 습관을 주입하는 방법이다.

---

클로드코드 스킬의 공식 핵심 4가지

Claude Code 공식 Skills 문서 기준으로 초보자는 아래 4가지만 먼저 잡으면 된다.

1. 스킬은 SKILL.md가 핵심 파일이다.
2. 스킬은 자동 호출도 되고(/description 매칭), 수동 호출(/skill-name)도 된다.
3. 스킬 폴더 위치에 따라 적용 범위가 달라진다.
4. 위험한 작업은 disable-model-invocation, allowed-tools로 안전하게 제한한다.

---

1) 어디에 두면 어디까지 적용될까?

공식 문서 기준 경로는 아래처럼 이해하면 가장 쉽다.

• 개인 공용: ~/.claude/skills/<skill-name>/SKILL.md
  • 내 모든 프로젝트에서 사용
• 프로젝트 전용: .claude/skills/<skill-name>/SKILL.md
  • 현재 프로젝트에서만 사용

어린이 비유로 말하면:

• 개인 공용 = 내 필통에 넣은 공통 도구
• 프로젝트 전용 = 이번 과학 숙제에만 쓰는 특별 준비물

참고: 같은 이름 스킬이 여러 레벨에 있으면 우선순위 규칙(enterprise > personal > project)이 적용된다. (공식 문서)

---

2) 가장 작은 스킬 1개부터 만들기

공식 예시 흐름을 그대로 줄이면 아래처럼 시작하면 된다.

mkdir -p ~/.claude/skills/explain-code

~/.claude/skills/explain-code/SKILL.md

---
name: explain-code
description: 코드 동작을 쉬운 비유와 단계로 설명할 때 사용
---
 
코드를 설명할 때 아래 순서를 지켜라.
1. 먼저 일상 비유 1개
2. 처리 흐름을 단계로 설명
3. 초보자가 실수하는 포인트 1개

이후 테스트는 2가지:

• 자동 호출: “이 코드 어떻게 동작해?”
• 수동 호출: /explain-code src/auth/login.ts

---

칠판 판서형 치트시트

클로드코드 스킬 5줄 요약

1. 스킬 = SKILL.md 한 장으로 시작
2. description이 자동 호출 힌트 역할
3. 급하면 /skill-name으로 직접 호출
4. 위험 작업은 disable-model-invocation: true
5. 결과는 항상 “전/후 비교”로 검증

---

3) 자동 호출 vs 수동 호출, 언제 뭘 쓰면 좋나?

flowchart TD
A[문제 인지: 매번 같은 요청 반복?] --> B{영향도}
B -->|부작용 거의 없음| C[자동 호출 허용]
B -->|배포/커밋/외부전송 포함| D[수동 호출 전용]
C --> E[description 구체화]
D --> F[disable-model-invocation true]
E --> G[실행/검증]
F --> G

자동 호출이 좋은 경우

• 코드 설명
• 스타일 가이드 반영
• 문서 포맷 정리

수동 호출이 좋은 경우

• 배포
• 커밋 생성
• 외부 시스템 전송

공식 문서의 핵심 필드:

• disable-model-invocation: true → 모델 자동 호출 차단
• user-invocable: false → / 메뉴에서 숨기고 모델만 쓰게 함

---

4) 초보자가 바로 쓰는 안전 설정 3종

A. 자동 호출 차단

---
name: deploy
description: 운영 배포 수행
disable-model-invocation: true
---

B. 도구 제한

---
name: safe-reader
description: 읽기 전용 탐색
allowed-tools: Read Grep Glob
---

C. 인자 받기

---
name: fix-issue
description: 이슈 번호 기반 수정
---
 
이슈 $ARGUMENTS 를 해결하라.

예: /fix-issue 123

---

5) 2편과 연결되는 실전 루틴 (20분)

2편에서 설치한 스킬이 있다면, 아래 루틴으로 바로 “사용 단계”까지 완성된다.

0~5분: 스킬 1개 선택

• 설치된 스킬 중 실제로 자주 쓸 1개 선택
• 선택 기준: 반복 빈도 + 위험도 낮음

5~10분: description 문장 보정

• 너무 넓은 설명은 자동 오작동을 만든다
• “언제 쓰는지”를 문장에 넣는다

예)

• 나쁜 설명: 코드를 도와준다
• 좋은 설명: 리액트 컴포넌트 리팩터링 요청일 때만 사용

10~15분: 자동/수동 둘 다 테스트

• 자동: 자연어 질문으로 호출
• 수동: /skill-name 직접 호출

15~20분: 전/후 비교 기록

• 정확성
• 일관성
• 수정 횟수
• 재현성

---

실무 미니 사례 2개

사례 1) 성공: 코드 설명 스킬

• Before: 팀마다 설명 방식이 달라 리뷰 시간이 길어짐
• After: explain-code 스킬로 비유 + 흐름 + 주의점 포맷 고정
• 효과: 온보딩 문서 품질이 일정해짐

사례 2) 실패 후 개선: 배포 스킬 자동 호출

• Before: 배포 스킬을 자동 호출 허용해 불필요한 배포 시도 발생
• 조치: disable-model-invocation: true 설정
• 결과: 배포는 사람 승인 후 /deploy로만 실행

---

MECE 한눈에 정리 (개념/원인/대응/실행)

• 개념: 스킬은 모델을 바꾸는 기능이 아니라, 작업 절차를 재사용하는 운영 레이어다.
• 원인: 설치만 하고 호출 규칙을 안 정하면 자동 오작동(과호출/누락)이 생긴다.
• 대응: description 구체화 + disable-model-invocation/allowed-tools로 안전선 설정.
• 실행: 20분 루틴으로 자동/수동 테스트 후 전·후 지표를 기록해 팀 표준으로 고정.

---

많이 헷갈리는 포인트 정리

Q1. .claude/commands와 .claude/skills는 뭐가 달라?

공식 문서 기준으로 지금은 커스텀 커맨드가 스킬 개념으로 통합되었다. 기존 .claude/commands/*.md도 동작하지만, 새 구성은 .claude/skills/<name>/SKILL.md가 확장성이 좋다.

Q2. 스킬이 너무 자주 튀어나와요

• description을 더 좁게 쓴다
• 필요하면 disable-model-invocation: true

Q3. 왜 어떤 스킬은 안 보이지?

공식 문서에 따르면 스킬 설명도 컨텍스트 예산 안에서 관리된다. 스킬 수가 많으면 일부가 제외될 수 있다. 이때 스킬 수를 줄이거나 구체적으로 정리해야 한다.

---

2편 → 3편 연결 한 줄 정리

2편이 “설치”였다면, 3편은 “운영”이다. 설치만 하면 반쪽이고, 호출 규칙 + 안전 설정 + 검증 루틴까지 붙여야 진짜 실무 품질이 나온다.

다음 읽기

• 🛠️ 02. skills.sh 설치 및 실행
• 🛠️ 클로드코드 03. 운영스택
• insights 명령어 정리

---

출처 (공식/참고)

공식 소스

• Claude Code Skills Docs: https://code.claude.com/docs/en/skills
• Claude Agent SDK Slash Commands: https://platform.claude.com/docs/en/agent-sdk/slash-commands
• Agent Skills Specification: https://agentskills.io/specification
• Anthropic Skills Repository: https://github.com/anthropics/skills

참고 페이지

• Claude Code Customization Guide (Alex Op): https://alexop.dev/posts/claude-code-customization-guide-claudemd-skills-subagents/
• How I use Claude Code (Builder.io): https://www.builder.io/blog/claude-code