Claude Code skills

Claude Code는 스킬이 시작된 곳이며, 여전히 스킬을 가장 잘 활용합니다. Claude Code의 스킬은 전체 네트워크 접근 권한으로 스크립트를 실행하고, 인수를 받고, 자체 subagent에서 실행되며, 이미 사용 중인 사용자 정의 슬래시 명령을 대체할 수 있습니다. 이 가이드는 Claude Code 쪽을 구체적으로 다룹니다. 형식 전반과 스킬의 출처는 Claude skills and agent skills를 참고하십시오.

Claude Code의 문서와 명령 참조는 2026년 11월 14일에 확인했습니다. 이 가이드 위의 목록은 Claude Code에서 설치하는 명령과 함께 HostedMCP 카탈로그에 있는 모든 스킬입니다.

Claude Code가 확인하는 위치

범위	폴더	사용 대상
개인	~/.claude/skills/<name>/SKILL.md	모든 프로젝트에서 본인
프로젝트	.claude/skills/<name>/SKILL.md	저장소를 클론한 모든 사람
중첩	<subfolder>/.claude/skills/<name>/SKILL.md	모노레포의 해당 부분에서 작업하는 사람
플러그인	<plugin>/skills/<name>/SKILL.md	플러그인이 있는 모든 사람, /plugin:name으로
조직	관리형 설정 폴더	해당 정책이 적용되는 모든 사람

두 스킬의 이름이 같으면 조직의 스킬이 본인 것보다 우선하고, 본인 것이 프로젝트 것보다 우선합니다. claude.ai에서 활성화한 스킬은 ~/.claude/skills/synced/로 동기화됩니다.

하나 만들기

mkdir -p .claude/skills/release-notes

그다음 .claude/skills/release-notes/SKILL.md를 작성합니다:

---
name: release-notes
description: Write release notes from merged pull requests. Use when the user asks for release notes, a changelog entry or a summary of what shipped.
---

1. List pull requests merged since the last tag with `gh pr list --state merged`.
2. Group them under Added, Changed and Fixed.
3. Write one plain sentence per change, for users rather than developers.

이것으로 동작하는 스킬이 완성됩니다. Claude Code는 재시작 없이 이를 인식합니다. 릴리스 노트를 요청하면 이 스킬을 사용하거나 /release-notes를 입력하면 됩니다.

SKILL.md는 500줄 미만으로 유지하고, 분량이 많은 자료는 지침에서 가리키는 옆 파일로 옮깁니다. Anthropic의 skill-creator 플러그인(/plugin install skill-creator@claude-plugins-official)은 스킬을 로드한 경우와 로드하지 않은 경우로 테스트하고 설명을 조정할 수 있습니다.

호출 방법

Frontmatter	/name 입력 가능	Claude가 자체적으로 사용	컨텍스트 내 설명
기본값	예	예	항상
disable-model-invocation: true	예	아니요	아니요
user-invocable: false	아니요	예	항상

/name은 메시지 시작 부분에서만 동작하며, 최대 여섯 개까지 연속으로 사용할 수 있습니다. 스킬은 인자를 받습니다. 본문의 $ARGUMENTS는 이름 뒤에 입력한 내용으로 대체되고, argument-hint는 메뉴에 힌트를 표시합니다.

Claude Code가 표준에 추가하는 몇 가지 필드도 있습니다. 별도의 트리거 설명을 위한 when_to_use, 스킬을 다른 모델이나 다른 effort 수준에서 실행하기 위한 model과 effort, allowed-tools와 disallowed-tools, 그리고 스킬을 서브에이전트에서 실행해 작업이 메인 대화를 채우지 않도록 하는 context: fork가 있습니다.

사용자 정의 슬래시 명령은 스킬로 통합되었습니다. .claude/commands/deploy.md와 .claude/skills/deploy/SKILL.md 모두 /deploy를 생성하며, 기존 명령 파일도 계속 동작합니다.

Claude Code에 기본 포함된 스킬

Claude Code의 명령 레퍼런스는 20개 명령을 스킬로 표시합니다. 그중 가장 자주 만나게 될 스킬은 다음과 같습니다:

스킬	하는 일
/code-review	diff, 브랜치 또는 pull request에서 버그를 선택한 노력 수준으로 검토하고, 수정하거나 코멘트를 남길 수 있습니다
/simplify	4개의 검토 에이전트가 재사용, 단순화, 효율성, 추상화 문제를 찾은 뒤 수정을 적용합니다
/batch	큰 변경을 5~30개 단위로 나누고 단위마다 백그라운드 에이전트 하나를 실행합니다
/debug	세션의 디버그 로깅을 켜고 로그를 읽습니다
/loop	프롬프트를 일정 간격으로 다시 실행하거나 스스로 속도를 조절합니다
/run 및 /verify	앱을 실행하고 변경이 실제로 동작하는지 확인합니다
/doctor	설치, 설정, 확장, CLAUDE.md를 점검합니다
/fewer-permission-prompts	자주 승인하는 읽기 전용 명령을 허용 목록으로 만듭니다
/update-config	settings.json을 평문 설명으로 편집합니다
/claude-api	최신 Claude API 및 SDK 레퍼런스를 불러옵니다
/dataviz	팔레트 검증기를 포함한 차트 및 대시보드 가이드

새 프로젝트용 CLAUDE.md를 작성하는 /init은 스킬이 아니라 내장 명령이며, /review는 /code-review의 별칭입니다. Claude Code에는 Word, PDF, PowerPoint, Excel용 Anthropic 문서 스킬이 포함되어 있지 않으므로 anthropics/skills 저장소에서 설치해야 합니다.

스킬의 비용

Claude가 스스로 호출할 수 있는 모든 스킬은 매 턴마다 설명을 컨텍스트에 올립니다. Claude Code는 이를 두 가지 방식으로 제한합니다.

• when_to_use를 포함한 각 설명은 목록에서 1,536자에서 잘립니다.
• 모든 설명은 모델 컨텍스트 윈도우의 약 1%에 해당하는 예산을 함께 나눠 씁니다. 예산을 넘으면 Claude Code는 사용 빈도가 가장 낮은 스킬부터 설명을 버리고 이름만 남깁니다.

한 번 사용된 스킬의 내용은 대화에 남습니다. 자동 컴팩션이 일어난 뒤에는 각 스킬의 가장 최근 사용이 다시 첨부되며, 스킬당 최대 5,000 토큰, 전체 최대 25,000 토큰까지입니다.

/skills는 스킬 목록을 보여 주고 토큰 비용순으로 정렬할 수 있습니다. /skill-doctor는 각 스킬의 컨텍스트 비용과 사용 빈도를 보고합니다. 직접 호출만 하는 스킬에는 disable-model-invocation: true를 설정해야 하며, 이렇게 하면 해당 설명이 컨텍스트에서 완전히 제거됩니다.

Skill, hook, subagent, MCP, plugin 중 선택

원하는 것	사용할 것	이유
Claude가 모든 세션에서 필요한 사실	CLAUDE.md	매번 로드됩니다. 200줄 이하로 유지합니다
일부 작업에 필요한 노하우	Skill	관련 있을 때만 로드됩니다
항상 일어나야 하는 동작	Hook	결정적이며 컨텍스트 비용이 없습니다. "가드레일은 hook에 둡니다"
컨텍스트 밖에서 처리할 무거운 작업	Subagent	별도 컨텍스트에서 작업하고 요약을 반환합니다
다른 시스템의 도구나 데이터	MCP server	Skill이 Claude에게 사용법을 가르칠 수 있습니다
팀을 위한 위의 모든 것	Plugin	하나의 설치로 묶습니다

Anthropic이 가장 많이 문서화하는 조합은 skill과 MCP server입니다. server는 도구를 제공하고, skill은 언제 어떻게 사용할지에 대한 판단을 제공합니다.

안전

Claude Code의 스킬은 사용자 권한과 전체 네트워크 접근 권한으로 어떤 스크립트든 실행할 수 있습니다. 직접 작성하지 않은 스킬은 스크립트를 반드시 읽어 보십시오. allowed-tools는 스킬이 사용자에게 묻지 않고 도구를 사용하도록 허용할 뿐, 아무것도 제한하지 않습니다. 프로젝트에서는 코드를 리뷰하듯이 pull request에서 .claude/skills/를 검토하십시오. 조직은 관리형 설정으로 이를 잠글 수 있으며, 승인된 플러그인 마켓플레이스의 스킬만 허용하는 것도 포함됩니다.

동작하지 않을 때

증상	원인	해결 방법
Claude가 스킬을 무시합니다	설명이 사용한 표현과 맞지 않습니다	설명을 다시 작성하고 when_to_use를 추가합니다
/name을 찾을 수 없습니다	폴더 이름과 name이 다르거나, 최상위 폴더가 새로 생겼습니다	둘을 일치시키고 /reload-skills를 실행합니다
플러그인 스킬의 이름이 다릅니다	플러그인 스킬에는 네임스페이스가 붙습니다	/plugin:name 형식으로 입력합니다
일부 스킬의 설명이 사라졌습니다	목록 예산을 초과했습니다	사용하지 않는 스킬을 제거하거나 disable-model-invocation: true를 설정합니다
스킬이 가려집니다	같은 이름의 조직 또는 개인 스킬이 있습니다	스킬 이름을 변경합니다