1.2 Skills 만들기

각 플랫폼에서 SKILL.md 파일을 작성하고 호출하는 방법, Skills 2.0 심화 기능까지 단계별로 설명한다. 업데이트: 2026-03-08

핵심 요약

구분	내용
📖 정의	SKILL.md 파일을 지정 경로에 생성하면 해당 스킬이 즉시 활성화된다
💡 핵심	플랫폼마다 저장 경로·호출 방식이 다르며, 고급 옵션은 Claude Code 전용이다
🎯 대상	반복 작업을 스킬로 자동화하려는 개발자
⚠️ 주의	배포·삭제 등 부작용이 있는 작업은 `disable-model-invocation: true`로 자동 실행을 막는 것이 권장된다

문서 탐색

이전	다음
2.1.1 Skills란?	2.1.3 Skills 예제

1. Claude Code Skills 만들기

저장 위치

위치	경로	사용 범위
글로벌	`~/.claude/skills/스킬이름/`	모든 프로젝트
프로젝트	`.claude/skills/스킬이름/`	해당 프로젝트만

팀원과 공유하려면 .claude/skills/를 git에 커밋하면 된다. git pull 즉시 사용 가능하다.

SKILL.md 기본 구조

---
name: skill-name                    # 슬래시 커맨드명 (/skill-name)
description: "설명"                  # Claude가 언제 이 스킬 쓸지 판단하는 기준
disable-model-invocation: true       # Claude 자동호출 금지 (나만 수동 호출)
user-invocable: false               # 사용자 수동호출 금지 (Claude만 자동 호출)
context: fork                       # [2.0] 격리된 컨텍스트에서 실행
hooks:                              # [2.0] 스킬 전용 훅
  PreToolUse:
    - command: "echo '시작'"
  Stop:
    - command: "echo '종료'"
allowed-tools:
  - Read
  - Write
  - Bash
---
 
## 지시사항
 
Claude에게 내릴 상세한 지시

옵션 선택 기준

상황	설정
배포, 커밋처럼 직접 실행해야 할 작업	`disable-model-invocation: true`
Claude의 배경 지식으로만 쓰고 싶은 정보	`user-invocable: false`
메인 세션과 격리하여 안전하게 실행	`context: fork` (Skills 2.0)
스킬 실행 중에만 훅 적용	`hooks:` 섹션 추가 (Skills 2.0)
둘 다 호출 가능 (기본값)	옵션 생략

호출 방법

/skill-name         ← 슬래시 커맨드로 직접 호출

/를 입력하면 사용 가능한 스킬 목록이 자동으로 나타난다. 또는 대화 맥락에서 Claude가 필요하다고 판단하면 자동 실행된다.

공개 스킬 설치

# Anthropic 공식 스킬 저장소에서 설치
git clone https://github.com/anthropics/skills
cp -r skills/skills/skill-creator ~/.claude/skills/

내장 스킬

/simplify   ← 최근 수정한 코드의 품질·재사용성·효율성 자동 검토 및 수정

Skills 2.0 — Claude Code 전용 심화 기능

📌 Skills 2.0은 Claude Code 전용이다. Gemini CLI · OpenAI Codex에는 아직 해당 기능들이 없다.

Skills 2.0 = 격리 실행 + 실시간 반영 + 측정 가능한 최적화

릴리스	주요 내용
Claude Code 2.1.0	Context Fork, Hot Reload, Agent-Scoped Hooks
Skills 2.0 (Skill Creator)	Evals 기반 평가, A/B 테스트, 스킬 유형 분류

Context Fork — 격리 실행

스킬이 현재 세션과 독립된 격리 환경에서 실행된다. Git의 브랜치처럼, 스킬이 메인 세션 상태를 오염시키지 않는다.

flowchart TD
    subgraph s1["Skills 1.0 — 메인 세션 공유"]
        A1["메인 세션"] --> B1["스킬 실행 (공유)"] --> C1["메인 세션에 영향 가능"]
    end
    subgraph s2["Skills 2.0 — context: fork 격리"]
        A2["메인 세션"] --> B2["(스냅샷)"] --> C2["포크된 서브에이전트"] --> D2["격리 실행"] --> E2["메인 세션 영향 없음"]
    end

---
name: risky-refactor
context: fork   # ← 이 한 줄로 격리 실행
---

사용 적합한 경우: DB 마이그레이션 테스트 / 대규모 리팩토링 실험 / 실패해도 현재 작업 보존이 필요한 경우

Hot Reload — 즉시 반영

스킬 파일을 수정하면 Claude Code 재시작 없이 즉시 반영된다.

flowchart TD
    subgraph v1["Skills 1.0"]
        A1["SKILL.md 수정"] --> B1["저장"] --> C1["/exit"] --> D1["claude 재실행"] --> E1["스킬 테스트"]
    end
    subgraph v2["Skills 2.0 (Hot Reload)"]
        A2["SKILL.md 수정"] --> B2["저장"] --> C2["/my-skill (바로 새 버전!)"]
    end

Agent-Scoped Hooks — 스킬 전용 훅

SKILL.md 프런트매터에 스킬 생애주기 전용 훅을 직접 정의한다. 스킬이 실행되는 동안에만 활성화되고, 종료 시 자동 해제된다.

---
name: deploy-prod
hooks:
  PreToolUse:
    - command: "echo '[$(date)] 배포 시작' >> audit.log"
  PostToolUse:
    - command: "echo '[$(date)] 툴 사용' >> audit.log"
  Stop:
    - command: "echo '[$(date)] 배포 완료' >> audit.log && notify-slack"
---

Evals + A/B 테스트 — 측정 가능한 품질

skill-creator 스킬을 통해 구조화된 평가(Evals)와 A/B 테스트가 가능하다.

flowchart TD
    A["/skill-creator 실행"] --> B["스킬 목적과 예상 동작 설명"]
    B --> C["Claude가 SKILL.md 초안 생성"]
    C --> D["Evals 케이스 자동 생성"]
    D --> E["A/B 테스트로 두 버전 비교"]
    E --> F["성공률 높은 버전 채택"]

스킬 유형 분류 (Skills 2.0 공식 카테고리)

유형	설명	예시
Capability Uplift	모델의 기본 기능을 확장	외부 API 호출, 전문 지식 주입, 특수 도구 통합
Workflow/Preference	반복 작업 자동화 + 개인/팀 설정	커밋, 배포, 코드 리뷰, 컨벤션 적용

~/.claude/skills/
├── capability-uplift/
│   ├── web-search/
│   └── domain-expert/
└── workflow/
    ├── smart-commit/
    └── deploy-prod/

Skills 1.0 vs 2.0 비교

항목	Skills 1.0	Skills 2.0
실행 환경	메인 세션 공유	격리된 독립 컨텍스트 (`context: fork`)
스킬 수정 반영	세션 재시작 필요	즉시 반영 (Hot Reload)
훅(Hooks)	전역/프로젝트 범위만	스킬별 독립 훅 지원
성능 측정	없음	Evals + A/B 테스트
스킬 분류	없음	Capability Uplift / Workflow
에이전트	기본	커스텀 에이전트 타입 지정 가능
스킬 탐색	파일 시스템 직접 확인	`/` 메뉴 자동 통합

2. Gemini CLI Skills 만들기

저장 위치

위치	경로	사용 범위
글로벌	`~/.gemini/skills/스킬이름/`	모든 프로젝트
프로젝트	`.gemini/skills/스킬이름/`	해당 프로젝트만

SKILL.md 구조

Claude Code와 거의 동일하다. name과 description만 필수다.

---
name: skill-name
description: "이 스킬이 어떤 역할을 하는지 설명"
---
 
## 지시사항
 
Gemini에게 내릴 상세한 지시

my-skill/
├── SKILL.md
├── scripts/      ← 실행 스크립트
├── resources/    ← 참고 문서, 데이터
└── assets/       ← 기타 리소스

호출 방법

Gemini CLI는 수동 슬래시 커맨드가 없다. 자동 호출만 지원한다. Gemini가 대화를 분석해서 스킬이 필요하다고 판단하면 내부적으로 activate_skill 도구를 통해 자동 실행한다.

"코드 리뷰해줘" → Gemini가 code-review 스킬 자동 활성화

수동 호출이 없으므로 description을 더 구체적으로 작성해야 정확하게 자동 호출된다.

스킬 설치

gemini skill install ./my-skill/
gemini skill install https://github.com/user/my-skill
gemini skill install https://github.com/anthropics/skills   # Anthropic 공식 스킬과 호환!

Claude Code 전용 옵션은 무시됨

Claude Code 옵션	Gemini CLI 동작
`disable-model-invocation`	무시됨
`user-invocable`	무시됨
`context: fork`	무시됨
`hooks`	무시됨 (별도 Hooks 시스템 사용)

3. OpenAI Codex Skills 만들기

저장 위치

위치	경로	사용 범위
글로벌	`~/.codex/skills/스킬이름/`	모든 프로젝트
프로젝트	`.codex/skills/스킬이름/`	해당 프로젝트만

SKILL.md 구조

---
name: skill-name
description: "이 스킬이 어떤 역할을 하는지 설명"
---
 
## 지시사항
 
Codex에게 내릴 상세한 지시

UI 메타데이터가 필요하면 agents/openai.yaml을 추가로 만들 수 있다:

my-skill/
├── SKILL.md
└── agents/
    └── openai.yaml    ← 아이콘, 카테고리 등 UI 메타데이터

호출 방법

$skill-name         ← 달러 사인으로 직접 호출

또는 자동 호출:

"배포해줘" → Codex가 deploy 스킬 자동 선택

$를 입력하면 스킬 목록이 나타난다.

내장 스킬

$skill-creator    ← 스킬 설명 입력 → SKILL.md 자동 생성
$skill-installer  ← 원격 스킬 설치 도우미

4. 플랫폼별 Skills 만들기 비교 요약

항목	Claude Code	Gemini CLI	OpenAI Codex
저장 경로 (프로젝트)	`.claude/skills/`	`.gemini/skills/`	`.codex/skills/`
저장 경로 (글로벌)	`~/.claude/skills/`	`~/.gemini/skills/`	`~/.codex/skills/`
수동 호출	`/skill-name`	없음	`$skill-name`
자동 호출	description 기반	description 기반	description 기반
고급 옵션	`disable-model-invocation` · `user-invocable` · `context: fork` · `hooks`	없음 (기본만)	없음 (기본만)
원격 설치	직접 복사	`gemini skill install URL`	`$skill-installer`
스킬 생성 도우미	`/skill-creator` (Skills 2.0)	없음	`$skill-creator`
타 플랫폼 호환	—	Claude Code 스킬 호환 O	제한적

5. 💡 Skills 작성 팁

Tip 1. description을 잘 작성하면 AI가 자동으로 활용한다 (전 플랫폼)

description 필드는 AI가 “이 스킬을 언제 쓸지” 판단하는 유일한 기준이다.

# 나쁜 예시 — AI가 언제 써야 할지 모름
description: "코드 도구"
 
# 좋은 예시 — 구체적인 상황, 트리거, 기대 행동 명시
description: "TypeScript 파일에서 타입 오류, 미사용 변수, 안전하지 않은 any 사용을 검사하고 수정한다"

Gemini CLI는 수동 호출이 없으므로 description이 특히 중요하다.

Tip 2. 부작용 있는 작업은 `disable-model-invocation` 설정 (Claude Code 전용)

배포, 파일 삭제처럼 돌이키기 어려운 작업은 Claude가 자동으로 실행하지 않도록 설정이 필요하다.

---
name: deploy-prod
description: "프로덕션 환경에 배포"
disable-model-invocation: true   # ← 반드시 추가!
---

Gemini CLI · Codex는 이 옵션이 없으므로, description에 “사용자 명시적 호출 시에만 실행”이라고 명시한다.

Tip 3. 하나의 스킬, 하나의 역할 (전 플랫폼)

# 나쁜 패턴: 모든 기능을 하나에 몰아넣기
super-skill/SKILL.md  ← 코드 리뷰 + 배포 + 문서 생성 + 테스트 다 들어있음

# 좋은 패턴: 역할별로 분리
skills/
├── code-review/SKILL.md
├── deploy/SKILL.md
├── generate-docs/SKILL.md
└── run-tests/SKILL.md

Tip 4. 스킬 이름은 동사로 시작하게 (전 플랫폼)

나쁜 이름	좋은 이름
`review`	`review-code`
`deploy`	`deploy-prod`
`docs`	`generate-docs`

팁별 플랫폼 적용 가능 여부

팁	Claude Code	Gemini CLI	OpenAI Codex
1. description 상세하게	O	O (특히 중요)	O
2. disable-model-invocation	O	X	X
3. 하나의 역할	O	O	O
4. 동사 이름	O	O	O
5. 공개 스킬 참고	O	O (Anthropic 스킬 호환)	O

문서 탐색

이전	다음
2.1.1 Skills란?	2.1.3 Skills 예제

JW's AI_Stash

Explorer

2.1.2 Skills 만들기

1.2 Skills 만들기

핵심 요약

문서 탐색

목차

1. Claude Code Skills 만들기

저장 위치

SKILL.md 기본 구조

옵션 선택 기준

호출 방법

공개 스킬 설치

내장 스킬

Skills 2.0 — Claude Code 전용 심화 기능

2. Gemini CLI Skills 만들기

저장 위치

SKILL.md 구조

호출 방법

스킬 설치

Claude Code 전용 옵션은 무시됨

3. OpenAI Codex Skills 만들기

저장 위치

SKILL.md 구조

호출 방법

내장 스킬

4. 플랫폼별 Skills 만들기 비교 요약

5. 💡 Skills 작성 팁

Tip 1. description을 잘 작성하면 AI가 자동으로 활용한다 (전 플랫폼)

Tip 2. 부작용 있는 작업은 `disable-model-invocation` 설정 (Claude Code 전용)

Tip 3. 하나의 스킬, 하나의 역할 (전 플랫폼)

Tip 4. 스킬 이름은 동사로 시작하게 (전 플랫폼)

팁별 플랫폼 적용 가능 여부

문서 탐색

참고 자료

Graph View

Table of Contents

Backlinks

JW's AI_Stash

Explorer

2.1.2 Skills 만들기

1.2 Skills 만들기

핵심 요약

문서 탐색

목차

1. Claude Code Skills 만들기

저장 위치

SKILL.md 기본 구조

옵션 선택 기준

호출 방법

공개 스킬 설치

내장 스킬

Skills 2.0 — Claude Code 전용 심화 기능

2. Gemini CLI Skills 만들기

저장 위치

SKILL.md 구조

호출 방법

스킬 설치

Claude Code 전용 옵션은 무시됨

3. OpenAI Codex Skills 만들기

저장 위치

SKILL.md 구조

호출 방법

내장 스킬

4. 플랫폼별 Skills 만들기 비교 요약

5. 💡 Skills 작성 팁

Tip 1. description을 잘 작성하면 AI가 자동으로 활용한다 (전 플랫폼)

Tip 2. 부작용 있는 작업은 disable-model-invocation 설정 (Claude Code 전용)

Tip 3. 하나의 스킬, 하나의 역할 (전 플랫폼)

Tip 4. 스킬 이름은 동사로 시작하게 (전 플랫폼)

팁별 플랫폼 적용 가능 여부

문서 탐색

참고 자료

Graph View

Table of Contents

Backlinks

Tip 2. 부작용 있는 작업은 `disable-model-invocation` 설정 (Claude Code 전용)