“화면 반응형 점검할 땐 대표 기기 3종으로 실제로 열어서 눌러보고 고쳐줘.” 이런 다단계 지시를 매번 풀어 쓰는 건 낭비다. Claude Code의 Skill은 이 반복 절차를 파일 하나로 패키징해 두고, 필요할 때 꺼내 쓰게 한다. 그런데 이게 세션 안에서 정확히 어떤 원리로 로딩되고 발동되는지는 의외로 안 알려져 있다.
Skill의 정체 — 코드가 아니라 지시문
먼저 오해부터 걷어내자. Skill은 프로그램이 아니다. .claude/skills/이름/SKILL.md 라는 마크다운 파일 하나이고, 그 안에는 “이럴 때 이 순서로 행동하라”는 절차 텍스트가 들어 있다. 파일 맨 위에는 frontmatter가 붙는다.
---
name: responsive-check
description: >
반응형 디자인을 점검·개선할 때. 대표 breakpoint 기기로 실제
브라우저를 열어 E2E식으로 눌러보며 깨짐을 잡는다. 모바일/태블릿
레이아웃, 미디어쿼리, 뷰포트 작업에 발동. /responsive-check로도 호출.
---
# Responsive Check
1. dev 서버 기동 후 iPhone(390)·iPad(768)·Desktop(1280)로 연다
2. 각 뷰포트에서 스크린샷 + nav 클릭·링크 진입 등 실제 순회
3. 깨짐(오버플로·겹침·탭타겟) 진단 → CSS 수정 → 재검증발동되면 이 본문이 대화에 지시로 주입되고, 모델이 그걸 읽어 Bash로 서버를 띄우고 브라우저를 여는 실제 행동을 한다. 파일이 뭘 실행하는 게 아니라, 모델에게 건네는 행동 대본이다.
핵심 원리 — progressive disclosure
여기가 설계의 묘미다. 세션이 시작될 때 Claude Code는 스킬 폴더를 스캔하지만, 이때 컨텍스트에 올리는 건 각 파일의 frontmatter(name + description)뿐이다. 본문 수십 줄은 읽지 않는다.
그래서 스킬이 10개, 50개 있어도 세션이 짊어지는 무게는 한 줄짜리 설명 곱하기 개수뿐이다. 본문 전체는 그 스킬이 실제로 발동되는 순간에야 펼쳐진다. 필요할 때만 여는 이 방식을 progressive disclosure라 부른다. 스킬을 아무리 많이 만들어도 평소 토큰이 낭비되지 않는 이유이자, 무거운 절차를 본문에 마음껏 적어도 되는 이유다.
두 가지 발동 경로
펼쳐지는 방아쇠는 둘이다.
- 자동(모델 발동): 작업이 스킬의
description과 맞아떨어진다고 모델이 판단하면 스스로 그 스킬을 연다. 판단 근거가 오직 description이므로, 여기에 트리거가 될 키워드(“반응형”, “미디어쿼리”, “뷰포트”)를 넉넉히 심는 게 자동 발동의 전부다. - 수동(사용자 발동):
/responsive-check처럼 슬래시로 직접 부른다. description과 무관하게 강제로 연다.
즉 description은 “무엇을 하는가”의 설명이자 동시에 “언제 켜지는가”의 조건이다. 본문은 “어떻게 하는가”의 대본이고. 역할이 깔끔하게 갈린다.
CLAUDE.md와 뭐가 다른가
같은 “지시를 주입한다”라도 CLAUDE.md는 항상 컨텍스트에 상주한다. 모든 세션에서 늘 지켜야 하는 불변 규칙에 맞다. 반대로 Skill은 필요할 때만 펼쳐진다. 특정 상황에서만 도는 다단계 절차에 맞다. “반응형 점검 워크플로”처럼 가끔 쓰지만 쓸 때는 길고 구체적인 절차가 필요한 것 — 이게 정확히 스킬의 자리다.
마지막으로 저장 위치가 스코프를 가른다. .claude/skills/에 두고 커밋하면 레포를 받는 모든 사람의 세션에서 똑같이 발견·발동된다. ~/.claude/skills/에 두면 내 모든 프로젝트에서 나만 쓴다. 팀의 공통 워크플로냐 개인 습관이냐에 따라 고르면 된다.
이 글에 대한 의견은 아래 댓글로 남겨주세요 (GitHub 계정 필요). 로그인 없이 남기고 싶다면