Claude Code skills 만들기와 사용 방법 정리

Claude Code Skills 개념 정리

Claude Code Skill은 특정 작업을 잘 하도록 Claude에게 "절차와 기준을 패키징해서 가르치는" 마크다운 기반 매뉴얼이다.¹⁸

코드 리뷰 기준, 커밋 메시지 포맷, 내부 데이터베이스 쿼리 규칙, 특정 도메인의 글쓰기 스타일처럼 "반복적으로 설명하기 귀찮은 것"을 Skill로 만들면 된다.¹

Skill의 핵심 특징은 다음 두 가지다.
첫째, 일반적으로는 모델이 상황에 맞으면 자동으로 불러 쓰도록 설계된 "model‑invoked" 컨텍스트이다.¹⁸
둘째, 폴더 단위로 묶인 지식·문서·스크립트 묶음이라서, 필요한 만큼만 점진적으로 읽어들이는 progressive disclosure 구조를 갖는다.¹⁸

Skills가 동작하는 방식

대략적인 흐름은 다음과 같다.¹⁸

Claude Code를 시작하면 각 Skill의 name과 description 같은 메타데이터만 시스템 프롬프트에 먼저 올라간다.

사용자가 요청을 보내면, Claude는 이 메타데이터를 보고 "어떤 Skill을 읽어야 할지"를 결정한다.

관련성이 높다고 판단된 Skill이 있으면, 해당 Skill 폴더 안의 SKILL.md를 읽어 현재 대화 컨텍스트에 합친다.

필요하다면 SKILL.md 안에서 링크된 추가 문서(reference.md, examples.md 등)를 그때그때 읽어들인다.

Skill 안에 스크립트가 있으면, 내용 전체를 프롬프트에 넣지 않고 실행만 시키고 결과만 컨텍스트에 넣을 수 있다.¹⁸

이 구조 덕분에 Skill 하나에 매우 많은 문서와 코드를 실어도, 실제 모델 컨텍스트에는 "지금 필요한 부분만" 들어간다.⁸

Skills를 어디에 둘 것인가

Skill이 저장되는 위치에 따라 적용 범위가 달라진다.¹⁶

엔터프라이즈 조직 수준 설정에 올리면 조직 전체 사용자가 공유해서 쓴다.

개인 Skill은 ~/.claude/skills/ 아래에 만든다. 모든 프로젝트에서 본인에게만 적용된다.¹

특정 레포에만 적용하려면 그 레포 루트의 .claude/skills/ 폴더에 Skill을 넣는다.¹

Claude Code 플러그인에 번들하면, 해당 플러그인을 설치한 사람은 누구나 Skill을 함께 쓸 수 있다.¹⁶

이름 충돌 시 우선순위는 대략 "엔터프라이즈 > 개인 > 프로젝트 > 플러그인" 순서로 위에 있는 것이 이긴다.¹

SKILL.md 기본 구조

Skill 폴더 안에서 필수 파일은 SKILL.md 하나다.¹⁸

문서는 크게 두 부분으로 나뉜다.

맨 위의 YAML frontmatter 영역
그 아래의 일반 Markdown 지시문·예시·참고 링크

기본 틀은 다음과 같다.¹⁸

---
name: your-skill-name
description: Brief description of what this Skill does and when to use it
# optional:
# allowed-tools: Read, Grep, Glob
# model: claude-sonnet-4-20250514
---

# Your Skill Name

## Instructions
Claude가 따라야 할 절차를 명확하게 적는다.

## Examples
Skill을 어떻게 쓰는지 구체적인 예시를 보여준다.

name과 description은 필수다.¹⁸

name은 소문자, 숫자, 하이픈만 사용하며 디렉터리 이름과 맞추는 것이 좋다.

description은 "무엇을, 언제, 언제 쓰지 말아야 하는지"까지 포함해서 구체적으로 적을수록 자동 활성화 정확도가 올라간다.⁶⁸

설명 품질과 자동 활성화

공식 문서상 Skill은 "모델이 상황에 맞게 알아서 쓰는" 구조지만, 실제로는 자동 활성화가 항상 잘 되는 것은 아니다.¹³

커뮤니티 사례 기준으로, description을 막연하게 쓰면 거의 트리거되지 않는다.⁶

잘 작동하는 패턴은 WHEN / WHEN NOT 패턴이다.⁶

언제 이 Skill을 로드해야 하는지
어떤 표현이나 키워드가 나오면 자동으로 고려해야 하는지
어떤 상황에서는 절대 로드하지 말아야 하는지

예시를 보면 차이가 명확하다.⁶

# 잘 동작하는 예시
description: >
  Stakeholder context for Test Project when discussing product features,
  UX research, or stakeholder interviews. Auto-invoke when user mentions
  Test Project, product lead, or UX research. Do NOT load for general
  stakeholder discussions unrelated to Test Project.

# 잘 안 동작하는 예시
description: Provides information about stakeholders

실전에서 Skill이 잘 안 걸리면 다음을 점검한다.

설명 안에 "사용 시점(when)"과 "비사용 시점(when not)"을 모두 넣었는가
도메인 키워드(프로젝트 이름, 역할, 회사 이름 등)를 명시했는가
Skill이 너무 일반적인 이름과 설명을 갖고 있지는 않은가

이런 식으로 몇 번 반복해서 description을 튜닝해 줘야 실제로 잘 걸린다.⁶

Skill 메타데이터 필드 정리

YAML frontmatter에서 쓸 수 있는 주요 필드는 다음과 같다.¹

name
Skill 이름. 필수. 소문자/숫자/하이픈만 사용. 폴더명과 동일하게 맞추는 것을 권장.

description
Skill의 목적과 사용 시점을 설명하는 문장. 필수. Claude가 이 설명을 보고 "언제 이 Skill을 로드할지"를 판단한다.

allowed-tools
이 Skill이 활성화되었을 때 Claude가 사용자 추가 허락 없이 바로 쓸 수 있는 도구 목록.¹
보안·안전·역할 분리를 위해 "읽기 전용 Skill", "데이터 분석 전용 Skill" 같은 것을 만들 때 유용하다.

model
Skill 활성화 시 사용할 모델을 지정할 수 있다.¹
Conversation 기본 모델 대신 특정 버전(예: claude-sonnet-4-20250514)을 강제하고 싶을 때 사용한다.

allowed-tools로 도구 제한하기

특정 Skill이 켜져 있을 때 Claude가 사용할 수 있는 도구를 제한하고 싶다면 allowed-tools를 설정한다.¹⁹

예를 들어 "파일은 읽기만 하고, 쓰기는 절대 하지 않게" 만들고 싶다면 다음처럼 작성한다.¹

---
name: reading-files-safely
description: Read files without making changes. Use when you need read-only file access.
allowed-tools: Read, Grep, Glob
---

# Safe File Reader

## Instructions
Read, Grep, Glob만 사용해서 파일을 탐색하되 어떤 파일도 수정하지 않는다.

이 Skill이 활성화된 동안에는 Read, Grep, Glob만 추가 허락 없이 사용할 수 있고, 다른 도구는 일반 permission 모델을 따른다.¹⁹

읽기 전용 리서치용 Skill, 제한된 분석용 Skill, 보안 민감 작업에 사용하는 Skill을 만들 때 특히 유용하다.

Progressive Disclosure: 지원 파일 구조화

Skill에 담고 싶은 내용이 많아지면, 모두 SKILL.md에 넣으면 컨텍스트가 불필요하게 비대해진다.

권장 패턴은 "중요한 것만 SKILL.md, 나머지는 링크로 분리"하는 progressive disclosure 패턴이다.¹⁸

폴더 구조 예시는 다음과 같다.¹

my-skill/
├── SKILL.md         # 핵심 개요와 사용법
├── reference.md     # 상세 API/도메인 레퍼런스 (필요할 때만 읽음)
├── examples.md      # 사용 예시 모음 (필요할 때만 읽음)
└── scripts/
    └── helper.py    # 실행만 하고 내용은 프롬프트에 올리지 않아도 되는 스크립트

SKILL.md에서 이런 식으로 연결한다.¹

## Additional resources

자세한 API 문서는 reference.md를 참고한다.  
사용 예시는 examples.md를 참고한다.

스크립트는 "읽지 말고 실행하라"고 명시하는 것이 좋다.¹⁸

## Utility scripts

입력 파일을 검증할 때는 scripts/validate_form.py를 실행해서 유효성 검사 결과만 사용한다.

이렇게 하면
핵심 규칙과 프로세스는 항상 컨텍스트에 들어가고
무거운 레퍼런스는 필요할 때만 읽혀서 컨텍스트를 아낀다.¹⁸

Skill 업데이트와 삭제

갱신은 SKILL.md를 직접 수정하면 된다.¹

Skill을 완전히 제거하고 싶으면 폴더 자체를 삭제한다.

Claude Code는 Skill 목록을 시작 시점에 로드하므로, 변경사항을 반영하려면 세션을 종료하고 다시 시작하는 것이 안전하다.¹

Subagent와 Skill 연동

Subagent는 별도 컨텍스트와 도구 세트를 가진 "작은 에이전트"다.¹⁹

중요한 점은, 메인 세션의 Skill이 자동으로 Subagent에 상속되지는 않는다는 것이다.¹

특정 Subagent에 필요한 Skill만 명시적으로 붙이고 싶다면 해당 에이전트의 AGENT.md에 skills 필드를 설정한다.¹

# .claude/agents/code-reviewer/AGENT.md
---
name: code-reviewer
description: Review code for quality and best practices
skills: pr-review, security-check
---

이렇게 설정하면 code-reviewer 에이전트를 사용할 때 pr-review, security-check Skill이 함께 로드된다.

복잡한 워크플로에서 "코드 리뷰 전용 에이전트", "보안 점검 전용 에이전트"처럼 역할별로 Skill 세트를 나눌 수 있다.¹⁸

Skill vs Slash Commands vs Subagents vs Plugins

Claude Code에는 Skill 말고도 여러 확장 수단이 있다.¹⁶⁹

Skill은 "상황이 맞으면 Claude가 알아서 로드하는 지식/규칙 패키지"에 가깝다.¹⁸

Slash command는 /deploy staging처럼 사용자가 직접 호출하는 재사용 프롬프트 템플릿이다.¹⁹

Subagent는 별도 상태와 도구를 가진 독립 에이전트이므로, 큰 작업 흐름을 맡길 때 유용하다.⁹

Plugin은 Skill, Subagent, 명령, MCP 설정 등을 묶어 배포하는 패키지 형식이다.⁶⁸

한 글에서 제안되는 간단한 의사 결정은 다음과 같다.⁶

"Claude가 자동으로 기억해서 적용해야 할 것"은 Skill
"특정 절차를 단계별로 자동화하고 싶을 때"는 Subagent
"자주 쓰는 Subagent/프롬프트에 단축키가 필요할 때"는 Slash command
"이 셋을 다른 사람과 공유하고 싶을 때"는 Plugin

CLAUDE.md, MCP 서버, Hooks 등은 별도의 층으로 존재하지만, Skill과는 서로 보완 관계에 있다.¹⁹

Skill 자동 활성화 문제와 Hook 기반 우회

실사용자 피드백에 따르면, Skill이 존재하고 list <available_skills>에는 나오지만 실제 대화에서 자동 활성화가 잘 안 되는 경우가 있다.³

Skill 설명과 사용자 요청이 거의 동일한 문구임에도 Skill을 무시하고 일반 답변을 하는 사례가 반복 보고되었다.³

한 커뮤니티 글에서는 "Skill은 그냥 앉아 있고, 당신이 직접 사용하라고 말해 줘야 한다"는 표현까지 나온다.³

이를 우회하는 패턴 중 하나가 Claude Code의 Hook 기능을 사용하는 것이다.³⁹

UserPromptSubmit Hook에서 사용자의 프롬프트를 읽어 특정 키워드가 보이면 "이 Skill을 써라"라는 명시적 지시를 Claude에게 넣는 방식이다.³

예를 들어 research라는 Skill을 자동으로 쓰게 하고 싶다면, 다음과 같은 스크립트를 ~/.claude/hooks/auto-research.sh에 둘 수 있다.³

#!/bin/bash
INPUT=$(cat)
PROMPT=$(echo "$INPUT" | jq -r '.prompt // empty')

if echo "$PROMPT" | grep -qiE '(research|study)'; then
  echo "🔍 INSTRUCTION: Use Skill(research) to handle this request with source verification."
fi

그리고 ~/.claude/settings.json의 UserPromptSubmit Hook에 이 스크립트를 연결한다.³

이렇게 하면 사용자가 "research X"라고 말하는 순간, Hook이 "Use Skill(research)"라는 강한 지시를 Claude에게 주고, Skill이 실제로 사용되는 빈도가 크게 올라간다.³

문장 하나로 요약하면, "술렁이는 힌트가 아니라, 명령형으로 Skill 사용을 강하게 지시해야 안정적으로 동작한다"는 것이다.³

Skills 배포와 재사용

Skill을 개인 용도로만 쓸 수도 있지만, 팀/조직/커뮤니티에서 재사용할 수 있도록 배포하는 방식도 있다.¹⁶⁸¹⁰

레포 수준 공유를 원하면 .claude/skills/ 디렉터리를 그대로 버전 관리에 넣는다. 레포를 클론하는 사람은 모두 같은 Skill 세트를 사용하게 된다.¹

여러 레포에서 공통으로 쓰고 싶으면 Claude Code Plugin 안에 skills/ 디렉터리를 만들고 그 안에 Skill 폴더들을 넣은 뒤, 플러그인 마켓플레이스를 통해 배포한다.¹¹⁰

엔터프라이즈 환경이라면 IAM/managed settings를 통해 조직 전체 Skill을 배포할 수 있다.¹⁸

Anthropic의 공개 Skills GitHub 리포지토리를 plugin marketplace로 추가한 뒤, 원하는 Skill 세트를 선택해서 설치하는 방식도 있다.¹⁰

로컬에서 다음 명령으로 마켓플레이스를 추가할 수 있다.¹⁰

/plugin marketplace add anthropics/skills

그 후 특정 Skill 플러그인을 설치하면, "PDF Skill로 이 파일에서 폼 필드를 추출해 줘"와 같이 곧바로 쓸 수 있다.¹⁰

Claude Code 환경에서 Skills를 잘 활용하는 흐름

Skills는 Claude Code 전체 환경 내에서 다른 기능들과 함께 쓸 때 진가가 드러난다.²⁷⁹

일반적인 세팅·활용 흐름은 다음과 같이 잡을 수 있다.

프로젝트 루트에서 /init으로 CLAUDE.md를 생성하고, 프로젝트 규칙과 테스트·빌드 방법, 도메인 요약 등을 정리한다.⁷⁹

여러 프로젝트에 공통인 개인 작업 방식·커뮤니케이션 스타일·커밋 메시지 규칙 등은 ~/.claude/skills/에 개인 Skill로 만든다.²⁶¹⁰

프로젝트 고유의 코드 리뷰 기준, 아키텍처 원칙, 데이터 모델, 도메인 언어는 .claude/skills/에 프로젝트 Skill로 만든다.¹²⁹

자주 반복되는 "이슈 디버깅 루프"나 "로그 분석 루프"는 Slash command로, "긴 작업을 맡길 전담 에이전트"는 Subagent로, "특정 도구나 외부 시스템과의 통합"은 MCP 서버와 함께 설계한다.²⁹

Skill 자동 활성화가 잘 안 되는 부분은 Hook를 이용해 "Use Skill(X)" 명령을 주입하는 식으로 보완한다.³⁹

이렇게 층을 나눠 두면
CLAUDE.md는 "프로젝트/개인 환경의 기본 설명서"
Skill은 "도메인별·역할별 세부 매뉴얼"
Slash command는 "자주 쓰는 시나리오 템플릿"
Subagent는 "별도 문맥에 장기 작업을 맡기는 부 에이전트"
Plugin과 marketplace는 "위 설정을 다른 사람과 공유하는 수단"

이라는 식으로 역할이 분리되어, 장기적으로 유지보수가 쉬워진다.²⁶⁹¹⁰