한 줄 요약: Claude Code 공식 문서 "Extend Claude with skills". SKILL.md 파일 하나로 Claude에게 지식이나 워크플로를 더하는 스킬을 만들고, 어디에 두고, 누가 부르게 하고, 어떻게 평가·공유·문제 해결하는지를 다룬다. 번들 스킬(/doctor, /run, /verify, /claude-api 등), claude.ai 계정에서 동기화되는 스킬, frontmatter 전체 표, 인자 치환, 동적 컨텍스트 주입(!`명령`), context: fork 서브에이전트 실행, 컴팩션 뒤 동작을 포함한다.
원본 정보#
- 제목: Extend Claude with skills
- 발행: Anthropic, Claude Code 공식 문서 (원본 날짜 미상)
- URL: https://code.claude.com/docs/en/skills (새 창)
- 수집(fetch)일: 2026-10-18. 본문의 버전 조건(v2.1.2xx), 설정 키, 숫자는 이 날짜 기준이다.
핵심 주장#
- 같은 지시·체크리스트·절차를 채팅에 계속 붙여 넣거나, CLAUDE.md의 한 절이 사실이 아니라 절차로 자랐다면 스킬을 만든다. CLAUDE.md와 달리 스킬 본문은 쓸 때만 로드되므로 긴 참고 자료도 필요하기 전까지는 비용이 거의 없다. → 스킬, 업무 절차를 스킬로 만들기
- 스킬은
SKILL.md하나로 시작한다. frontmatter의description이 Claude가 언제 스킬을 자동으로 불러올지 정하는 근거이고, 디렉터리 이름(또는name)이/명령이름이 된다. 모든 frontmatter 필드는 선택이며description만 권장된다. 기존.claude/commands/커스텀 명령은 스킬에 합쳐졌고 그대로 동작한다. → 업무 절차를 스킬로 만들기 - 누가 부르는지를 frontmatter로 정한다.
disable-model-invocation: true는 사용자만(설명도 컨텍스트에 들어가지 않음),user-invocable: false는 Claude만 부르게 한다. 부작용이 있거나 시점을 직접 정하고 싶은/deploy·/commit같은 워크플로는 전자, 명령으로 의미 없는 배경 지식은 후자다. → 스킬, 권한 모드 - 불러온 스킬은 대화에 계속 남고, 컴팩션 뒤에는 앞부분만 남을 수 있다. 렌더된
SKILL.md는 메시지 하나로 들어가 이후 턴에도 남고 파일을 다시 읽지 않는다. 자동 컴팩션 때는 스킬마다 가장 최근 호출의 앞 5,000토큰을 다시 붙이고, 다시 붙인 스킬 전체가 25,000토큰 예산을 나눈다. 그래서 본문은 짧게, 중요한 지시는 위쪽에, 작업 내내 적용할 지침은 상시 지시로 쓴다. → 장기 작업 컨텍스트 관리, 컨텍스트 비용 - 스킬이 트리거되는 것과 의도대로 일하는 것은 따로 확인한다. 현실적인 프롬프트 몇 개를 새 세션에서 스킬을 켠 채와 끈 채로 돌려 비교한다. 플러그인 스킬은
claude plugin eval, 단일 스킬은 skill-creator 플러그인이 이 비교를 자동화한다. → 업무 절차를 스킬로 만들기, 스킬 문제 해결
원본의 숫자·설정값 (2026-10-18 기준)#
description과when_to_use를 합친 텍스트는 스킬 목록에서 1,536자에서 잘린다(skillListingMaxDescChars로 조정).- 스킬 목록의 문자 예산은 모델 컨텍스트 창의 1%다(
skillListingBudgetFraction, 또는SLASH_COMMAND_TOOL_CHAR_BUDGET). 넘치면 가장 덜 쓰는 스킬의 설명부터 뺀다. SKILL.md는 500줄 이하로 유지하고 세부 참고 자료는 별도 파일로 옮기라는 팁.- 컴팩션 뒤 다시 붙이는 스킬: 스킬마다 앞 5,000토큰, 합계 25,000토큰, 가장 최근에 호출한 스킬부터 채운다.
- 한 메시지에 스킬을 쌓을 때: 첫 스킬 + 최대 5개 더.
- 동적 컨텍스트 명령은 Bash 도구 기본 타임아웃 2분 아래에서 돈다.
- claude.ai 동기화 확인 주기: 작업 중 약 10분, 유휴 시 약 40분.
.trash/의 파일은 기본 30일 뒤 지워진다. - 버전 조건(일부):
/doctor prompt-auditv2.1.283, verify·simplify 커밋 전 실행 v2.1.286, 터미널 스킬 동기화 v2.1.273,/skill-doctorv2.1.252,claude plugin validatev2.1.233,background필드 v2.1.218,allowManagedPermissionRulesOnly의allowed-tools무시 v2.1.282.