Claude code skills란? - 클로드 코드 스킬 만들기 예제(example)

포스팅 개요

본 포스팅은 Claude Code의 Skills 기능에 대해 다루는 글입니다. Claude Code를 사용하다 보면 반복적으로 같은 지시를 내리는 경우가 많습니다. "배포 전에 테스트 돌려줘", "PR 요약해줘", "이 형식으로 로그 남겨줘" 같은 것들이죠. 매번 동일한 프롬프트를 입력하는 건 비효율적이고, 지시 내용이 길어지면 실수가 생기기도 합니다.

 

Claude Code의 Skills는 이런 문제를 해결하기 위해 만들어진 기능입니다. 반복되는 지시사항이나 워크플로우를 SKILL.md 파일로 정의해두면, /skill-name으로 간편하게 호출하거나 Claude가 상황에 맞게 자동으로 불러올 수 있습니다. 쉽게 말해, Claude에게 새로운 능력을 가르쳐주는 기능이라고 보면 됩니다.

 

이 글에서는 Skills의 기본 개념부터 실제로 Skill을 만들어보는 과정, 그리고 실전 예제까지 단계별로 살펴보겠습니다. 글의 마지막에는 고급 활용법도 정리했으니, Claude Code를 좀 더 효율적으로 쓰고 싶은 분들께 도움이 되길 바랍니다.

 

본 포스팅은 Anthropic 공식 문서를 바탕으로 작성되었습니다.

 

• Anthropic 공식 문서 (Skills): https://docs.anthropic.com/ko/docs/claude-code/skills

Claude를 skills로 확장하기 - Claude Code Docs

 

출처: 클로드코드를 Skills로 확장하기

---

포스팅 본문

그러면 지금부터 Claude Code Skills에 대해 하나씩 살펴보겠습니다. 기본 개념부터 시작해서, 왜 필요한지, 어떻게 동작하는지, 그리고 직접 만드는 방법까지 순서대로 진행합니다.

[1]. Skills 기본 개념

Skills는 Claude가 할 수 있는 작업을 확장하는 기능입니다. 기술적으로 말하면, SKILL.md라는 마크다운 파일에 지침을 작성해두면 Claude가 이를 자신의 도구 목록에 추가하는 방식입니다. 사용자가 /skill-name으로 수동 호출할 수도 있고, Claude가 대화 내용을 보고 관련 있다고 판단하면 자동으로 불러오기도 합니다.

 

Skills는 Agent Skills(agentskills.io) 개방형 표준을 따르기 때문에, Claude Code뿐 아니라 다른 AI 도구에서도 활용할 수 있다는 장점이 있습니다.

 

참고로, 기존에 .claude/commands/ 디렉토리에서 사용자 정의 명령어를 만들어 쓰고 계셨다면, 이 기능이 Skills로 병합되었다는 점을 알아두시면 좋을 것 같습니다. 예를 들어 .claude/commands/deploy.md와 .claude/skills/deploy/SKILL.md는 둘 다 /deploy 명령을 생성하며 동일하게 동작합니다. 기존 commands 파일은 계속 작동하니 당장 마이그레이션할 필요는 없지만, 새로 만든다면 Skills 형식을 권장합니다.

 

그런데 Claude Code에는 이미 CLAUDE.md 파일과 .claude/rules/ 디렉토리라는 지시 체계가 있습니다(rules에 대해서는 후속 포스팅에서 소개해볼까 합니다). Skills와 뭐가 다른 걸까요? 핵심적인 차이는 로드 시점입니다.

 

구분	CLAUDE.md	.claude/rules/	Skills
로드 시점	모든 세션 시작 시	모든 세션 시작 시 또는 파일 매칭 시	호출될 때 또는 관련 있을 때
범위	전체 프로젝트	파일 경로별 지정 가능	작업별
용도	핵심 규칙, 빌드 명령	언어별/디렉토리별 가이드라인	참조 자료, 반복 가능한 워크플로우

 

CLAUDE.md와 Rules는 세션이 시작되면 항상 컨텍스트에 올라갑니다. 반면 Skills는 필요할 때만 로드됩니다. 세션 시작 시에는 Skill의 description(설명)만 로드되고, 실제로 호출되었을 때 비로소 전체 내용이 컨텍스트에 올라가는 것이죠. 이 덕분에 컨텍스트 윈도우를 효율적으로 사용할 수 있습니다.

 

정리하면 이렇습니다.

• CLAUDE.md: "항상 이 규칙을 지켜" 같은 상시 지침
• .claude/rules/: "이 파일을 다룰 때는 이 규칙을 따라" 같은 조건부 지침
• Skills: "이 작업을 할 때는 이 방법을 써" 같은 온디맨드 지침

---

[2]. Skills가 필요한 이유

그렇다면 Skills는 왜 필요할까요? 실무에서 체감할 수 있는 이점을 정리해보겠습니다.

 

첫째, 반복 작업을 자동화할 수 있습니다.

매번 "테스트를 돌리고, 빌드하고, 배포해줘"라고 길게 입력하는 대신, /deploy 한 번이면 끝납니다. 코드 리뷰, PR 요약, 커밋 메시지 작성 등 자주 하는 작업을 Skill로 만들어두면 시간을 크게 절약할 수 있습니다.

 

둘째, 컨텍스트 윈도우를 절약할 수 있습니다.

CLAUDE.md에 모든 지침을 넣으면 금방 200줄을 넘게 되고, 그만큼 매 요청마다 토큰이 소비됩니다. Skills는 호출될 때만 전체 내용이 로드되기 때문에, 평소에는 가벼운 설명 한 줄 정도만 컨텍스트를 차지합니다.

 

셋째, 팀과 공유할 수 있습니다.

프로젝트의 .claude/skills/ 디렉토리에 Skill을 넣고 git에 커밋하면, 팀원 모두가 동일한 워크플로우를 사용할 수 있습니다. 개인 전용으로 쓰고 싶다면 ~/.claude/skills/에 넣으면 됩니다. 또는 프로젝트에 있는 .claude/skills에 넣어도 되죠.

 

넷째, Claude가 알아서 적절한 시점에 활용합니다.

Skill의 description을 잘 작성해두면, 사용자가 명시적으로 호출하지 않아도 Claude가 대화 맥락을 보고 자동으로 해당 Skill을 불러옵니다. 예를 들어 "이 코드가 어떻게 동작하는지 설명해줘"라고 하면, explain-code Skill이 자동으로 활성화됩니다.

---

[3]. Skills 동작 방식

Skills의 동작 방식을 이해하려면, 호출 방법과 컨텍스트 로딩 순서를 알아야 합니다.

 

[3-1]. 자동 호출과 수동 호출

Skills를 실행하는 방법은 두 가지입니다.

 

1) 자동 호출 (Model Invocation)

Claude는 세션이 시작될 때 모든 Skill의 description을 읽습니다. 이후 사용자의 요청이 특정 Skill의 description과 매칭된다고 판단하면, Claude가 알아서 해당 Skill을 로드합니다. 사용자가 별도로 지시하지 않아도 되는 것이죠.

 

2) 수동 호출 (User Invocation)

Claude Code 프롬프트에서 /skill-name을 입력하면 해당 Skill이 즉시 로드됩니다. 인수를 전달할 수도 있는데, 예를 들어 /fix-issue 123처럼 Skill 이름 뒤에 값을 붙이면 됩니다.

 

[3-2]. 호출 제어

Skill의 frontmatter(YAML 설정)를 통해 누가 호출할 수 있는지를 제어할 수 있습니다.

출처: 클로드코드를 Skills로 확장하기

Frontmatter 설정	사용자 호출	Claude 호출	컨텍스트 로딩
(기본값)	O	O	description이 항상 컨텍스트에 있고, 호출 시 전체 로드
disable-model-invocation: true	O	X	description도 컨텍스트에 없음. 사용자 호출 시에만 전체 로드
user-invocable: false	X	O	description이 항상 컨텍스트에 있고, 호출 시 전체 로드

 

여기서 주목할 점은, disable-model-invocation: true를 설정하면 description 자체가 Claude의 컨텍스트에서 완전히 사라진다는 것입니다. 즉, 클로드가 자동으로 실행하는 것을 방지하는 것이죠. Claude는 이 Skill이 존재하는지조차 모릅니다. 배포(deploy) 같은 작업은 Claude가 임의로 실행하면 안 되니까, 이렇게 설정해두고 사용자가 /deploy를 직접 입력했을 때만 실행되도록 하는 것이죠.

반대로, 특정 레거시 시스템에 대한 배경 지식처럼 사용자가 직접 호출할 일은 없지만 Claude가 알아야 하는 정보는 user-invocable: false로 설정하면 됩니다. / 메뉴에서는 보이지 않지만, Claude가 필요할 때 자동으로 참조합니다.

 

[3-3]. 컨텍스트 로딩 순서

Skill이 컨텍스트에 올라가는 과정은 다음과 같습니다.

 

1. 세션 시작: Skill의 description(설명)만 로드됩니다. 이때 전체 내용은 아직 로드되지 않습니다.

2. Skill 호출: 사용자가 /skill-name으로 호출하거나, Claude가 자동으로 선택하면 그때 전체 SKILL.md 내용이 로드됩니다.

3. 실행: Claude가 Skill의 지침에 따라 작업을 수행합니다.

 

이 구조 덕분에 Skill이 아무리 많아도, 실제로 호출되기 전까지는 description 한 줄 정도의 토큰만 소비합니다. 컨텍스트 윈도우가 부족한 상황에서 큰 장점이 있습니다.

---

[4]. Skills 생성하기

이제 직접 Skill을 만들어보겠습니다. Skill을 만드는 건 생각보다 간단합니다. 디렉토리를 하나 만들고, 그 안에 SKILL.md 파일을 작성하면 끝입니다.

 

[4-1]. 디렉토리 구조

Skill을 저장하는 위치에 따라 적용 범위가 달라집니다.

 

위치	경로	적용 범위
Enterprise	관리 설정(Managed Settings)으로 배포	조직의 모든 사용자
개인 Skill	~/.claude/skills/<skill-name>/SKILL.md	모든 프로젝트에서 사용
프로젝트 Skill	.claude/skills/<skill-name>/SKILL.md	해당 프로젝트에서만 사용
Plugin Skill	<plugin>/skills/<skill-name>/SKILL.md	플러그인 활성화 위치

 

같은 이름의 Skill이 여러 위치에 있으면, 우선순위가 높은 쪽이 적용됩니다. 우선순위는 Enterprise > 개인 > 프로젝트 순서입니다. Plugin Skill은 별도의 네임스페이스(plugin-name:skill-name)를 사용하므로 다른 Skill과 이름이 충돌하지 않습니다.

 

각 Skill은 디렉토리 단위로 구성됩니다. 가장 기본적인 구조는 이렇습니다.

 

my-skill/
├── SKILL.md           # 메인 지침 파일 (필수)
├── template.md        # 템플릿 (선택)
├── examples/
│   └── sample.md      # 예제 (선택)
└── scripts/
    └── validate.sh    # 스크립트 (선택)

 

SKILL.md만 있으면 Skill로 동작합니다. 나머지 파일은 필요에 따라 추가하면 됩니다.

 

[4-2]. SKILL.md 파일 구조

SKILL.md 파일은 크게 두 부분으로 나뉩니다.

 

1. YAML frontmatter (--- 마커 사이): Skill의 메타데이터와 설정

2. Markdown 본문: Claude가 따를 실제 지침

 

---
name: my-skill
description: 이 Skill이 하는 일과 사용 시기를 설명합니다
---

여기에 Claude가 따를 지침을 작성합니다.
구체적인 단계, 규칙, 예시 등을 넣으면 됩니다.

 

[4-3]. 주요 Frontmatter 필드

frontmatter에서 사용할 수 있는 주요 필드를 정리하면 다음과 같습니다. 모든 필드는 선택사항이며, description만 작성해도 충분합니다.

 

필드	설명
name	Skill 이름. 생략하면 디렉토리 이름을 사용. 소문자, 숫자, 하이픈만 가능 (최대 64자)
description	Skill이 하는 일과 사용 시기. Claude가 자동 호출 여부를 판단하는 기준
disable-model-invocation	true로 설정하면 Claude의 자동 호출을 막음. /name으로만 호출 가능
user-invocable	false로 설정하면 / 메뉴에서 숨김. Claude만 사용하는 배경 지식용
allowed-tools	Skill이 활성화됐을 때 Claude가 추가 승인 없이 사용할 수 있는 도구 목록
model	Skill 실행 시 사용할 모델 지정
context	fork로 설정하면 별도의 subagent 컨텍스트에서 실행 (주 대화 컨텍스트 보존)
agent	context: fork일 때 사용할 subagent 유형. Explore, Plan, general-purpose 또는 커스텀 에이전트
argument-hint	자동완성 시 표시될 인수 힌트. 예: [issue-number]
hooks	Skill의 라이프사이클에 범위가 지정된 hooks. 도구 사용 전후에 스크립트 실행 가능

 

---

[5]. 예제: 로그 기록 Skill

실제로 어떻게 동작되는 지 간단한 로그 기록 예제를 만들어보겠습니다. Claude Code를 실행할 때마다 "yyyy-mm-dd hhmmss 이수진!" 형식의 로그를 남기는 Skill입니다.

 

[5-1]. 요구사항

만들고 싶은 Skill의 요구사항은 다음과 같습니다.

 

• 프로젝트 루트에 logs/ 디렉토리를 자동 생성
• logs/session.log 파일에 현재 날짜와 시간을 기록
• 로그 형식: yyyy-mm-dd hhmmss 이수진!
• 예시: 2026-03-22 153042 이수진!

 

[5-2]. Skill 생성

먼저 Skill 디렉토리를 만듭니다. 개인용으로 모든 프로젝트에서 쓸 수 있도록 ~/.claude/skills/ 아래에 생성합니다.

 

mkdir -p ~/.claude/skills/log-leesoojin

 

다음으로 ~/.claude/skills/log-leesoojin/SKILL.md 파일을 작성합니다.

 

---
name: log-leesoojin
description: 세션 시작 시 날짜와 시간을 포함한 로그를 기록합니다. Claude Code 세션이 시작되거나 작업을 시작할 때 사용합니다.
allowed-tools: Bash(echo *), Bash(date *), Bash(mkdir *)
---

# 세션 로그 기록

세션이 시작되면 아래 작업을 수행하세요:

1. 프로젝트 루트에 `logs/` 디렉토리가 없으면 생성합니다
2. 현재 날짜와 시간을 `yyyy-mm-dd hhmmss` 형식으로 가져옵니다
3. `logs/session.log` 파일에 아래 형식으로 한 줄을 추가합니다

형식:
```
yyyy-mm-dd hhmmss 이수진!
```

실행할 명령어:
```bash
mkdir -p logs && echo "$(date '+%Y-%m-%d %H%M%S') 이수진!" >> logs/session.log
```

로그를 기록한 후, "로그가 기록되었습니다"라고 간략히 알려주세요.

 

[5-3]. Skill 구성 설명

각 설정을 살펴보겠습니다.

 

• name: log-leesoojin - /log-leesoojin으로 수동 호출할 때 사용하는 이름입니다.
• description - Claude가 대화 맥락을 보고 이 Skill이 관련 있다고 판단하면 자동으로 호출합니다. 다만 자동 호출은 description의 키워드가 아니라, 사용자의 요청 내용과 description의 의미적 연관성을 기준으로 판단됩니다. 즉, 사용자가 "로그 기록해줘" 같은 요청을 했을 때 호출될 수 있습니다.
• allowed-tools - Bash 명령 중 echo, date, mkdir만 허용합니다. 불필요한 권한 요청 없이 바로 실행됩니다.

 

[5-4]. 동작 확인

Claude Code를 실행하고 테스트해봅니다.

 

먼저, /skills를 입력했을 때 방금 만든 log-leesoojin 스킬이 보이는 것을 확인할 수 있습니다.

 

수동 호출 방법:

/log-leesoojin

 

수동으로 직접 호출 했을 때 logs라는 디렉토리를 만들고 로그를 생성한 것을 확인할 수 있습니다.

그럼 자동으로 스킬을 호출도 잘 하는지 확인해볼까요?

 

자동 호출 유도:

안녕하세요? 로그로 남겨주세요.

 

 

로그를 남겨달라는 지시를 보고 skills를 자동 호출한 뒤 로그를 생성한 것을 확인할 수 있습니다.

 

[5-5]. 응용 팁

이 Skill을 기반으로 몇 가지 응용이 가능합니다.

 

1) 수동 호출 전용으로 전환하기

Claude가 자동으로 호출하는 것을 막고 싶다면, frontmatter에 아래 한 줄을 추가하면 됩니다.

disable-model-invocation: true

 

2) 메시지를 동적으로 변경하기

$ARGUMENTS 변수를 활용하면, 호출 시 전달한 인수로 메시지를 바꿀 수 있습니다.

---
name: log-custom
description: 사용자 지정 메시지로 로그를 기록합니다
allowed-tools: Bash(echo *), Bash(date *), Bash(mkdir *)
---

logs/session.log에 아래 형식으로 기록하세요:

```bash
mkdir -p logs && echo "$(date '+%Y-%m-%d %H%M%S') $ARGUMENTS" >> logs/session.log
```

 

이렇게 하면 /log-custom 작업 시작!이라고 입력했을 때, 로그에 "2026-03-22 153042 작업 시작!"이 기록됩니다.

 

[5-6]. 번들 Skills 소개

Claude Code에는 기본으로 내장된 번들 Skills도 있습니다. 따로 설치할 필요 없이 바로 사용할 수 있습니다.

 

• /simplify - 최근 변경된 코드를 검토하고 개선합니다. 3개의 검토 에이전트(코드 재사용, 품질, 효율성)를 병렬로 실행합니다.
• /batch <instruction> - 코드베이스 전체에서 대규모 변경을 병렬로 처리합니다. 예: /batch migrate src/ from Solid to React
• /debug [description] - 현재 Claude Code 세션의 디버그 로그를 분석하여 문제를 해결합니다.
• /loop [interval] <prompt> - 프롬프트를 지정한 간격으로 반복 실행합니다. 예: /loop 5m check if the deploy finished
• /claude-api - Claude API 참조 자료를 로드합니다. 코드에서 anthropic이나 @anthropic-ai/sdk를 import할 때 자동 활성화됩니다.

---

마무리

이번 포스팅에서는 Claude Code의 Skills 기능에 대해 살펴보았습니다. 핵심 내용을 정리하면 다음과 같습니다.

 

부족한 글이지만, Claude Code를 좀 더 효율적으로 활용하고 싶은 분들께 도움이 되셨으면 합니다. 궁금한 점이나 피드백이 있으시면 댓글로 남겨주세요.