공부 / AI / claude

skill

작성
수정
#AI

skill은 클로드에게 어떠한 리퀘스트를 주면 어떠한 절차에 따라서 그 해당하는일을 어떻게 처리를 하게 할 수 있는 기능입니다.

똑같은 일을 똑같이 처리를 하는 기능.
여러가지 조사를 하지않고 제시해주는 방향으로만 가게함.
워크 탬플릿처럼 동작하여 여러사람이 사용이 가능함.
오토메팅한 워크플로우대로 동작을 시키는 것도 가능함.

hook과의 차이점은

  1. skill : claude가 판단하여 해당하는 스킬을 사용하여야하겠다 라는 판단이 들어서고 해당하는 스킬을 가져와서 사용함 "이 작업을 어떻게 하는지"에 대한 지식/절차를 담는 용도에 가까움
  2. hook : claude의 판단이 개입되지않음 특정한 작업이 들어왔을때 무조건적으로 실행함 "무조건 이렇게 해야 한다/하면 안 된다"는 규칙을 강제하는 용도

SKILL.md의 구성
맨위는 YAML Frontmatter로 이루어짐
name : command name
description : when and how to use it
invocation controls : manual vs automatic
allowed tools
그리고 스킬에 대한 설명으로 이루어짐.

스킬 작성법

먼저 알아둬야 하는게 스킬은 학습하지 않습니다. 매번 같은 파일을 읽는 고정 지침서일 뿐입니다. 그래서 스킬에 무언가를 학습시키고 싶으면 두 조각으로 쪼개야 합니다. 명령어가 자료를 읽고 참고 파일을 갱신하는 추출 역할을 하고 스킬은 그 참고 파일을 읽어서 따르는 적용 역할만 합니다.

스킬은 Progressive Disclosure라고 해서 3단계로 나눠서 읽힙니다.

  1. frontmatter : 항상 컨텍스트에 들어감
  2. SKILL.md 본문 : 트리거될 때 읽힘
  3. references/, scripts/ : 본문이 지시할 때만 읽힘

그래서 본문에 다 쓰면 안됩니다. 본문에는 워크플로우만 두고 상세 내용은 references/로 분리해야 합니다.

description이 트리거의 전부입니다. 본문에 "이럴 때 써라"를 아무리 써도 소용없는데, 본문은 트리거된 다음에야 읽히기 때문입니다. 단 클로드는 스킬을 과소 트리거하는 경향이 있어서 description을 약간 밀어붙이게 써야 합니다.

글쓰기 스타일을 정하는 스킬의 경우 "하지 마라" 목록이 "해라" 목록보다 중요합니다. AI 티는 대부분 특정 패턴 때문에 나기 때문에 그 패턴을 막는게 먼저입니다.

아래는 Anthropic 공식 문서인 Skill authoring best practices와 The Complete Guide to Building Skills for Claude, Claude Code 스킬 문서, 그리고 스킬을 많이 만들어 공개한 Matt Pocock과 superpowers의 스킬 작성 가이드를 보고 정리한 내용입니다.

만들기 전에

먼저 이 스킬로 해결할 구체적인 사용 사례를 2~3개 정해야 합니다. 사용자가 어떤 말을 할 때 트리거되는지, 어떤 단계를 거치는지, 결과가 뭔지까지 적어두면 됩니다. Anthropic이 가장 효과적인 방법으로 꼽는 건 스킬 없이 어려운 작업 하나를 Claude와 끝까지 성공시킨 다음 그 과정을 스킬로 뽑아내는 것입니다. 작업하면서 내가 반복해서 알려준 맥락과 규칙이 곧 스킬에 들어갈 내용이 됩니다.

만들 가치가 있는지도 따져봐야 합니다. 한 번 쓰고 끝날 해결책, 이미 문서가 잘 되어 있는 표준, 한 프로젝트에만 해당하는 규칙은 스킬로 만들 필요가 없습니다. 프로젝트 규칙은 CLAUDE.md에 넣으면 되고, 정규식이나 검증 스크립트로 막을 수 있는 기계적인 규칙은 문서보다 자동화가 맞습니다.

frontmatter와 description

파일 이름은 정확히 SKILL.md여야 합니다. 대소문자까지 구분해서 skill.md는 인식되지 않고, 스킬 폴더 안에 README.md도 넣지 않습니다. 설명은 전부 SKILL.md나 references/에 둡니다.

---
# 폴더명과 같게, 소문자·숫자·하이픈만, 64자 이하
name: writing-weekly-reports
# 무엇을 하는지 + 언제 쓰는지, 3인칭, 1024자 이하
description: Generates weekly report drafts from Linear issues. Use when the user asks for a weekly report, 주간 보고, or a summary of this week's tickets.
---

name에는 claude, anthropic 같은 예약어가 못 들어가고 frontmatter 어디에도 <, > 같은 XML 꺾쇠를 쓸 수 없습니다. frontmatter는 시스템 프롬프트에 그대로 들어가서 프롬프트 인젝션 통로가 될 수 있기 때문입니다. 이름은 processing-pdfs처럼 동명사(-ing)로 짓거나 pdf-processing 같은 명사구로 짓고, helper, utils처럼 뭘 하는지 안 보이는 이름은 피하라고 합니다.

description은 항상 3인칭으로 씁니다. 시스템 프롬프트에 들어가는 문장이라 "I can help you~"나 "You can use this~"처럼 시점이 섞이면 스킬을 찾는데 문제가 생길 수 있습니다. 내용은 무엇을 하는지와 언제 쓰는지를 둘 다 넣고, 언제 쓰는지에는 사용자가 실제로 칠 법한 표현이나 파일 확장자를 넣습니다. 한국어로 요청하는 경우가 많으면 위 예시처럼 한국어 표현도 같이 넣어두면 됩니다.

단 description에 스킬의 작업 순서를 요약하면 안 됩니다. superpowers 쪽 실험에서 description에 "작업 사이에 코드 리뷰"라고 요약해뒀더니 본문 플로우차트에는 리뷰가 두 번 있는데도 에이전트가 리뷰를 한 번만 했다고 합니다. description만 보고 본문을 건너뛴 겁니다. 그래서 무엇을 하는지는 짧게 밝히고 어떤 순서로 하는지는 본문에만 둬야 합니다.

트리거가 잘 안 되면 Claude한테 "언제 ○○ 스킬을 쓸 거야?"라고 물어보면 됩니다. Claude가 description을 거의 그대로 읊어줘서 빠진 키워드가 뭔지 보입니다. 반대로 너무 자주 트리거되면 "Do NOT use for ~"처럼 쓰면 안 되는 경우를 적거나 범위를 더 좁히면 됩니다. Claude Code에서는 description과 when_to_use를 합친 글자가 1,536자에서 잘리고, 스킬이 많아서 목록 예산(컨텍스트 윈도우의 1% 정도)을 넘으면 덜 쓰는 스킬부터 description이 빠집니다. 가장 중요한 사용 사례를 description 맨 앞에 두는 이유입니다.

본문 쓰는 법

본문은 Claude는 이미 똑똑하다는 전제에서 시작합니다. Claude가 모르는 것만 쓰고 문단마다 이 설명이 토큰 값을 하는지 따져봐야 합니다. 스킬 내용은 한 번 로드되면 세션 내내 컨텍스트에 남아서 한 줄 한 줄이 매 턴 반복되는 비용이 되기 때문입니다. PDF가 뭔지, 라이브러리가 왜 필요한지 같은 설명은 빼고 "텍스트 추출은 pdfplumber를 써라"와 코드 몇 줄이면 충분합니다. Claude가 원래 알아서 하는 행동을 시키는 문장도 토큰만 먹는 no-op이라 문장째 지웁니다.

지시를 얼마나 빡빡하게 쓸지는 작업이 얼마나 깨지기 쉬운지로 정합니다. Anthropic은 이걸 길에 비유하는데, 양옆이 절벽인 좁은 다리처럼 순서 하나만 틀려도 끝나는 작업(DB 마이그레이션 등)은 정확한 스크립트를 주고 "이 명령어를 그대로 실행하고 플래그를 바꾸지 마라" 수준으로 좁게 씁니다. 장애물 없는 넓은 들판처럼 상황마다 답이 다른 작업(코드 리뷰 등)은 방향만 주고 판단을 맡깁니다. 그 사이는 파라미터가 있는 템플릿이나 의사코드로 줍니다.

지시할 때는 MUST, NEVER를 대문자로 박는 것보다 왜 그래야 하는지를 설명하는게 더 잘 먹힙니다. skill-creator 가이드는 대문자 ALWAYS나 NEVER가 보이면 노란불이라고까지 합니다. 요즘 모델은 이유를 알면 예시에 없는 상황에도 알아서 응용하기 때문입니다. 금지 문장도 비슷한데, Matt Pocock은 "코끼리를 생각하지 마"라고 하면 코끼리만 떠오르듯이 금지 문장이 오히려 그 행동을 컨텍스트에 끌어올린다고 봅니다. 그래서 위에서 말한 "하지 마라" 목록도 항목마다 대신 뭘 써야 하는지 긍정형 목표를 같이 적어둬야 효과가 있습니다.

references/로 나눌 때는 SKILL.md에서 한 단계 깊이까지만 링크합니다. A 파일이 B를 가리키고 B가 다시 C를 가리키는 식으로 중첩되면 Claude가 head -100처럼 앞부분만 훑고 넘어가서 정보를 놓칠 수 있습니다. 100줄이 넘는 참고 파일은 맨 위에 목차를 넣어둬야 일부만 읽어도 전체 범위를 알 수 있습니다. 그 외에 같은 대상은 끝까지 같은 용어로 부르고, "2025년 8월 이전이면 옛 API를 써라" 같은 날짜 조건은 금방 틀린 정보가 되니 "옛 방식" 섹션으로 따로 뺍니다. 선택지도 여러 개 늘어놓지 말고 기본값 하나와 예외 상황 하나 정도만 줍니다.

단계가 많은 작업은 Claude가 복사해서 하나씩 체크할 수 있는 체크리스트를 넣어두면 검증 단계를 건너뛰는 일이 줄어듭니다. 각 단계에는 끝났는지 판단할 수 있는 완료 기준이 있어야 하는데, "이해가 되면 다음으로"처럼 흐릿하게 쓰면 뒤에 남은 단계로 넘어가고 싶어서 대충 끝내버리기 쉽습니다. "수정한 모델을 전부 확인했다"처럼 확인할 수 있고 빠짐없는 기준이 가장 강합니다. 품질이 중요한 작업은 검증 → 수정 → 재검증 루프를 명시하고, 대량 수정이나 되돌리기 어려운 작업은 계획을 changes.json 같은 중간 파일로 먼저 뽑아서 스크립트로 검증한 뒤에 실행하게 만듭니다.

스크립트를 같이 넣을 때는 실행하라는 건지 읽어보라는 건지를 분명히 적어야 합니다. 실행만 하면 출력만 토큰을 먹고 코드 자체는 컨텍스트에 안 들어가서 효율적입니다. 에러는 Claude한테 떠넘기지 말고 스크립트 안에서 처리하고, TIMEOUT = 47처럼 이유 없는 숫자는 왜 그 값인지 주석을 답니다. 꼭 지켜야 하는 검증은 말로 지시하는 것보다 스크립트로 박아두는게 확실한데, 코드는 결정적이지만 언어 해석은 그렇지 않기 때문입니다. MCP 툴을 부를 때는 GitHub:create_issue처럼 서버 이름까지 붙인 전체 이름을 써야 툴을 못 찾는 문제가 안 생깁니다.

누가 호출할지 정하기

Claude Code에서는 frontmatter로 스킬을 누가 부를지 정할 수 있습니다. 기본값은 나도 /스킬이름으로 부를 수 있고 Claude도 알아서 부를 수 있는 상태입니다. disable-model-invocation: true를 붙이면 나만 부를 수 있는데, 배포나 커밋, 메시지 전송처럼 부작용이 있어서 타이밍을 내가 정해야 하는 작업에 씁니다. 이때는 description이 컨텍스트에 아예 올라가지 않아서 토큰도 안 먹습니다. 반대로 user-invocable: false는 / 메뉴에서 숨겨서 Claude만 부를 수 있게 하는데, 레거시 시스템 설명처럼 명령어로 실행할 의미는 없고 배경지식으로만 필요한 스킬에 씁니다.

Matt Pocock은 이 선택을 두 가지 부담의 교환으로 설명합니다. Claude가 부를 수 있는 스킬은 description이 매 턴 컨텍스트에 올라가는 비용을 내는 대신 알아서 찾아지고, 나만 부르는 스킬은 컨텍스트 비용이 0인 대신 그런 스킬이 있다는 걸 내가 기억해야 합니다. 그래서 Claude나 다른 스킬이 스스로 찾아야 하는 경우가 아니면 나만 부르는 스킬로 두라고 하는데, grill-me가 이렇게 되어 있습니다.

그 외에 자주 쓰는 필드는 아래 정도입니다. model, effort로 스킬이 도는 동안만 모델과 effort를 바꿀 수도 있고, paths에 glob을 주면 그 경로의 파일을 다룰 때만 자동으로 로드됩니다.

---
name: pr-summary
description: Summarizes a pull request. Use when the user asks what a PR changes.
argument-hint: "[pr-number]"  # 자동완성 때 보이는 인자 힌트
allowed-tools: Bash(gh *)     # 이 스킬이 실행되는 턴 동안 권한 확인 없이 쓸 툴
context: fork                 # 서브 에이전트에서 따로 실행
agent: Explore                # fork할 때 쓸 에이전트 종류
---

context: fork로 돌리면 서브 에이전트는 지금까지의 대화를 보지 못합니다. 그래서 본문만 읽고도 할 일을 알 수 있게 써야 하고, "이 API 규칙을 따라라" 같은 가이드라인만 있는 스킬을 fork하면 할 일이 없어서 빈손으로 돌아옵니다.

본문에서는 $ARGUMENTS(또는 $0, $1)로 호출할 때 넘긴 인자를 받고, ${CLAUDE_SKILL_DIR}로 스킬 폴더 경로를 받아서 번들 스크립트를 부릅니다. 또 줄 맨 앞이나 공백 뒤에 !`git diff HEAD`처럼 쓰면 스킬 내용이 Claude한테 가기 전에 명령어가 먼저 실행되고 그 결과가 그 자리에 들어갑니다. !로 실행한 명령어 결과가 컨텍스트로 들어가는 것과 비슷한데, Claude가 추측이 아니라 실제 데이터를 보고 시작하게 만들 수 있습니다.

커스텀 커맨드는 스킬로 합쳐져서 .claude/commands/deploy.md와 .claude/skills/deploy/SKILL.md는 둘 다 /deploy를 만들고 똑같이 동작합니다. 새로 만들 땐 보조 파일을 같이 둘 수 있는 스킬 폴더 형식을 쓰면 됩니다. 단 위 필드들은 대부분 Claude Code 전용이라, claude.ai에 올리거나 API로 쓰는 스킬은 오픈 표준인 Agent Skills 필드(name, description, license, compatibility, metadata, allowed-tools)만 쓸 수 있고 다른 필드가 있으면 업로드가 에러로 실패합니다.

스킬 내용은 한 번 로드되면 세션 내내 남아 있지만 자동 compact가 일어나면 스킬마다 앞 5,000토큰만, 전부 합쳐 25,000토큰까지만 다시 붙습니다. 중요한 지시를 본문 앞쪽에 둬야 하는 이유이고, compact 뒤로 스킬 영향력이 약해졌다 싶으면 다시 호출하면 됩니다. 계속 지켜야 하는 규칙이 자꾸 무시되면 description과 지시를 강화하거나 hooks로 강제합니다.

테스트와 반복

스킬이 트리거됐다고 제대로 동작한다는 뜻은 아닙니다. 불러야 할 때 부르는지(트리거)와 불렀을 때 결과가 맞는지(기능)를 따로 봐야 합니다.

Anthropic은 문서를 쓰기 전에 평가부터 만들라고 합니다. 먼저 스킬 없이 Claude한테 대표 작업을 시켜서 어디서 틀리는지 기록하고, 그 빈틈을 확인하는 시나리오를 3개 만들고, 스킬 없는 상태의 결과를 기준선으로 잡은 다음, 빈틈을 메울 만큼만 지시를 씁니다. 상상으로 요구사항을 채우지 않고 실제로 틀린 부분만 고치는 방식입니다. superpowers의 writing-skills는 이걸 아예 TDD로 봅니다. 스킬 없이 서브 에이전트한테 압박 시나리오를 줘서 규칙을 어기는 걸 먼저 보고(RED) 그때 댄 핑계를 그대로 적어둔 뒤, 그 핑계만 막는 최소한의 스킬을 쓰고(GREEN), 새 핑계가 나오면 계속 막습니다(REFACTOR). 실패하는 걸 먼저 보지 않았다면 스킬이 뭘 가르치는지 모르는 거라는 입장입니다.

Claude 두 개를 쓰는 방법도 있습니다. Claude A와 같이 스킬을 쓰고 다듬고, 스킬을 로드한 새 Claude B한테 실제 작업을 시켜서 어디서 헤매는지 본 다음 그걸 다시 A한테 가져가는 식입니다. 테스트는 꼭 새 세션에서 해야 하는데, 스킬을 쓰면서 쌓인 맥락이 남아 있으면 문서에 빠진 부분이 가려지기 때문입니다. 관찰할 때는 예상과 다른 순서로 파일을 읽는지, 중요한 참고 파일을 안 여는지 봅니다. 같은 파일만 계속 읽는다면 그 내용은 본문으로 올릴 대상이고, 한 번도 안 읽는 파일은 필요 없거나 안내가 약하다는 뜻입니다.

트리거 테스트는 불러야 하는 질문과 부르면 안 되는 질문을 섞어서 돌립니다. skill-creator는 각각 8~10개씩 20개 정도를 만들라고 하는데, 부르면 안 되는 쪽은 뻔히 상관없는 질문 말고 키워드는 겹치지만 실제로는 다른 게 필요한 애매한 질문이어야 의미가 있습니다. "이 PDF 읽어줘"처럼 단순한 요청은 Claude가 기본 도구로 바로 처리해버려서 description이 완벽해도 스킬을 안 부르니, 테스트 질문은 여러 단계가 필요한 구체적인 요청으로 만듭니다. 목표는 관련 질문의 90% 정도에서 트리거되는 것입니다. Haiku, Sonnet, Opus처럼 쓸 model마다 돌려보는 것도 필요한데, Opus에서 충분하던 설명이 Haiku에는 모자랄 수 있고 반대로 Opus한테는 과할 수 있습니다.

도구로는 Anthropic의 skill-creator 플러그인이 있습니다. /plugin install skill-creator@claude-plugins-official로 설치하면 테스트 케이스를 evals/evals.json에 저장하고, 스킬이 있을 때와 없을 때를 서브 에이전트로 따로 돌려서 통과율·시간·토큰을 비교해주고, description만 따로 튜닝해주는 기능도 있습니다. plugin에 들어간 스킬은 claude plugin eval로 같은 비교를 CI에 걸 수 있습니다.

자주 막히는 부분도 있습니다. frontmatter YAML이 깨지면 스킬은 메타데이터 없이 로드돼서 /스킬이름으로는 불리는데 자동 트리거는 안 됩니다. 이건 claude plugin validate ~/.claude/skills나 --debug로 파싱 에러를 찾을 수 있습니다. 로드는 되는데 지시를 안 따르면 대부분 본문이 너무 길거나, 중요한 지시가 아래에 묻혀 있거나, "잘 검증해라"처럼 모호하게 써서입니다. 스킬을 수십 개씩 켜두면 목록만으로 context를 먹어서 응답 질이 떨어질 수 있는데, /skill-doctor로 스킬별 컨텍스트 비용과 안 쓰는 스킬을 확인할 수 있습니다.