본문으로 건너뛰기
Kreath Archive
TechProjectsBooksAbout
TechProjectsBooksAbout

내비게이션

  • Tech
  • Projects
  • Books
  • About
  • Tags

카테고리

  • AI / ML
  • 웹 개발
  • 프로그래밍
  • 개발 도구

연결

  • GitHub
  • Email
  • RSS
© 2026 Kreath Archive. All rights reserved.Built with Next.js + MDX
홈TechProjectsBooksAbout
//
  1. 홈
  2. 테크
  3. 6장: 커스텀 슬래시 명령어와 스킬 만들기
2026년 2월 25일·개발 도구·

6장: 커스텀 슬래시 명령어와 스킬 만들기

Claude Code의 스킬 시스템을 이해하고, 반복 작업을 자동화하는 커스텀 슬래시 명령어를 설계하고 구현하는 방법을 다룹니다.

15분227자7개 섹션
ai-agentanthropicmcpautomationdevtools
공유
claude-code-guide6 / 10
12345678910
이전5장: 훅(Hooks)으로 자동화 파이프라인 구축하기다음7장: MCP 서버 연동으로 외부 도구 통합하기

스킬 시스템 개요

Claude Code의 스킬(Skills)은 재사용 가능한 명령어 패키지입니다. /commit, /review-pr과 같은 슬래시 명령어를 통해 호출되며, 복잡한 작업을 일관된 방식으로 수행하도록 사전 정의된 지시를 담고 있습니다.

스킬이 해결하는 문제는 명확합니다. 같은 유형의 작업을 매번 긴 프롬프트로 설명하는 대신, 한 번 정의해 두면 슬래시 명령어 하나로 호출할 수 있습니다.

// 매번 이렇게 입력하는 대신
"현재 staging된 변경사항을 분석해서 Conventional Commits 형식으로 
커밋 메시지를 작성하고, 한글로 써 줘. 변경 범위가 넓으면 
feat/fix/refactor 중 가장 적합한 것을 선택해 줘."

// 이렇게 한 줄로 호출
/commit

스킬 vs 명령어 (역사적 맥락)

Claude Code는 초기에 "명령어(commands)"와 "스킬(skills)"을 별도 개념으로 운영했습니다. 명령어는 .claude/commands/ 디렉토리에 마크다운 파일로 저장했고, 스킬은 .claude/skills/ 디렉토리에 SKILL.md와 보조 파일들을 담는 구조였습니다.

현재는 두 시스템이 통합되어, 어느 위치에 파일을 두든 동일한 슬래시 명령어 인터페이스로 접근할 수 있습니다. 하지만 스킬 디렉토리 구조가 더 많은 기능을 지원하므로 권장됩니다.

기능명령어 (.claude/commands/)스킬 (.claude/skills/)
슬래시 명령어 생성지원지원
YAML 프론트매터미지원지원
보조 파일 (템플릿 등)미지원지원
자동 호출미지원지원
동적 컨텍스트 주입미지원지원
에이전트 모드미지원지원

스킬 구조

스킬은 .claude/skills/ 디렉토리에 하위 폴더로 구성됩니다. 각 스킬 폴더에는 반드시 SKILL.md 파일이 포함되어야 합니다.

.claude/
  skills/
    commit/
      SKILL.md          # 스킬 정의 (필수)
    review/
      SKILL.md
      checklist.md      # 보조 파일 (선택)
    create-component/
      SKILL.md
      template.tsx      # 템플릿 파일 (선택)

SKILL.md 구조

SKILL.md는 YAML 프론트매터와 마크다운 본문으로 구성됩니다.

.claude/skills/commit/SKILL.md
markdown
---
name: commit
description: "Git 변경사항을 분석하고 Conventional Commits 형식으로 커밋합니다"
user-invocable: true
---
 
# 커밋 스킬
 
## 실행 절차
 
1. `git status`와 `git diff --staged`로 변경사항을 확인합니다
2. 변경의 성격을 분석합니다 (신규 기능, 버그 수정, 리팩터링 등)
3. Conventional Commits 형식으로 커밋 메시지를 작성합니다
4. 커밋 메시지는 한글로 작성합니다
5. 커밋 전에 사용자에게 메시지를 확인받습니다
 
## 커밋 메시지 형식
 
type: feat | fix | refactor | docs | chore | test | style | perf
형식: `type: 변경 내용을 간결하게 설명 (한글)`
 
## 규칙
- staging된 파일이 없으면 사용자에게 알려줍니다
- .env, credentials 등 민감 파일이 포함되어 있으면 경고합니다
- 변경 범위가 너무 넓으면 분리 커밋을 제안합니다

프론트매터 필드

필드설명기본값
name슬래시 명령어 이름 (/name으로 호출)필수
description스킬 설명 (자동 호출 매칭에 사용)필수
user-invocable사용자가 직접 호출 가능 여부true
disable-model-invocationClaude가 자동으로 호출할 수 없도록 차단false
allowed-tools이 스킬에서 사용 허용할 도구 목록전체
context동적 컨텍스트 주입 셸 명령어없음
agent서브에이전트로 실행 여부false

실전 스킬 제작

1. 코드 리뷰 스킬

.claude/skills/review/SKILL.md
markdown
---
name: review
description: "현재 브랜치의 변경사항을 코드 리뷰합니다"
user-invocable: true
---
 
# 코드 리뷰 스킬
 
## 절차
 
1. `git diff main...HEAD`로 현재 브랜치의 전체 변경사항을 확인합니다
2. 변경된 각 파일을 다음 관점에서 리뷰합니다:
 
### 체크리스트
- **정확성**: 로직이 올바른가
- **타입 안전성**: TypeScript 타입이 적절한가
- **에러 처리**: 예외 상황이 처리되는가
- **보안**: 인젝션, XSS 등 취약점이 없는가
- **성능**: 불필요한 연산이나 메모리 누수가 없는가
- **가독성**: 변수명, 함수명이 의도를 명확히 전달하는가
 
## 출력 형식
파일별로 발견된 이슈를 심각도(critical, warning, suggestion)와 함께 정리합니다.
이슈가 없는 파일은 생략합니다.

2. 컴포넌트 생성 스킬

보조 파일(템플릿)을 활용하는 스킬입니다.

.claude/skills/create-component/SKILL.md
markdown
---
name: create-component
description: "React 컴포넌트를 프로젝트 규칙에 맞게 생성합니다"
user-invocable: true
---
 
# 컴포넌트 생성 스킬
 
사용자가 컴포넌트 이름과 위치를 지정하면, 프로젝트 컨벤션에 맞는 
React 컴포넌트를 생성합니다.
 
## 사용법

/create-component Button components/ui


## 절차

1. 인자에서 컴포넌트 이름과 경로를 파싱합니다
2. 이 디렉토리의 template.tsx를 참고하여 컴포넌트를 생성합니다
3. 파일명은 PascalCase를 사용합니다

## 규칙
- 함수 선언식 사용 (화살표 함수 금지)
- Props 타입은 ComponentNameProps 형식으로 정의
- 'use client'는 필요한 경우에만 추가
- export default 대신 named export 사용
.claude/skills/create-component/template.tsx
tsx
interface ComponentNameProps {
  // props
}
 
function ComponentName({ ...props }: ComponentNameProps) {
  return (
    <div>
      {/* content */}
    </div>
  );
}
 
export { ComponentName };

3. 동적 컨텍스트를 활용하는 스킬

context 필드를 사용하면 스킬 실행 시 셸 명령어의 출력을 컨텍스트로 주입할 수 있습니다.

.claude/skills/fix-ci/SKILL.md
markdown
---
name: fix-ci
description: "CI 실패를 분석하고 수정합니다"
user-invocable: true
context: "gh run list --limit 1 --json conclusion,name,headBranch && gh run view $(gh run list --limit 1 --json databaseId -q '.[0].databaseId') --log-failed 2>/dev/null | tail -50"
---
 
# CI 수정 스킬
 
## 동적 컨텍스트
위의 context 명령어가 자동으로 실행되어 
최근 CI 실행 결과와 실패 로그가 컨텍스트에 주입됩니다.
 
## 절차
 
1. 주입된 CI 로그에서 실패 원인을 분석합니다
2. 관련 파일을 찾아 수정합니다
3. 로컬에서 같은 명령어를 실행하여 수정을 검증합니다
4. 수정 내용을 커밋합니다

4. 에이전트 모드 스킬

agent: true로 설정하면 스킬이 서브에이전트로 실행됩니다. 메인 세션의 컨텍스트를 오염시키지 않으면서 독립적인 작업을 수행할 수 있습니다.

.claude/skills/test-coverage/SKILL.md
markdown
---
name: test-coverage
description: "테스트 커버리지가 낮은 파일을 찾아 테스트를 추가합니다"
user-invocable: true
agent: true
---
 
# 테스트 커버리지 개선 스킬
 
이 스킬은 서브에이전트로 실행되어 메인 세션에 영향을 주지 않습니다.
 
## 절차
 
1. `pnpm test --coverage`를 실행하여 커버리지 리포트를 생성합니다
2. 커버리지가 80% 미만인 파일을 식별합니다
3. 각 파일에 대해 누락된 테스트 케이스를 작성합니다
4. 모든 테스트가 통과하는지 확인합니다
5. 결과 요약을 메인 에이전트에 보고합니다

스킬 설치 위치

스킬은 두 곳에 설치할 수 있으며, 각각 범위가 다릅니다.

위치범위용도
.claude/skills/프로젝트해당 프로젝트에서만 사용
~/.claude/skills/전역모든 프로젝트에서 사용

프로젝트 특화 스킬(컴포넌트 생성, CI 수정 등)은 프로젝트 디렉토리에, 범용 스킬(커밋, 리뷰 등)은 전역 디렉토리에 두는 것이 적절합니다.

스킬 설계 원칙

한 가지 일을 잘 하도록

하나의 스킬이 너무 많은 것을 하면 유지보수가 어려워집니다. "커밋하고 리뷰하고 배포까지" 하는 스킬보다, 각각을 독립적인 스킬로 분리하는 것이 좋습니다.

200줄 이내로 유지

SKILL.md가 길어지면 Claude가 핵심 지시를 놓칠 수 있습니다. 지시는 간결하게, 필요하면 보조 파일에 세부사항을 분리합니다.

명령형으로 작성

스킬은 대화가 아니라 지시서입니다. "다음을 수행합니다"보다 "다음을 수행해 주세요"가 아니라, "다음을 수행한다"와 같은 명령형이 효과적입니다.

비효율적
markdown
변경사항을 확인해 주시고, 커밋 메시지를 작성해 주시면 좋겠습니다.
효율적
markdown
1. `git diff --staged`로 변경사항을 확인한다
2. Conventional Commits 형식으로 커밋 메시지를 작성한다
3. 사용자 확인 후 커밋한다

실패 시나리오를 고려

"staging된 파일이 없으면 어떻게 하는가", "빌드가 실패하면 어떻게 하는가"와 같은 예외 상황에 대한 지시를 포함합니다.

정리

스킬은 Claude Code의 재사용 가능한 작업 단위입니다.

  • SKILL.md 파일의 프론트매터와 마크다운 지시로 정의합니다
  • 보조 파일(템플릿, 체크리스트)을 함께 포함할 수 있습니다
  • context 필드로 동적 정보를 주입하고, agent 필드로 독립 실행이 가능합니다
  • 한 가지 일에 집중하고, 간결하게 유지하며, 실패 시나리오를 고려하는 것이 설계 원칙입니다

다음 장에서는 Claude Code의 확장성을 한 단계 더 끌어올리는 MCP 서버 연동을 다룹니다.

이 글이 도움이 되셨나요?

관련 주제 더 보기

#ai-agent#anthropic#mcp#automation#devtools

관련 글

개발 도구

7장: MCP 서버 연동으로 외부 도구 통합하기

Model Context Protocol의 개념을 이해하고, Claude Code에 MCP 서버를 연결하여 데이터베이스, API, 외부 서비스를 통합하는 방법을 다룹니다.

2026년 2월 27일·13분
개발 도구

5장: 훅(Hooks)으로 자동화 파이프라인 구축하기

Claude Code 훅 시스템의 개념과 라이프사이클을 이해하고, 코드 품질 게이트와 자동화 파이프라인을 구축하는 방법을 다룹니다.

2026년 2월 23일·13분
개발 도구

8장: 서브에이전트와 에이전트 팀 활용하기

Claude Code의 서브에이전트와 에이전트 팀 기능을 이해하고, 복잡한 작업을 병렬로 분할 처리하는 방법을 다룹니다.

2026년 3월 1일·16분
이전 글5장: 훅(Hooks)으로 자동화 파이프라인 구축하기
다음 글7장: MCP 서버 연동으로 외부 도구 통합하기

댓글

목차

약 15분 남음
  • 스킬 시스템 개요
  • 스킬 vs 명령어 (역사적 맥락)
  • 스킬 구조
    • SKILL.md 구조
    • 프론트매터 필드
  • 실전 스킬 제작
    • 1. 코드 리뷰 스킬
    • 2. 컴포넌트 생성 스킬
    • 3. 동적 컨텍스트를 활용하는 스킬
    • 4. 에이전트 모드 스킬
  • 스킬 설치 위치
  • 스킬 설계 원칙
    • 한 가지 일을 잘 하도록
    • 200줄 이내로 유지
    • 명령형으로 작성
    • 실패 시나리오를 고려
  • 정리