claudekit / guides / build-skill
[ Guide · Advanced · 12분 ]

Skill 직접 만들기

published · updated

자신만의 Skill을 직접 만드는 방법을 단계별로 안내합니다. 파일 위치, description 작성법, 좋은 예시 참고 방법까지 다룹니다.

Skill이란?

Skill은 SKILL.md 파일에 적은 지침으로 Claude의 작업 방식을 확장하는 기능입니다. 본문에 절차, 규칙, 점검 항목을 적어두면 Claude가 관련 작업에서 그 절차대로 작업하고, 사용자는 /skill-name으로 직접 실행할 수도 있습니다. CLAUDE.md와 달리 본문은 실제로 사용될 때만 불러오므로, 긴 참고 자료를 넣어도 평소에는 컨텍스트를 거의 차지하지 않습니다.

기존 커스텀 커맨드는 Skill로 통합됐습니다. .claude/commands/deploy.md와 .claude/skills/deploy/SKILL.md는 둘 다 /deploy를 만들고 같은 방식으로 동작하며, 기존 커맨드 파일도 계속 작동합니다. Skill은 frontmatter로 훅, 허용 도구, 서브에이전트 실행 등을 지정할 수 있어 단순한 문서 이상의 동작도 정의할 수 있습니다. 여러 Skill과 에이전트, 훅, MCP 서버를 묶어 배포하려면 Plugin을 사용합니다.

파일 구조

~/.claude/skills/<skill-name>/
├── SKILL.md          # 필수 — frontmatter + 본문
└── (보조 파일)        # 선택 — 참고 자료, 템플릿 등

SKILL.md 기본 형식

---
name: <skill-name>
description: <Claude가 이 Skill을 호출할 조건을 구체적으로 명시>
---

# Skill 제목

## 언제 사용하나
이 Skill이 호출되어야 하는 상황 명시.

## 절차
1. 첫 단계
2. 두 번째 단계
3. ...

## 점검 항목
- [ ] 항목 1
- [ ] 항목 2

name은 생략하면 디렉터리 이름이 기본값이 됩니다.

자주 쓰는 추가 frontmatter

필드용도
disable-model-invocation: trueClaude가 자동으로 불러오지 않고, 사용자가 /name으로 실행할 때만 동작
user-invocable: false/ 메뉴에서 숨기고 Claude만 사용 (배경 지식용)
pathsglob 패턴과 일치하는 파일을 다룰 때만 자동으로 불러옴
allowed-toolsSkill이 실행되는 턴에서 권한 확인 없이 쓸 도구 지정

description의 중요성

description은 Claude가 Skill을 호출할지 결정하는 핵심 신호입니다. 스킬 목록에서는 description과 when_to_use를 합친 텍스트가 1,536자에서 잘리므로 핵심 용도를 앞에 둡니다. 좋은 description의 특징:

  • 트리거 조건 명시 — “X 작업 시”, “Y 파일을 다룰 때”
  • 기능명과 키워드 포함 — 사용자가 실제로 쓸 표현
  • 부정 조건도 명시 (선택) — “단, Z인 경우는 제외”

좋은 예

description: |
  Use when creating or modifying SQL migration files in db/migrations/.
  Enforces naming convention (timestamp_description.sql), reversibility,
  and schema review checklist. Skip for read-only queries.

나쁜 예

description: Database stuff  # 너무 일반적, 호출 조건 불명확

본문 작성 원칙

1. 절차는 번호 매겨 명시

Claude는 번호 매겨진 절차를 더 정확히 따릅니다.

2. 금지 사항은 굵게

**절대 하지 말 것**:
- 마이그레이션 파일을 직접 삭제
- ALTER TABLE 없이 컬럼 변경

3. 검증 단계 포함

## 검증
- 마이그레이션 적용 후 `npm test`
- 롤백 테스트: `npm run db:rollback && npm run db:migrate`

4. 외부 링크는 절대 경로

본문에 다른 Skill이나 문서를 참조할 때 명확히 표시합니다.

실전 예: 콘텐츠 검토 Skill

---
name: review-content
description: |
  Use when reviewing or modifying content files in src/content/.
  Checks frontmatter schema, ko/en pair consistency, link validity,
  and applies the project quality rules.
---

# Content Review

## 실행 시점
- 콘텐츠 파일을 생성, 수정한 후
- 배포 전 최종 검토

## 절차
1. frontmatter 스키마 위반 확인
2. ko/en 페어 정합성 (slug, dates 동일)
3. 외부 링크 유효성
4. 본문 톤 일관성

## 검증
\```bash
npm run build
\```

Skill을 두는 위치

위치적용 범위
~/.claude/skills/<name>/SKILL.md내 모든 프로젝트 (이 컴퓨터)
.claude/skills/<name>/SKILL.md이 저장소의 세션. 커밋하면 팀 전체가 사용
플러그인 내 skills/<name>/SKILL.md플러그인이 활성화된 곳. /plugin-name:skill-name으로 실행
관리 설정(managed settings) 디렉터리의 .claude/skills/조직이 배포한 컴퓨터의 모든 사용자

팀과 공유하려면 프로젝트의 .claude/skills/를 커밋하고, 여러 저장소나 공개 배포가 필요하면 플러그인으로 묶어 마켓플레이스에 등록합니다.

Claude Code는 Skill 디렉터리를 감시하므로 SKILL.md를 추가하거나 고치면 재시작 없이 현재 세션에 반영됩니다. 세션 시작 후에 새로 만든 최상위 skills 디렉터리는 /reload-skills로 불러옵니다.

흔한 실수

  • ❌ description이 너무 짧음 — Claude가 트리거 못함
  • ❌ 본문이 산문(에세이) 스타일 — 절차로 분리 필요
  • ❌ 너무 광범위한 Skill — 한 Skill = 한 절차 원칙
  • ❌ 다른 Skill과 트리거 조건 충돌 — 명확히 구분

다음 단계

§ 10

자주 묻는 질문

자주 묻는 질문
§ 10.1
Skill은 무엇인가요?
`SKILL.md` 파일에 지침을 적어 두면 Claude가 관련 작업에서 자동으로 불러오거나, 사용자가 `/skill-name`으로 직접 실행할 수 있는 확장 기능입니다. frontmatter의 description으로 사용 조건을 정의하고, 본문에 절차와 규칙을 적습니다.
§ 10.2
Plugin과 무엇이 다른가요?
Skill은 하나의 절차나 지식 단위이고, Plugin은 Skill, 에이전트, 훅, MCP 서버 등을 묶어 배포하는 패키지입니다. 기존 커스텀 커맨드(`.claude/commands/`)는 Skill로 통합되어, Skill 하나만으로도 `/name` 명령을 만들 수 있습니다.
§ 10.3
어떻게 만들고 어디에 두나요?
`<skill-name>/SKILL.md` 형태로 디렉터리와 파일을 만듭니다. `~/.claude/skills/`에 두면 내 모든 프로젝트에서, 프로젝트의 `.claude/skills/`에 두고 커밋하면 팀 전체가 사용하며, 플러그인으로 묶어 배포할 수도 있습니다.
§ 10.4
description은 왜 중요한가요?
description은 Claude가 Skill을 적용할지 결정하는 핵심 신호입니다. 호출 조건을 구체적으로 적어야 정확하게 발동하며, 스킬 목록에서는 description과 when_to_use를 합친 텍스트가 1,536자에서 잘리므로 핵심 용도를 앞에 둡니다.
§ 10.5
기존 Skill 좋은 예시가 있나요?
Jesse Vincent가 만든 superpowers 플러그인(obra/superpowers)의 Skills(brainstorming, systematic-debugging, writing-plans 등)가 참고하기 좋은 예시입니다. description, 본문 구조, 절차 명시 방식을 참고할 수 있습니다.