Claude Skills를 제대로 쓰는 방법: 필요한 순간에만 불러오는 작업 지침

여러분, Claude Skills를 개념부터 어렵게 생각하시는 분들이 꽤 많은 것 같습니다. 그런데 결론부터 말하면 Skills는 굉장히 쉬운 개념입니다. 핵심 정의는 한 줄이거든요. 필요할 때 Claude가 불러올 수 있는 지침, 스크립트, 리소스가 포함된 폴더입니다. 여기서 제가 가장 중요하게 보는 표현은 “필요할 때”입니다. 모든 규칙을 항상 컨텍스트에 넣는 게 아니라, 특정 작업에 필요한 지침만 선택적으로 불러오는 구조이기 때문입니다.

이 차이가 실제 작업에서는 꽤 큽니다. Claude Code 기본 규칙이나 긴 전역 지침에 모든 것을 넣으면, 정작 쓰지 않는 정보까지 매번 컨텍스트를 차지하죠. 반면 Skills는 작업의 성격에 맞을 때만 로드되도록 설계할 수 있어서 컨텍스트가 훨씬 가볍습니다.

핵심 요약

• Claude Skills는 특정 작업에 필요한 지침, 스크립트, 리소스를 하나의 폴더로 묶는 구조입니다.
• 가장 중요한 부분은 name과 description 같은 메타데이터이며, Claude가 언제 스킬을 써야 하는지 판단하는 기준이 됩니다.
• 항상 로드되는 규칙 파일과 달리 Skills는 필요한 순간에만 컨텍스트로 들어오기 때문에 효율적입니다.
• Playwright MCP, Notion MCP처럼 외부 도구와 결합하면 웹 분석부터 문서화까지 이어지는 워크플로우를 만들 수 있습니다.
• 테스트 시나리오 생성, 스프레드시트 작업, 프레젠테이션 생성처럼 반복되는 전문 작업에 특히 잘 맞습니다.

Claude Skills의 기본 구조

폴더 단위로 작업 능력을 정의한다

Claude Skills는 보통 Claude 설정 경로의 skills 폴더 아래에 여러 개의 스킬 폴더를 두는 방식으로 구성됩니다. 각 스킬 폴더에는 스킬 설명 문서, 필요한 스크립트, 참고 리소스가 들어갈 수 있습니다.

이 구조의 장점은 작업별 전문성을 분리할 수 있다는 점입니다. 예를 들어 테스트 시나리오 생성 스킬, 문서 작성 스킬, 스프레드시트 분석 스킬을 각각 별도 폴더로 관리하면, Claude는 요청에 맞는 스킬만 골라 사용할 수 있습니다.

메타데이터가 호출 정확도를 결정한다

Skills에서 가장 중요한 건 사실 메타데이터입니다. 특히 name과 description이 Claude가 스킬을 언제 활용해야 하는지 판단하는 기준이 되죠. 설명이 너무 추상적이면 정작 필요할 때 호출되지 않거나, 반대로 필요하지 않은 상황에서 엉뚱하게 호출될 수 있습니다.

좋은 description은 트리거 조건을 구체적으로 적습니다. “문서 작업을 도와준다”보다 “웹사이트 URL을 받아 Playwright로 화면 요소를 분석하고 Given-When-Then 테스트 시나리오를 생성해 문서화한다”가 훨씬 좋죠. Claude가 이 두 줄만 보고 “아, 이럴 때 쓰는 스킬이구나”를 판단하니까요.

name: test-scenario-generator
description: 웹사이트 URL을 분석해 테스트 시나리오를 만들고 문서화할 때 사용한다.

컨텍스트 효율이 중요한 이유

항상 읽히는 규칙은 비용이 된다

AI 에이전트는 컨텍스트 안에 들어온 정보를 기준으로 작업합니다. 그래서 규칙을 많이 넣으면 더 똑똑해질 것 같지만, 실제로는 반대인 경우가 많습니다. 불필요한 규칙이 늘어날수록 정작 중요한 코드와 요구사항을 읽을 공간이 줄어듭니다.

Claude Skills는 바로 이 문제를 줄여 줍니다. 특정 작업을 할 때만 관련 지침을 불러오기 때문에, 기본 컨텍스트는 가볍게 유지하면서 필요한 순간에만 전문 지침을 꺼내 쓸 수 있습니다.

Subagent와 Skills는 역할이 다르다

기존에도 Claude에는 subagent 같은 기능이 있었습니다. 다만 제가 말하고 싶은 건, Skills는 컨텍스트 효율 면에서 결이 좀 다르다는 점입니다. Subagent는 특정 역할을 수행하는 에이전트 관점에 가깝고, Skills는 작업에 필요한 자료와 절차를 불러오는 패키지에 가깝습니다.

그래서 둘을 경쟁 관계로 보기보다 조합해서 쓰는 게 좋다고 봅니다. 복잡한 역할 분리는 subagent가 맡고, 반복 가능한 절차와 리소스는 Skills로 패키징하는 식이죠.

MCP와 결합하는 워크플로우

Playwright MCP로 웹페이지를 분석한다

제가 실제로 만들어 본 예시는 테스트 시나리오 생성 스킬입니다. 사용자가 웹사이트 URL을 주면, 스킬은 Playwright MCP를 사용해 웹페이지 구조, 버튼, 폼, 주요 요소를 분석합니다. 사람이 브라우저를 열어 화면을 보고 테스트 케이스를 떠올리는 과정을 AI가 대신해 주는 방식이죠.

이때 중요한 건 단순히 화면을 캡처하는 게 아니라, 테스트 가능한 사용자 행동을 식별하는 것입니다. 버튼 클릭, 폼 입력, 페이지 이동, 오류 상태 같은 요소가 테스트 시나리오의 재료가 됩니다.

Notion MCP로 문서화까지 연결한다

테스트 시나리오를 만들었다면 다음 문제는 이걸 어디에 남길 것인가입니다. 저는 Notion MCP를 활용해 분석 결과와 시나리오를 문서에 저장하는 흐름까지 붙였습니다. 즉, Skills는 단순 생성 도구가 아니라 “분석 → 작성 → 문서화”를 하나의 작업으로 묶을 수 있는 거죠.

이런 구조는 반복 업무에 특히 강합니다. 매번 같은 방식으로 웹사이트를 분석하고, 같은 형식으로 테스트 시나리오를 만들고, 같은 위치에 문서화하는 일이라면 Skills로 만들 가치가 큽니다.

좋은 Skill 설계 원칙

트리거를 좁고 명확하게 쓴다

스킬이 너무 넓은 범위를 담당하면 호출 기준이 흐려집니다. “개발을 도와주는 스킬”보다 “URL을 입력받아 테스트 시나리오를 생성하는 스킬”처럼 목적이 좁을수록 좋습니다.

산출물 형식을 고정한다

반복 작업에서 산출물 형식이 매번 달라지면 품질 관리가 어렵습니다. 테스트 시나리오라면 Given-When-Then, 우선순위, 전제 조건, 기대 결과 같은 필드를 고정해 두는 편이 좋습니다.

스크립트와 리소스를 함께 둔다

Skills는 지침만 담는 폴더가 아닙니다. 필요한 스크립트와 참고 리소스를 함께 둘 수 있습니다. 자주 쓰는 변환 스크립트, 템플릿, 예시 파일을 넣어두면 Claude가 매번 새로 만들지 않고 재사용할 수 있습니다.

스킬 폴더 구성과 SKILL.md 작성법

Claude Code에 스킬을 추가하는 방법은 간단합니다. .claude 경로에 skills 폴더를 만들고, 그 안에 스킬별 폴더를 하나씩 둡니다. 폴더 이름이 곧 스킬 이름이 되고, 각 폴더의 SKILL.md가 가장 핵심이 되는 파일입니다.

.claude/
  skills/
    test-scenario-generator/
      SKILL.md          # 메타데이터 + 핵심 지침
      templates/        # 시나리오 템플릿 같은 참고 문서
      notion-schema.json
      scripts/          # 필요하면 실행 가능한 셸 스크립트

SKILL.md는 맨 위에 YAML 형식의 메타데이터가 있고, 그 아래에 실제 지침(instruction)이 마크다운으로 들어갑니다. 제가 만든 스킬의 description은 “Playwright를 활용한 자동 테스트 시나리오 생성 및 Notion 업로드 스킬”이었습니다. 이 한 줄만 보고도 에이전트가 “테스트 시나리오를 만들거나 Notion에 올릴 때 쓰는 스킬이구나”라고 판단할 수 있게 쓰는 게 핵심이죠.

SKILL.md만으로 정보가 부족하면 Claude가 폴더 안의 서브 문서까지 알아서 찾아봅니다. 마크다운이나 JSON 같은 참고 문서를 넣을 수도 있고, 실제로 실행 가능한 셸 스크립트를 넣어 코드가 돌아가게 만들 수도 있습니다.

테스트 시나리오 생성 스킬의 5단계 워크플로우

지침에서 가장 중요한 부분은 핵심 워크플로우입니다. 저는 아래처럼 단계를 고정해 두었습니다.

단계	하는 일	사용하는 도구
1. 정보 수집	테스트 대상 URL 등 최소 정보를 받는다	사용자 입력
2. 페이지 분석	웹페이지를 직접 열어 구조, 버튼, 폼, 요소를 파악하고 시나리오를 도출한다	Playwright MCP
3. 시나리오 생성	미리 정의한 템플릿에 맞춰 Given-When-Then 시나리오를 작성한다	스킬 내 템플릿
4. 사용자 검토	작성한 시나리오 중 수정할 부분이 있는지 확인받는다	대화
5. 문서 업로드	Notion 테스트 시나리오 허브 데이터베이스에 업로드한다	Notion MCP

4단계처럼 사람의 검토를 중간에 넣어 두면, 잘못 도출된 시나리오가 그대로 팀 문서에 쌓이는 걸 막을 수 있습니다.

실행 전 준비: MCP 서버 설치 확인

이 스킬은 두 MCP 서버를 쓰기 때문에, 두 서버가 로컬에 설치돼 있어야 정상 동작합니다. claude mcp list로 Notion MCP와 Playwright MCP가 등록돼 있는지 먼저 확인하세요. Playwright는 원래 E2E 테스트를 작성하는 테스팅 라이브러리인데, MCP 서버로 쓰면 에이전트가 브라우저 동작을 직접 제어할 수 있습니다.

실제 호출 흐름

호출은 정말 간단합니다. 스킬을 이름으로 부를 필요 없이 “테스트 시나리오 생성 가능해?”라고만 물어도, Claude Code가 메타데이터를 보고 사용자 정의 스킬 중 test-scenario-generator가 있다고 찾아 줍니다.

저는 테스트 연습용 데모 쇼핑몰 사이트 URL을 넣고 “인증, 상품, 장바구니에 대한 테스트 시나리오를 작성해 보자”라고 요청했습니다. 그러면 Claude Code가 스킬 호출 여부를 묻고, 승인하면 Playwright MCP로 Chrome 브라우저를 열어 페이지를 돌아다닙니다. 로그인도 해 보고 장바구니에 상품도 담아 보면서 구조를 파악한 뒤 시나리오를 작성하죠. 예전에는 QA 담당자가 웹페이지를 직접 확인하며 시나리오를 써야 했던 과정을 에이전트에게 맡길 수 있다는 게 가장 큰 장점이라고 봅니다.

Notion 스키마를 JSON으로 두는 이유

작성된 시나리오는 로컬 마크다운으로 관리해도 되지만, 팀원과 공유하려면 Notion 같은 협업 도구가 더 효율적입니다. 업로드 대상인 테스트 시나리오 허브 데이터베이스는 시나리오 ID, 기능 구분, 우선순위, 상태, 작성 일자, 링크, 메모 같은 컬럼으로 구성했습니다.

여기서 팁은 데이터베이스 컬럼 정보를 notion-schema.json 같은 파일로 스킬 폴더에 넣어 두는 겁니다. 이 파일도 제가 직접 쓰지 않았습니다. 데이터베이스 URL을 주고 “이 데이터베이스의 스키마를 검토해서 JSON으로 만들어 줘”라고 요청해 만든 거죠. 스키마가 있으면 스킬이 Notion MCP로 데이터베이스 구조를 파악한 뒤 우선순위, 프로젝트명, 초안 상태 같은 메타데이터까지 맞춰 한 건씩 업로드합니다. 각 페이지 본문도 스킬에 정의한 템플릿과 똑같은 형식으로 채워집니다.

Subagent로 시나리오 작성을 병렬화하기

한 가지 아이디어를 더 드리면, Skills와 subagent를 조합해 속도를 올릴 수 있습니다. subagent를 쓰지 않으면 하나의 에이전트가 시나리오 1, 2, 3, 4를 순차적으로 끝내야 전체 작업이 완료됩니다. 반면 subagent를 쓰면 서로 의존성이 없는 시나리오를 골라 “1, 2번은 첫 번째 subagent가, 3, 4번은 두 번째 subagent가” 하는 식으로 나눠 병렬로 처리할 수 있죠.

이렇게 하면 전체 작업 시간이 크게 줄어듭니다. 앞에서 말한 역할 분담이 바로 이겁니다. 절차와 템플릿은 Skills로 패키징하고, 병렬 실행과 역할 분리는 subagent가 맡는 구조입니다.

마무리

정리하면, Claude Skills는 특정 작업을 더 잘하게 만드는 작업 패키지입니다. 핵심은 모든 지식을 항상 주입하는 게 아니라, 필요한 순간에 필요한 지침과 리소스만 불러오는 것이죠.

그래서 제가 드리고 싶은 말은 이겁니다. 실무에서 자주 반복되는 작업이 있다면, 한 번쯤 Skills로 분리해 보시면 좋겠습니다. 웹 분석, 테스트 시나리오 생성, 문서화, 스프레드시트 처리, 프레젠테이션 작성처럼 절차가 반복되고 산출물 형식이 중요한 작업일수록 잘 맞습니다. 좋은 Skills는 AI에게 일을 더 많이 시키는 도구가 아닙니다. 같은 일을 더 일관되게 수행하게 만드는 운영 단위라고 봅니다.

덧붙이면, Skills가 꼭 Claude에만 있는 기능은 아닙니다. Cursor Rules도 메타데이터에 적용 조건을 적어 두면 필요한 상황에만 규칙이 붙는 식으로, 비슷한 역할을 하게 만들 수 있죠. 다만 멀티 에이전트 워크플로우를 구성하는 관점에서는 Skills 쪽이 좀 더 에이전트답게 동작하는 것 같습니다.

---

관련 영상

이 글과 연결된 영상은 개발동생 유튜브 채널에서 보기에서 확인할 수 있습니다.