Claude Skills

Claude Skill은 특정 작업 유형에 대한 지식과 절차를 담는 재사용 단위입니다.

디렉터리 이름이 직접 호출 이름이 되며, description은 Claude가 자동으로 사용할지 판단하는 핵심 단서입니다.

.claude/skills/
└── api-design/
    └── SKILL.md

.claude/skills/
└── api-design/
    └── SKILL.md

# SKILL.md 
---
name: api-design
description: API 엔드포인트 설계와 구현 시 사용. RESTful 컨벤션과 팀 응답 포맷을 따라야 할 때 적용.
allowed-tools: Read Grep Bash
---

## API 설계 규칙
- 모든 응답은 JSON으로 반환
- 에러 포맷은 `{ error, code, details? }` 유지
- 컨트롤러에 비즈니스 로직을 직접 넣지 않음

# SKILL.md 
---
name: api-design
description: API 엔드포인트 설계와 구현 시 사용. RESTful 컨벤션과 팀 응답 포맷을 따라야 할 때 적용.
allowed-tools: Read Grep Bash
---

## API 설계 규칙
- 모든 응답은 JSON으로 반환
- 에러 포맷은 `{ error, code, details? }` 유지
- 컨트롤러에 비즈니스 로직을 직접 넣지 않음

Skill에 넣기 좋은 내용은 다음과 같습니다.

3회 이상 반복되는 작업 절차
API 설계, 테스트 작성, 문서화, 배포, 커밋 준비 같은 플레이북
팀 컨벤션, 도메인 지식, 예시, 체크리스트
필요할 때만 읽을 참고 문서와 실행 스크립트

LLM이 자동으로 스킬을 이용하지 않고 사용자가 수동으로만 실행해야 하는 작업은 disable-model-invocation: true를 formatter(— — 사이) 부분에 추가합니다.

예를 들어 배포, 커밋, 외부 전송처럼 부작용이 큰 작업은 Claude가 자동으로 판단해 실행하지 않게 막는 것이 안전합니다.

핵심 요약 #

Skill은 Claude Code에게 특정 작업 방식, 체크리스트, 규칙, 도구 사용 절차를 재사용 가능한 형태로 알려주는 폴더 기반 확장 기능입니다.
기본 구조는 <skill-name>/SKILL.md입니다. SKILL.md가 필수 entrypoint입니다.
Skill은 사용자가 /skill-name으로 직접 호출할 수도 있고, Claude가 description과 when_to_use를 보고 관련 상황에서 자동으로 불러올 수도 있습니다.
최신 Claude Code에서는 custom commands가 skills에 통합되었습니다. 즉 .claude/commands/deploy.md와 .claude/skills/deploy/SKILL.md는 둘 다 /deploy를 만들고 같은 방식으로 작동합니다.
기존 .claude/commands/ 파일은 계속 작동하지만, 새로 만들 때는 보조 파일, 스크립트, 자동 호출 제어를 지원하는 skills 방식이 권장됩니다.
단, “반드시 실행되어야 하는 규칙”은 skill보다 hook이 더 적합합니다. Skill은 Claude가 선택하거나 사용자가 호출하는 지침이고, hook은 Claude Code lifecycle 특정 시점에 자동 실행되는 결정적 제어 장치입니다.

언제 Skill을 만들면 좋을까요 #

Skill은 아래 상황에 적합합니다.

매번 같은 지침을 Claude에게 붙여 넣고 있습니다.
특정 프로젝트에서 반복되는 작업 절차가 있습니다.
CLAUDE.md에 적은 내용이 단순한 배경지식이 아니라 “절차”나 “워크플로우”가 되었습니다.
/review-pr, /write-tests, /summarize-changes, /generate-docs처럼 명령처럼 호출하고 싶은 작업이 있습니다.
필요한 참고 문서, 예시, 스크립트를 함께 묶어두고 싶습니다.

반대로 아래 상황은 hook을 먼저 고려합니다.

특정 Bash 명령 실행 전에 반드시 검사해야 합니다.
파일 수정 후 항상 formatter를 돌려야 합니다.
보호된 파일 편집을 항상 차단해야 합니다.
git commit, git push, deploy 같은 위험 작업 전에 규칙을 강제해야 합니다.

Claude Skill 폴더 구조 #

프로젝트 전용 skill (추천):

.claude/
  skills/
    my-skill/
      SKILL.md

.claude/
  skills/
    my-skill/
      SKILL.md

개인 전역 skill:

~/.claude/
  skills/
    my-skill/
      SKILL.md

~/.claude/
  skills/
    my-skill/
      SKILL.md

보조 파일이 있는 구조:

.claude/
  skills/
    my-skill/
      SKILL.md
      reference.md
      examples.md
      scripts/
        helper.sh

.claude/
  skills/
    my-skill/
      SKILL.md
      reference.md
      examples.md
      scripts/
        helper.sh

중요한 점:

skill 폴더명은 slash command 이름이 됩니다. 예: .claude/skills/summarize-changes/SKILL.md → /summarize-changes
SKILL.md 파일명이 필수입니다. my-skill.md처럼 작성하면 인식되지 않을 수 있습니다.
SKILL.md 외 파일은 선택입니다.
reference.md, examples.md, scripts/ 등은 필요할 때만 Claude가 읽거나 실행하도록 구성합니다.

최소 SKILL.md 예시 #

---
name: summarize-changes
description: Summarizes uncommitted git changes and flags risky edits. Use when the user asks what changed, wants a commit message, or asks to review the current diff.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes in two or three bullet points.
Then list risks such as missing tests, hardcoded values, or unrelated changes.
If there are no changes, say there are no uncommitted changes.

---
name: summarize-changes
description: Summarizes uncommitted git changes and flags risky edits. Use when the user asks what changed, wants a commit message, or asks to review the current diff.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes in two or three bullet points.
Then list risks such as missing tests, hardcoded values, or unrelated changes.
If there are no changes, say there are no uncommitted changes.

설명:

name: skill 표시 이름입니다. 생략하면 디렉터리 이름을 사용합니다.
description: Claude가 언제 이 skill을 사용할지 판단하는 핵심 설명입니다.
!git diff HEAD: dynamic context injection입니다. Claude가 skill 내용을 읽기 전에 명령을 실행하고 결과를 본문에 주입합니다.

git-mannage-skill를 만든다고 가정하면 아래와 같은 구조로 만들어 줍니다.

이제 클로드 코드에서 slash(/)를 입력하고 skills 하위 디렉토리명을 입력하면 해당 스킬을 사용할 수 있습니다.

frontmatter 필드 #

---
name: my-skill
description: What this skill does and when to use it.
when_to_use: Additional trigger examples or situations.
argument-hint: "[issue-number] [branch-name]"
arguments: [issue, branch]
disable-model-invocation: true
user-invocable: true
allowed-tools: Bash(git status *) Bash(git diff *) Read Grep
context: fork
agent: Explore
---

---
name: my-skill
description: What this skill does and when to use it.
when_to_use: Additional trigger examples or situations.
argument-hint: "[issue-number] [branch-name]"
arguments: [issue, branch]
disable-model-invocation: true
user-invocable: true
allowed-tools: Bash(git status *) Bash(git diff *) Read Grep
context: fork
agent: Explore
---

주요 필드:

name: skill 이름입니다. 소문자, 숫자, 하이픈 중심으로 작성합니다.
description: 가장 중요합니다. “무엇을 하는지”와 “언제 써야 하는지”를 함께 적습니다.
when_to_use: trigger 문구나 사용 상황을 추가로 적습니다.
argument-hint: /skill-name 자동완성에 보일 인자 힌트입니다.
arguments: $issue, $branch처럼 named argument를 사용할 수 있게 합니다.
disable-model-invocation: true: Claude가 자동으로 이 skill을 실행하지 못하게 합니다. 사용자가 직접 /skill-name으로 호출해야 합니다.
user-invocable: false: slash menu에서는 숨기고 Claude만 내부적으로 사용하게 합니다.
allowed-tools: skill 실행 중 사전 승인할 도구 범위를 제한합니다.
context: fork: 별도 subagent context에서 실행합니다.
agent: context: fork와 함께 사용할 subagent 유형을 지정합니다.

Commands와 Skills의 통합 #

최신 Claude Code 문서 기준으로 custom commands는 skills에 통합되었습니다.

예전 방식:

.claude/
  commands/
    deploy.md

.claude/
  commands/
    deploy.md

새 skill 방식:

.claude/
  skills/
    deploy/
      SKILL.md

.claude/
  skills/
    deploy/
      SKILL.md

두 방식 모두 /deploy를 만듭니다.

다만 skills 방식이 더 확장성이 좋습니다.

보조 파일을 skill 폴더 안에 함께 넣을 수 있습니다.
description, when_to_use, disable-model-invocation, user-invocable 등으로 호출 방식을 더 세밀하게 제어할 수 있습니다.
Claude가 상황을 보고 자동으로 skill을 불러올 수 있습니다.
scripts/, reference.md, examples.md 등을 통해 복잡한 워크플로우를 구성할 수 있습니다.

주의할 점:

공식 Claude Code 문서에서 말하는 “commands와 skills 통합”은 .claude/commands/*.md와 .claude/skills/*/SKILL.md가 같은 slash command 인터페이스로 동작한다는 의미입니다.
skill의 slash command 이름은 기본적으로 skill 디렉터리 이름에서 나옵니다.

AI를 활용한 Skill 생성 #

Skill을 직접 작성해도 되지만, 아래 도구를 활용하면 더 빠르게 만들 수 있습니다.

superpowers의 writing-skills: skill 작성 원칙, 설명문 개선, progressive disclosure 구조화에 활용할 수 있습니다.
gstack의 skill-creator: 원하는 workflow를 설명하면 skill 초안 생성, 폴더 구조 설계, 예시 작성에 활용할 수 있습니다.

AI 코딩 에이전트 Wiki

LangChain/LangGraph

OpenSearch

Claude Skills

핵심 요약 #

언제 Skill을 만들면 좋을까요 #

Claude Skill 폴더 구조 #

최소 SKILL.md 예시 #

frontmatter 필드 #

Commands와 Skills의 통합 #

AI를 활용한 Skill 생성 #

글이 도움이 되셨나요?

답글 남기기 응답 취소

핵심 요약 #

언제 Skill을 만들면 좋을까요 #

Claude Skill 폴더 구조 #

최소 SKILL.md 예시 #

frontmatter 필드 #

Commands와 Skills의 통합 #

AI를 활용한 Skill 생성 #

글이 도움이 되셨나요?

공유하기

답글 남기기 응답 취소