Claude Code 스킬을 설치해도 처음부터 컨텍스트 창에 들어오는 내용은 거의 없습니다. 실제 작업에 필요해지는 순간까지 미뤄지기 때문입니다. 이 지연 로딩이 핵심입니다.
처음에는 프런트매터만 들어오고, 자세한 본문은 필요할 때 불러옵니다
세션이 열릴 때 시스템 프롬프트에 들어가는 스킬 정보는 SKILL.md의 프런트매터뿐입니다. name(최대 64자)과 description(최대 1,024자)만 해당합니다 . 설치된 스킬 하나당 대략 ~100토큰 정도입니다 . Claude가 관련성을 판단하기에는 충분하지만, 그 이상은 아닙니다. 전체 본문은 작업이 설명과 맞아떨어지거나 /skill-name을 직접 호출할 때까지 디스크에 남아 있습니다. 이 점진적 공개 모델은 2025년 12월 18일 공개 표준으로 발표된 Agent Skills 명세에 정의되어 있습니다 .
| 단계 | 불러오는 내용 | 시점 |
|---|---|---|
| 1 | 프런트매터 메타데이터(~100토큰) | 세션 시작 시, 항상 |
| 2 | SKILL.md 전체 본문 | 작업이 일치하거나 /skill-name 호출 시 |
| 3 | references/ 및 assets/ 안의 파일 | Claude가 읽을 때마다 필요에 따라 |
에이전트가 3단계 내용을 컨텍스트에 계속 들고 있는 대신 필요할 때 읽기 때문에, Anthropic은 "the amount of context that can be bundled into a skill is effectively unbounded"라고 설명합니다 .
붙여넣은 스타일 명세로는 이 방식을 따라갈 수 없습니다. 매 세션마다 전체 토큰 비용을 치러야 하고, 작업 관련성에 따라 자동 선택될 수 없으며, 버전 관리 밖에 놓입니다. 그래서 저장소 산출물로 리뷰하거나 개선할 수도 없습니다. 스킬 폴더는 이 세 가지를 모두 충족할 수 있습니다. 평소에는 가볍고, 관련 있을 때 자동으로 로드되며, 팀이 저장소에서 리뷰할 수 있습니다.
SkillUI: npm 설치(v18+)와 정밀 스크래핑을 위한 선택적 Playwright/Chromium
이런 폴더를 만들어 주는 가장 명확한 도구는 개발자 Amaan의 MIT 라이선스 TypeScript CLI인 SkillUI입니다(repo github.com/amaancoderx/npxskillui). 필수 조건은 Node.js 18+와 npm입니다 . 전역 설치는 다음과 같습니다.
npm install -g skillui기본 모드는 순수 정적 DOM/CSS 분석으로 동작합니다. AI 모델도, API 키도 필요 없습니다. 그래서 색상 토큰, 타입 스케일, 간격 그리드, 컴포넌트 패턴을 추정이 아니라 소스에 실제로 존재하는 내용에서 복원합니다 . Ultra 모드는 Playwright를 추가해 스크롤 여정 스크린샷, hover/focus 차이, 애니메이션 신호, 레이아웃 구조를 캡처합니다.
npm install playwright && npx playwright install chromium라이브 URL이 반드시 필요한 것은 아닙니다. --dir은 로컬 .css/.scss/.ts/.tsx 파일을 검사하고, --repo는 GitHub에 호스팅된 Tailwind 설정과 CSS 변수 정의를 읽습니다 .
SkillUI 실행 흐름: 전역 설치, 사이트 스크래핑, 오퍼레이터 활성화
SkillUI를 처음부터 끝까지 실행하는 과정은 세 가지 명령으로 끝납니다. 설치, 스크래핑, 활성화입니다. 이 도구는 Node.js 18+가 필요하며, 현재 기준 v1.3.2로 배포됩니다 . 추출은 순수 정적 DOM/CSS 분석이므로, 스크래핑 중에는 API 키나 모델 호출이 개입하지 않습니다 .
1단계 — 전역 설치 후 확인합니다.
npm install -g skillui
skillui --version # 1.3.22단계 — 라이브 사이트를 스크래핑합니다. SkillUI에 원하는 URL을 지정하면 자체 완결형 폴더를 생성합니다. 여기서는 notion-design/입니다.
skillui --url https://notion.so이 폴더에는 CLAUDE.md, SKILL.md, DESIGN.md와 참조 문서 세트인 ANIMATIONS.md, LAYOUT.md, COMPONENTS.md, INTERACTIONS.md, VISUAL_GUIDE.md가 함께 들어갑니다. 여기에 토큰 JSON, 스크린샷, 로컬에 묶인 Google Fonts, .skill ZIP 아카이브도 포함됩니다 .
3단계 — 오퍼레이터를 활성화합니다. 생성된 디렉터리 안에서 Claude Code를 엽니다.
cd notion-design && claudeClaude는 CLAUDE.md와 SKILL.md를 자동으로 읽고, 추출된 루틴을 해당 세션에서 이름 있는 슬래시 오퍼레이터로 노출합니다. 페이지를 만들어 달라고 요청하면 추측이 아니라 구체적인 토큰을 바탕으로 작업합니다 .
오퍼레이터를 오래 유지하려면 폴더를 대상 저장소 안의 .claude/skills/<name>/SKILL.md로 옮긴 뒤 커밋하면 됩니다. 그러면 스킬이 git과 함께 이동하고 팀 전체에 공유됩니다. 대신 ~/.claude/skills/에 두면 내 컴퓨터의 모든 프로젝트에서 사용할 수 있습니다 . 전체 실행 과정은 source walkthrough를 참고하세요.
본문 잘림, 위험한 프런트매터, 그리고 99%에 가까운 스멜 발생률
자동 로딩은 편리하지만, 설계할 때 반드시 감안해야 할 엄격한 예산이 따라옵니다. 컨텍스트 압축 중 다시 붙는 스킬은 각각 처음 5,000토큰까지만 유지되고, 전체 합산 한도는 25,000토큰입니다 . SKILL.md는 500줄 미만으로 유지하고, 세부 내용은 references/ 하위 디렉터리로 밀어 넣으세요. 이 디렉터리는 해당 예산을 놓고 경쟁하지 않고 필요할 때 로드됩니다. 목록 자체에도 제약이 있습니다. description과 when_to_use 텍스트는 1,536자에서 잘립니다 . 따라서 Claude가 관련성을 판단할 때 아예 보지 못하는 일이 없도록, 가장 강한 트리거 신호를 처음 약 200자 안에 배치해야 합니다.
편의성보다 더 중요한 것은 신뢰입니다. 2026년 공급망 연구는 설명으로 위장한 적대적 SKILL.md 변형이 평균 77.6% 선택됐다고 보고했습니다 . 프런트매터는 Claude가 어떤 스킬을 고를지에 영향을 줄 수 있는 운영 텍스트이며, 프롬프트 인젝션 벡터가 될 수 있습니다. Anthropic의 지침은 단호합니다. 악성 스킬은 Claude가 명시된 목적 밖의 도구를 실행하도록 유도할 수 있으므로, 신뢰할 수 있는 스킬만 설치하라는 것입니다 . 품질도 얇습니다. 2026년에 실제 파일 238개를 검토한 결과, 99% 이상이 모호한 지시, 예시 누락, 정의되지 않은 범위 같은 '스킬 스멜'을 하나 이상 갖고 있었습니다 . SkillUI가 생성한 결과물은 커밋하기 전에 반드시 읽어보세요.
SkillUI 다음 단계: Figma Dev, 반응형 분기점, 시각적 차이 비교
생성된 스킬을 신뢰할 수 있게 만들었다면, 마지막 추측까지 없애기 위해 디자인 메타데이터 소스와 함께 사용하세요. Figma의 Dev Mode MCP 서버는 2025년 6월 베타에 들어갔습니다 . Claude가 픽셀에서 추론한 토큰이 아니라 정확한 색상, 간격, 값을 받을 수 있으므로, 완전히 근거 있는 출력을 위해 추출 체크리스트를 담은 SKILL.md에 이를 입력하세요.
흔한 빈틈은 다음 세 가지 추가 항목으로 메울 수 있습니다:
- 반응형 분기점: 모바일과 태블릿 제약을 SKILL.md 본문에 명시해, 작성자가 데스크톱만 충실히 구현한 결과물을 조용히 내보내지 못하게 하세요.
- 스크린샷 비교 루프: 구현 후 Claude에게 결과를 스크린샷으로 찍고, 원본과 차이를 비교한 뒤, 각 불일치를 수정하게 하세요. Anthropic이 UI 작업용으로 문서화한 루프입니다 .
- 수동 DESIGN.md 편집: SkillUI는 DOM/CSS에 존재하는 것만 복구합니다. 따라서 브랜드 의도, 누락된 토큰, Storybook에만 있는 상태는 오퍼레이터가 완성되기 전에 직접 추가해야 합니다.
핵심은 이렇습니다. SkillUI가 스킬의 초안을 만들고, Figma Dev Mode와 명시적 분기점, 시각적 차이 비교가 정확도를 끌어올립니다.
자주 묻는 질문
Claude Code 스킬 파일이란 무엇인가요?
스킬은 필수 진입점인 SKILL.md를 포함한 폴더입니다. YAML 프런트매터(name, description)와 Markdown 본문으로 구성되며, 선택적으로 scripts/, references/, assets/, templates/ 하위 디렉터리를 둘 수 있습니다. 시작 시 시스템 프롬프트에 들어가는 것은 프런트매터 메타데이터뿐이며, 스킬당 대략 100토큰 정도입니다 . 이는 모델이 관련성을 판단하기에 충분합니다. 전체 본문은 작업이 설명과 일치하거나 /skill-name을 직접 호출할 때만 로드됩니다.
SKILL.md는 사용자 지정 슬래시 명령과 어떻게 다른가요?
.claude/commands/deploy.md 파일과 .claude/skills/deploy/SKILL.md 파일은 모두 같은 /deploy 항목을 만들지만, 스킬 형식에는 일반 명령에 없는 세 가지가 추가됩니다 . 참고 자료와 스크립트를 넣을 수 있는 지원 파일 디렉터리, when_to_use, allowed-tools, model, effort, hooks, context: fork 같은 호출 제어용 프런트매터, 그리고 명시적 /name 호출뿐 아니라 작업이 설명과 일치할 때 모델이 자동으로 로드하는 기능입니다.
SkillUI는 웹사이트에서 실제로 무엇을 추출하나요?
SkillUI는 순수 정적 DOM/CSS 분석을 수행합니다. AI 모델도 API 키도 사용하지 않으므로, 복구된 토큰은 실제 소스에 존재하는 내용에 근거합니다 . 기본 모드는 HTML과 CSS를 스크래핑해 색상 토큰, 타입 스케일, 간격 그리드, 컴포넌트 패턴을 찾습니다. 선택형 "ultra" 모드는 Playwright를 구동해 스크롤 여정 스크린샷, hover 및 focus 차이, 실제 Chromium 브라우저에서 캡처한 애니메이션 신호를 추가합니다 .
긴 세션 중에도 전체 SKILL.md 본문을 항상 사용할 수 있나요?
아니요. 보장되지 않습니다. 로드된 스킬 콘텐츠는 세션에 남지만, 컨텍스트 압축 중 잘릴 수 있습니다. 다시 붙는 스킬은 각각 처음 5,000토큰으로 예산이 잡히며, 전체 합산 한도는 25,000토큰입니다 . 예산 안에 머물려면 SKILL.md를 500줄 미만으로 유지하고, 더 긴 세부 내용은 references/ 하위 디렉터리로 옮기세요. 그러면 모델이 세션 내내 컨텍스트에 들고 있지 않고 필요할 때 열어볼 수 있습니다.
npm이나 GitHub에서 받은 타사 SKILL.md 파일을 설치해도 안전한가요?
신뢰할 수 있고 감사된 저장소에서만 설치하세요. Anthropic은 악성 스킬이 모델에게 명시된 목적 밖의 도구를 실행하도록 지시할 수 있다고 경고합니다. SKILL.md는 강제되는 코드가 아니라 운영 텍스트이기 때문입니다 . 2026년 공급망 연구도 이 위험을 확인했습니다. 설명으로 위장한 적대적 스킬 변형이 평균 77.6%의 선택률을 기록했으며 , 이는 정직한 대안보다 높았습니다. 설치하기 전에 프런트매터와 본문을 읽고, 직접 검토하고 버전 관리할 수 있는 스킬을 우선하세요.
이 글이 도움이 되셨다면, 새 글이 올라올 때마다 이메일로 받아보세요.
