실무자가 SKILL.md에 담는 것, 그리고 이동하는 이유

Claude Code를 실무에 쓰는 사람이라면 결국 같은 질문에 닿습니다. 매 세션마다 컨텍스트 비용을 내지 않고 재사용 가능한 방법론을 어떻게 넣어둘 수 있을까요? Anthropic이 내놓은 답은 SKILL.md이고, 이 방식의 경제성 때문에 이제 여러 제품을 넘나들며 쓰이고 있습니다.

큰 보조 파일을 함께 묶어도 SKILL.md 유지 비용이 낮은 이유

SKILL.md가 비용을 낮게 유지하는 핵심은 점진적 공개입니다. 초기화 시점에 에이전트는 각 스킬의 name과 description만 시스템 프롬프트에 로드하고, 전체 지침 본문과 함께 묶인 스크립트나 참조 파일은 실제 요청이 그 설명과 맞아떨어질 때까지 미룹니다. 2,000단어 분량의 참조 자료를 담은 SKILL.md도 "필요해지기 전까지는 거의 비용이 들지 않습니다" .

2025년 12월 18일부터 이 형식은 agentskills.io의 공개 표준이 되었기 때문에, 하나의 SKILL.md 디렉터리를 Claude.ai, Claude Code, Claude Agent SDK, Claude Developer Platform에서 수정 없이 그대로 실행할 수 있습니다 .

현재 기준선은 Claude Code v2.1.199(2026년 7월 2일)입니다. 이 버전은 슬래시 스킬을 여러 개 쌓아 호출할 때의 문제를 고쳤고, 명령어 레퍼런스는 최대 여섯 개까지 이어서 체인할 수 있다고 확인합니다. v2.1.198(7월 1일)은 서브에이전트를 기본적으로 백그라운드에서 실행되게 했고, v2.1.197(6월 30일)은 Sonnet 5를 기본 모델로 올렸습니다 .

SKILL.md 작성법: 프런트매터, 본문, 디렉터리 구조

SKILL.md에 필요한 구성 요소는 두 가지뿐입니다. YAML 프런트매터와 마크다운 본문입니다. 프런트매터에는 name이 들어가며, 이것이 슬래시 명령어 라벨이 됩니다. 예를 들어 name: deploy는 /deploy가 됩니다. 또한 description은 모델이 실제 요청과 대조하는 트리거 문구입니다 . description은 제목이 아니라 간결한 의도 문장("Summarize uncommitted changes for review")으로 쓰세요. 에이전트가 시작 시점에 전체 지침 본문을 로드할지 판단하기 위해 훑는 문자열이 바로 이것입니다 .

위치가 우선순위를 결정합니다. 같은 스킬은 네 가지 범위에 둘 수 있고, 더 높은 단계가 더 낮은 단계를 조용히 덮어씁니다. 엔터프라이즈가 이겨도 경고는 표시되지 않습니다 :

커스텀 명령어는 스킬로 통합되었기 때문에 .claude/commands/deploy.md와 .claude/skills/deploy/SKILL.md는 동일합니다. 둘 다 /deploy를 등록합니다 .

현재 상태를 바탕으로 지침을 실행하려면 본문 줄 앞에 셸 확장을 붙이면 됩니다. Anthropic의 공식 summarize-changes 시작 예제는 Claude가 스킬을 읽기 전에 !`git diff HEAD`를 인라인으로 넣습니다. 그래서 리뷰는 오래된 스냅샷이 아니라 실제 워킹 트리를 반영합니다 :

---
name: summarize-changes
description: Summarize uncommitted changes in the working tree for review
---
Review the following diff and summarize it for a reviewer:

!`git diff HEAD`

스타일 가이드, 오류 카탈로그, 아키텍처 다이어그램 같은 보조 파일은 스킬 디렉터리에서 SKILL.md와 나란히 두고 지연 로드합니다. 본문에서는 상대 경로로 참조하세요. 이 파일들은 초기화 때 지불하는 name-plus-description 비용에 포함되지 않으며, 문서가 많은 스킬도 실제로 발동되기 전까지 저렴하게 유지되는 이유가 바로 여기에 있습니다 .

매일 쓰는 실무 역량을 SKILL.md 항목으로 옮기기

Claude Code를 매일 안정적으로 쓰게 만드는 반복 습관은 각각의 SKILL.md 파일로 깔끔하게 대응됩니다. Anthropic은 코드베이스 정찰, 계획 수립, 재사용 가능한 지식, 리뷰, 위임이라는 다섯 가지 운영 영역을 문서화하고 있으며, 각각은 붙여 넣는 프롬프트가 아니라 이름이 붙고 버전 관리되는 스킬이 됩니다 . 패턴만 알면 전환은 기계적입니다. 설명에는 트리거 문구를 담고, 본문에는 방법을 담고, 함께 두는 파일에는 오래 유지될 참조 자료를 담습니다.

코드베이스 정찰. Anthropic의 일반 워크플로가 처음에 던지는 온보딩 질문을 인코딩합니다. 아키텍처 개요를 요청하고, 핵심 데이터 모델을 식별하고, 인증이 어떻게 처리되는지 추적하고, "이 함수는 왜 호출되는가?"에 답하게 하는 식입니다 . 본문은 @ 파일 및 디렉터리 참조로 실제 경로에 고정해 응답이 실제 트리를 인용하게 하고, 설명은 "understand the codebase structure"나 "explore the authentication flow" 같은 표현에 맞춰 해당 프롬프트에서 발동되도록 설정합니다.

PRD 인터뷰 루프. "5 Claude Code skills I use every single day"에서 Matt Pocock은 계획 수립을 세 개의 별도 SKILL.md 파일로 나눕니다. 사용자를 인터뷰하고 Fred Brooks의 설계 트리 각 분기를 따라가는 "grill me" 스킬, 저장소를 기준으로 주장을 검증한 뒤 결과를 GitHub 이슈로 내보내는 "write a PRD" 스킬, 그리고 이를 원자적 작업으로 분해하는 "PRD to issues" 스킬입니다(video: Matt Pocock). 그는 이것을 plan mode에 대한 교정으로 설명합니다.

"Plan mode produces a plan document before shared understanding is reached," — Matt Pocock, 5 Claude Code skills I use every single day에서.

재사용 가능한 지식 계층. 변동성에 따라 나눕니다. 코딩 표준, 라이브러리 선택, 리뷰 체크리스트처럼 오래가는 사실은 항상 로드되는 CLAUDE.md에 넣고, 동적 맥락이 필요한 절차적 방법론은 트리거될 때만 로드되는 SKILL.md에 넣습니다 . 같은 지시를 양쪽에 중복해서 넣지 마세요. 개발자들이 반복 행동을 이미 설정 파일로 인코딩한다는 점은 실증적으로도 확인됩니다. 한 arXiv 연구는 242개의 공개 저장소에서 253개의 CLAUDE.md 매니페스트를 분석했습니다 .

Diff 리뷰. !`git diff HEAD` 주입 줄을 포함한 summarize-changes 스킬은 리뷰를 현재 작업 트리에 고정합니다. 여기에 현재 diff에서 정확성 버그를 검토하고 --fix를 받는 번들 /code-review 스킬을 함께 쓰세요. 그 로직을 자체 SKILL.md 안에 다시 구현할 필요는 없습니다 .

위임. 프로젝트별 서브에이전트 프롬프트를 범위가 제한된 도구 접근 권한과 함께 인코딩한 다음, /run-skill-generator를 한 번 실행해 프로젝트 실행 레시피를 .claude/skills/run-<name>/에 자동 기록합니다 . 실행-검증-테스트 루프는 수동 순서가 아니라 한 번에 반복 호출할 수 있는 이름 붙은 호출이 됩니다.

실무자가 자주 부딪히는 실패: 우선순위, 설명 조정, 체인 깊이

대부분의 스킬 실패는 요란하지 않고 조용합니다. 반복해서 나타나는 네 가지 실패, 즉 우선순위 충돌, 설명 불일치, CLAUDE.md/SKILL.md 중복, 체인 초과는 같은 증상을 보입니다. 에이전트가 인코딩한 것과 다른 일을 하지만 오류는 기록되지 않습니다. 스킬은 네 가지 범위, 즉 엔터프라이즈, ~/.claude/skills/의 개인, .claude/skills/의 프로젝트, 플러그인 범위에서 해석되며 우선순위는 엔터프라이즈 > 개인 > 프로젝트입니다 . 엔터프라이즈 스킬이 내가 만든 스킬과 같은 이름을 쓰면 그쪽이 이기고, 아무 경고도 나오지 않습니다. 새 스킬 이름을 정하기 전에 ls ~/.claude/skills/로 점검하고 엔터프라이즈 네임스페이스가 비어 있는지 확인하세요.

다음 함정은 설명 불일치입니다. 모델이 스킬을 거의 자동 호출하지 않는다면 description 필드가 실제 요청과 맞지 않는 것입니다. 자동 호출은 프롬프트가 그 텍스트와 맞을 때만 트리거됩니다 . 먼저 /skill-name을 명시적으로 실행해 본문이 맞는지 확인한 뒤 문구를 반복 조정하세요. 너무 구체적인 설명과 너무 일반적인 설명은 똑같은 실패를 만들기 때문에, 세부사항을 더하는 대신 중간 지점을 맞춰야 합니다.

CLAUDE.md와 SKILL.md 사이의 중복은 긴 세션에서 컨텍스트가 차오를수록 가중치를 일관되지 않게 만듭니다. 경계를 깨끗하게 유지하세요. CLAUDE.md는 코딩 표준과 아키텍처 결정 같은 오래가는 사실을 맡고, SKILL.md는 사용될 때만 본문이 로드되는 절차적 방법론을 맡습니다 . 스킬 동작이 예측 가능하지 않아질 때마다 겹치는 부분을 점검하세요.

마지막은 체인 깊이입니다. Claude Code v2.1.199(2026년 7월 2일)는 중첩된 슬래시-스킬 호출을 수정했고, 명령어 레퍼런스는 하나의 접두사에서 최대 여섯 개의 선행 스킬을 체인으로 연결할 수 있다고 확인합니다 . 여섯 개를 넘는 동작은 정의되어 있지 않고 오류도 기록되지 않으므로, 프로덕션 체인은 다섯 개 이하로 유지하고 더 긴 파이프라인은 스킬 본문 안의 중첩 호출로 구성하세요. Matt Pocock이 이 기본 원칙을 설명하듯, 그의 스킬은 "a corrective to plan mode"이며 plan mode는 "produces a plan document before shared understanding is reached"합니다. 위임을 신뢰 가능하게 만드는 것은 체인 길이가 아니라 스킬 정의의 정밀함입니다(video: Matt Pocock).

SKILL.md를 더 확장하는 법: MCP, 이벤트 기반 자동화, 이식성

스킬 본문이 충분히 정밀해지면, 내용을 불필요하게 키우지 않고도 세 가지 확장으로 활용 범위를 넓힐 수 있습니다. Model Context Protocol(MCP)을 쓰면 스킬이 외부 시스템을 다룰 수 있습니다. Notion, Figma, Slack, Gmail, Outlook, 이슈 트래커, Context7 같은 문서 서버를 frontmatter에서 대상 MCP 서버로 지정하거나, 지시 본문 안에서 직접 호출하는 방식입니다 . 이렇게 하면 "PRD 작성"이나 "코드 리뷰" 스킬이 로컬 텍스트 작업에 머무르지 않고, 실제 티켓을 읽고 팀이 일하는 곳에 결과를 다시 써 주는 작업으로 바뀝니다 .

라이프사이클 훅은 스킬 본문에 넣지 않는 편이 나은 부수 효과를 처리합니다. 결정적인 셸 명령이나 HTTP 엔드포인트를 SessionStart, UserPromptSubmit, PreToolUse, PostToolUse 이벤트에서 실행할 수 있습니다. 매번 반드시 일어나야 하는 작업, 예를 들어 각 편집 뒤 lint 실행이나 민감한 경로에 대한 쓰기 차단 같은 용도로만 쓰고, 스킬 수준의 지시를 대신하는 수단으로 쓰지는 마세요 .

이식성은 2025년 12월 18일 agentskills.io에 공개 표준이 나오면서 얻은 가장 큰 이점입니다. .claude/skills/ 디렉터리는 Claude.ai에 그대로 넣을 수 있고, 유료 Pro 또는 Team 플랜에서 Profile → Settings → Capabilities 아래에서 설정할 수 있습니다 (동영상: Kevin Stratvert). 이름과 설명 문구를 정할 때는 Agensi 마켓플레이스 수요도 참고할 만합니다. code-reviewer, 설치 수 65회의 git-commit-writer, 설치 수 36회의 pr-description-writer가 가장 높은 순위에 있습니다 . 핵심은 분명합니다. SKILL.md 본문은 판단에 집중시키고, 반복 가능한 부수 효과는 훅으로 보내며, MCP로 바깥 시스템에 연결하고, 설명은 낯선 사람이 설치할 것처럼 작성하세요. 이제 실제로 그럴 수 있기 때문입니다.

자주 묻는 질문

SKILL.md와 CLAUDE.md는 무엇이 다른가요?

CLAUDE.md는 세션 시작 시 전체가 로드되고 계속 컨텍스트에 남습니다. 그래서 코딩 표준, 선호 라이브러리, 아키텍처 결정, 리뷰 체크리스트처럼 오래 유지되어야 하는 사실을 두기에 적합합니다 . 반면 SKILL.md는 점진적 공개 방식을 씁니다. 초기화 시에는 name과 description만 시스템 프롬프트에 들어가고, 요청이 설명과 맞을 때만 전체 본문이 로드됩니다 . 경험칙은 이렇습니다. CLAUDE.md는 항상 켜져 있는 컨텍스트이고, SKILL.md는 "필요해지기 전까지는 거의 비용이 들지 않는" 주문형 방법론입니다.

Claude Code는 언제 SKILL.md 스킬을 자동 호출할지 어떻게 판단하나요?

모델은 현재 요청을 각 스킬의 description 필드와 대조합니다. 설명이 프롬프트의 의도와 잘 맞으면 Claude Code가 전체 본문을 로드하고 스킬을 실행합니다. 맞지 않으면 아무것도 로드하지 않습니다 . 실무에서는 먼저 /skill-name으로 스킬을 명시적으로 테스트해 본문이 작동하는지 확인한 뒤, 자동 호출이 안정적으로 트리거될 때까지 설명 문구를 다듬는 흐름이 좋습니다. 올바른 스킬이 전혀 실행되지 않는 가장 흔한 이유는 설명이 모호하기 때문입니다.

같은 SKILL.md를 Claude.ai와 Claude Code에서 재사용할 수 있나요?

예. 2025년 12월 18일 이 형식이 agentskills.io에 공개 이식 표준으로 게시되었기 때문에, 하나의 스킬 디렉터리를 수정 없이 Claude.ai, Claude Code, Claude Agent SDK, Claude Developer Platform 전반에서 실행할 수 있습니다 . 단, 두 가지는 주의해야 합니다. Claude.ai의 Skills는 유료 Pro 또는 Team 플랜이 필요하고 , 함께 넣은 스크립트는 환경별 경로 검증이 필요할 수 있습니다.

Claude Code에는 어떤 번들 스킬이 포함되어 있으며, 어떻게 끌 수 있나요?

번들 스킬은 끄지 않는 한 모든 세션에서 사용할 수 있으며, /code-review, /debug, /batch, /loop, /security-review, /run, /verify, /dataviz, /claude-api가 포함됩니다 . 모두 제거하려면 settings.json에 disableBundledSkills: true를 설정하세요. 범위에 유의해야 합니다. 엔터프라이즈 범위에서 설정하면 조직의 모든 사용자에게 영향을 주므로, 이 변경을 푸시하기 전에 의도를 확인하세요.

v2.1.199 이후 한 번의 슬래시 호출에서 SKILL.md 항목을 몇 개까지 연결할 수 있나요?

명령어 레퍼런스에 따르면, 하나의 슬래시 접두사에서 앞쪽 스킬을 최대 여섯 개까지 연결할 수 있습니다 . 2026년 7월 2일자로 표시된 Claude Code v2.1.199에서는 중첩된 슬래시 스킬 호출이 올바르게 해석되지 않던 버그가 수정되었습니다 . 현재 문서에서 여섯 개를 넘는 동작은 정의되어 있지 않으므로, 프로덕션 체인은 다섯 개 이하로 유지하세요.