매번 붙여넣던 지시를 폴더 하나로 — Agent Skill 입문
2026.07.24 게시
같은 지시를 세 번째 붙여넣고 있다면, 그게 Skill을 쓸 때다.
커밋 메시지 규칙, 배포 전 확인 순서, 우리 팀 API 응답 포맷. 새 대화를 열 때마다 같은 설명을 다시 하고 있었다면 그 반복이 Skill이 없애려는 문제다. 이 글은 Skill을 한 번도 만들어보지 않은 사람을 기준으로, 무엇이고 · 왜 그렇게 생겼고 · 어떻게 하나 만들어보는지까지를 정리한 것이다.
먼저 범위를 밝혀둔다. 이 글은 2026년 7월 기준 Anthropic 공식 문서를 기준으로 개념과 사용법을 정리한 글이다. Skill은 제품 버전에 따라 세부 동작이 자주 바뀌는 기능이라, 특정 버전에 묶인 내용은 본문에서 따로 표시했다. 실제 스킬을 만들어 두 에이전트에서 재현성을 측정한 실험 기록은 이 블로그의 Agent SDD 개발 일지 시리즈 쪽에 있다.
목차
1. Skill은 폴더 하나다
정의부터 단순하다. Skill은 SKILL.md 파일이 들어 있는 폴더 하나다.
프레임워크도, 등록 API도, 빌드 과정도 없다. 정해진 위치에 폴더를 만들고 그 안에 마크다운 파일 하나를 두면 끝이다.
SKILL.md는 두 부분으로 나뉜다.
- 위쪽 YAML 블록(프론트매터) — 이 스킬이 무엇이고 언제 쓰는 것인지 설명하는 메타데이터
- 아래쪽 마크다운 본문 — 스킬이 실제로 불렸을 때 Claude가 따를 지시문
나머지 파일은 전부 선택이다. 참고 문서를 따로 두고 싶으면 reference.md를 만들고, 스크립트를 실행시키고 싶으면 scripts/ 아래에 넣으면 된다. 이 파일들은 SKILL.md에서 “이런 내용이 여기 있다”고 언급해두면 Claude가 필요할 때 알아서 읽는다.
작은 차이 하나: Claude Code에서는 프론트매터의
name이 선택 항목이고, 생략하면 폴더 이름이 그대로 쓰인다. 반면 Claude API나 claude.ai에 스킬을 올릴 때는name과description이 필수다. 처음엔 그냥 둘 다 쓰는 걸 권한다.
2. 왜 이렇게 생겼나 — 점진적 로딩
Skill 구조를 이해하는 핵심은 하나다. 모든 내용이 한꺼번에 컨텍스트에 들어가지 않는다.
CLAUDE.md에 절차를 길게 써두면 그 내용은 세션 내내 컨텍스트를 차지한다. 그래서 CLAUDE.md는 길어질수록 부담이 된다. Skill은 그 부담을 세 단계로 나눠 미룬다.
여기서 나오는 실용적인 결론이 두 개 있다.
하나. 스킬은 많이 깔아도 된다. 안 쓰는 스킬은 이름과 설명 한 줄만큼만 비용이 든다. 공식 문서 기준으로 스킬당 약 100 토큰이다. “혹시 쓸까 봐” 넣어둔 스킬 20개가 있어도 실제 부담은 크지 않다.
둘. 본문은 짧게 써야 한다. 스킬이 한 번 호출되면 그 본문은 세션이 끝날 때까지 컨텍스트에 남는다. 공식 문서는 SKILL.md를 500줄 이내로 유지하고, 긴 참고 자료는 별도 파일로 빼라고 권한다. 이건 뒤의 “걸리는 것들” 절에서 다시 다룬다.
3. 스킬은 언제 불려오나 — description이 트리거다
처음 스킬을 만든 사람이 가장 많이 하는 실수가 여기 있다. description을 설명문으로 쓴다는 것이다.
description은 설명이 아니라 트리거다. 세션이 시작되면 Claude의 컨텍스트에는 설치된 모든 스킬의 이름과 description만 올라가 있다. 사용자가 뭔가를 요청하면 Claude는 그 요청을 이 description 목록과 맞춰보고, 맞는 게 있으면 그때 파일을 읽는다. description에 없는 단어로는 스킬이 걸리지 않는다.
그래서 description에는 무엇을 하는지와 언제 쓰는지를 둘 다 써야 한다. 공식 문서의 예시가 이 형태를 잘 보여준다.
# 나쁜 예 — 무엇인지만 있다
description: PDF 처리 도구
# 좋은 예 — 무엇을, 언제 쓰는지가 함께 있다
description: PDF에서 텍스트와 표를 추출하고, 양식을 채우고, 문서를 병합한다.
PDF 파일을 다룰 때, 또는 사용자가 PDF·양식·문서 추출을 언급할 때 사용한다.
“언제 쓰는지”를 쓸 때는 사용자가 실제로 입력할 법한 단어를 넣는 게 요령이다. 내가 아는 정식 용어가 아니라, 그 상황에서 자연스럽게 나올 말이어야 한다.
그리고 매칭에 기대지 않는 경로도 있다. /스킬이름을 직접 입력하면 매칭 단계를 건너뛰고 바로 호출된다. Claude Code에서 이 이름은 폴더 이름에서 온다. .claude/skills/deploy-staging/SKILL.md는 /deploy-staging이 된다.
4. 5분 만에 하나 만들어보기
개념은 여기까지면 충분하다. 하나 만들어보는 게 빠르다. 아래는 Claude Code 기준이다.
1단계 — 지시문만 있는 가장 단순한 스킬
폴더를 만든다.
mkdir -p ~/.claude/skills/commit-msg
~/.claude/skills/commit-msg/SKILL.md에 이걸 저장한다.
---
name: commit-msg
description: 커밋 메시지를 팀 규칙에 맞춰 작성한다.
사용자가 커밋 메시지를 써달라고 하거나, 변경사항을 커밋하려 할 때 사용한다.
---
커밋 메시지는 아래 규칙을 지킨다.
1. 첫 줄은 `<타입>: <요약>` 형태로 쓰고 50자를 넘기지 않는다.
2. 타입은 feat, fix, refactor, docs, test, chore 중 하나만 쓴다.
3. 본문에는 무엇을 바꿨는지가 아니라 왜 바꿨는지를 쓴다.
4. 이슈 번호가 있으면 마지막 줄에 `Refs: #123` 형태로 붙인다.
끝이다. Claude Code를 열고 두 가지 방법으로 확인할 수 있다.
/commit-msg라고 직접 입력한다.- 또는 그냥 “커밋 메시지 좀 써줘”라고 말한다.
description이 걸리면 Claude가 알아서 이 스킬을 불러온다.
두 번째 방법이 동작하지 않는다면 그건 description 문제일 가능성이 높다. 이게 바로 3절에서 말한 트리거 이야기다.
2단계 — 실제 데이터를 끌어오기
위 스킬에는 약점이 있다. Claude가 지금 무엇이 바뀌었는지 모른다는 것이다. Claude Code에는 스킬 내용이 Claude에게 전달되기 전에 셸 명령을 실행하고 그 출력으로 자리를 채워주는 문법이 있다.
---
name: commit-msg
description: 스테이징된 변경사항을 읽어 팀 규칙에 맞는 커밋 메시지를 작성한다.
사용자가 커밋 메시지를 써달라고 하거나, 변경사항을 커밋하려 할 때 사용한다.
allowed-tools: Bash(git diff *)
---
## 현재 스테이징된 변경사항
!`git diff --staged`
## 지시
위 변경사항을 읽고 커밋 메시지를 작성한다.
1. 첫 줄은 `<타입>: <요약>` 형태로 쓰고 50자를 넘기지 않는다.
2. 타입은 feat, fix, refactor, docs, test, chore 중 하나만 쓴다.
3. 본문에는 무엇을 바꿨는지가 아니라 왜 바꿨는지를 쓴다.
4. 스테이징된 변경이 없으면 그렇다고만 답한다.
!`git diff --staged` 부분이 핵심이다. 이건 Claude가 실행하는 명령이 아니라 전처리다. 순서는 이렇다.
- 스킬이 호출되면 Claude Code가 먼저
git diff --staged를 실행한다. - 그 출력이 해당 줄을 대체한다.
- Claude는 diff가 이미 채워진 상태의 문서를 받는다.
덕분에 Claude가 “지금 뭐가 바뀌었지?”를 추측하거나 별도로 도구를 부를 필요가 없다. 다만 이 문법은 Agent Skills 표준이 아니라 Claude Code가 추가한 확장이다. 다른 도구에서도 쓰려면 이 부분은 빼야 한다.
allowed-tools는 이 스킬이 호출된 그 턴 동안 해당 도구를 승인 없이 쓰게 해주는 항목이다. 매번 “이 명령 실행해도 됩니까” 확인을 받지 않아도 된다. 대신 권한을 열어주는 것이므로, 남의 스킬에서 이 줄을 볼 때는 주의해야 한다.
5. 어디에 둘 것인가
같은 스킬이라도 어느 폴더에 두느냐에 따라 적용 범위가 달라진다.
| 위치 | 경로 | 적용 범위 |
|---|---|---|
| 개인 | ~/.claude/skills/이름/SKILL.md |
내 모든 프로젝트 |
| 프로젝트 | .claude/skills/이름/SKILL.md |
그 저장소에서만 |
| 플러그인 | 플러그인/skills/이름/SKILL.md |
플러그인이 켜진 곳 |
처음에는 개인 폴더에서 시작하는 게 편하다. 쓸 만하다는 확신이 서면 프로젝트 폴더로 옮겨 커밋하면 팀 전체가 같은 스킬을 쓰게 된다. 팀 규칙을 코드처럼 버전 관리한다는 게 프로젝트 스킬의 실질적인 값이다.
같은 이름이 여러 곳에 있으면 엔터프라이즈 › 개인 › 프로젝트 순으로 덮어쓴다. 팀이 커밋해둔 deploy 스킬이 있는데 내 개인 폴더에도 deploy가 있으면 내 것이 쓰인다는 뜻이다. 팀 스킬이 안 먹는 것 같을 때 한 번 의심해볼 지점이다.
한 가지 더. 스킬은 제품 간에 자동으로 동기화되지 않는다. claude.ai에 올린 스킬은 API에서 쓸 수 없고, Claude Code의 파일 기반 스킬은 나머지 둘과 별개다. 쓰려는 곳마다 따로 올려야 한다.
6. Skill · CLAUDE.md · MCP · Subagent, 뭐가 다른가
이 넷이 헷갈리는 게 정상이다. 겹치는 영역이 있다. 기준을 하나만 잡으면 대체로 갈린다.
- CLAUDE.md — 항상 참이고 짧은 사실. “이 프로젝트는 pnpm을 쓴다.” 세션 내내 들고 있어도 부담이 없을 만큼 짧아야 한다.
- Skill — 여러 단계로 된 절차나 체크리스트. CLAUDE.md의 한 항목이 “사실”에서 “절차”로 자라나는 순간이 스킬로 뺄 때다.
- MCP — 외부 시스템에 실제로 연결해야 할 때. 이슈 트래커를 읽거나 사내 API를 호출하는 건 문서로 해결되지 않는다.
- Subagent — 지금 대화 컨텍스트와 분리해서 돌리고 싶은 작업.
배타적인 선택은 아니다. 스킬 프론트매터에 context: fork를 붙이면 그 스킬이 별도 서브에이전트 컨텍스트에서 실행된다. 조사나 리뷰처럼 결과만 받고 싶은 작업에 쓴다.
7. 처음 쓸 때 걸리는 것들
문서만 읽고 넘어가면 나중에 한 번씩 부딪히는 지점들이다.
스킬이 안 걸린다. 대부분 description 문제다. 사용자가 실제로 쓸 법한 단어가 들어 있는지 보자. Claude에게 “지금 어떤 스킬을 쓸 수 있어?”라고 물어보면 인식되고 있는지 확인할 수 있다. 프론트매터 YAML이 깨져 있으면 메타데이터가 비어버려서 /스킬이름으로는 되는데 자동 호출만 안 되는 상태가 되기도 한다.
스킬이 너무 자주 걸린다. description을 더 좁히거나, 자동 호출을 아예 막는다. disable-model-invocation: true를 넣으면 나만 /이름으로 부를 수 있다. 배포·전송처럼 부작용이 있는 작업에는 이걸 넣는 걸 권한다. Claude가 “코드가 준비된 것 같으니 배포하자”고 판단하게 두면 곤란하다.
본문이 길면 계속 비싸진다. 스킬이 호출되면 그 내용은 하나의 메시지로 대화에 들어가고 세션이 끝날 때까지 남는다. Claude Code는 이후 턴에서 스킬 파일을 다시 읽지 않는다. 그래서 스킬 본문은 “지금 이 순간의 단계”가 아니라 작업 내내 유효한 상시 지시문처럼 써야 한다. 길어지면 별도 파일로 빼고 SKILL.md에서는 가리키기만 한다.
스킬이 많아지면 설명이 잘린다. 컨텍스트에 올라가는 스킬 목록에는 예산이 있고, 넘치면 설명이 잘려나간다. 그러면 매칭에 필요한 단어가 사라져서 갑자기 안 걸리기 시작한다. Claude Code에서 /doctor를 실행하면 이 목록이 얼마나 차지하는지 추정치를 볼 수 있다. (버전에 따라 다르므로 /doctor 출력 기준으로 확인하는 게 정확하다.)
호출됐다는 것과 잘 됐다는 건 다르다. 스킬이 걸리는 걸 눈으로 확인하면 만족하기 쉬운데, 그건 Claude가 스킬을 찾았다는 뜻이지 의도대로 동작했다는 뜻은 아니다. 제대로 보려면 현실적인 프롬프트 몇 개를 정해두고, 스킬을 켠 새 세션과 끈 새 세션에서 각각 돌려 비교해야 한다. 새 세션이어야 하는 이유는 스킬을 만들면서 쌓인 대화 맥락이 SKILL.md의 빈틈을 가려주기 때문이다. Anthropic이 공개한 skill-creator 플러그인이 이 비교 루프를 자동화해준다.
8. 남의 스킬을 설치할 때
한 줄로 정리하면 이렇다. 스킬 설치는 소프트웨어 설치와 같은 무게로 봐야 한다.
스킬은 Claude에게 지시를 주고 코드를 실행시킬 수 있다. 즉 스킬에 적힌 목적과 실제로 하는 일이 다를 수 있다. 공식 문서도 직접 만들었거나 Anthropic에서 받은 스킬만 쓰라고 명시한다.
출처가 불확실한 스킬을 굳이 써야 한다면 최소한 이건 보고 넣자.
SKILL.md본문뿐 아니라scripts/아래 파일까지 전부 읽는다.- 외부 URL을 가져오는 부분이 있는지 본다. 가져온 내용에 지시가 섞여 들어올 수 있고, 외부 의존성은 나중에 바뀔 수도 있다.
allowed-tools에 뭐가 열려 있는지 본다.- 프로젝트
.claude/skills/에 커밋된 스킬은 그 저장소를 신뢰한 시점부터allowed-tools가 발효된다. 남의 저장소를 처음 열 때 확인할 항목이다.
정리
- Skill은
SKILL.md가 든 폴더 하나다. 프레임워크가 아니다. - 세 단계로 나눠 로드되기 때문에, 많이 깔아도 부담이 적고 대신 본문은 짧아야 한다.
description은 설명문이 아니라 트리거다. 무엇을 · 언제를 둘 다 쓴다.- 개인 폴더에서 시작해서, 쓸 만하면 프로젝트로 옮겨 커밋한다.
- 부작용이 있는 작업은 자동 호출을 막는다.
- 호출되는 것과 잘 되는 것은 다르다. 새 세션에서 비교해야 안다.
같은 지시를 세 번 붙여넣었다면, 그 세 번째에 폴더를 하나 만드는 게 낫다.
관련 글
Skill의 지시 충돌과 예시 복사 문제를 실제 실험으로 좁혀간 기록이다.
Link - 예시가 지시보다 강할 때가 있다
Trigger·Non-trigger·Procedure를 나눠 Skill의 실제 동작과 오작동을 검증한 기록이다.
Link - Skill 검증을 위한 Eval, 직접 돌려보았다
참고 자료
- Agent Skills 개요 — 개념, 3단계 로딩, 제품별 지원 범위, 보안 주의사항
- Extend Claude with skills — Claude Code 기준 실사용 가이드, 프론트매터 전체 항목
- Skill authoring best practices —
description작성법과 반복 개선 방법 - anthropics/skills — 공식 스킬 저장소. 실제 스킬을 읽어보는 게 빠르다.
- agentskills.io — Agent Skills 공개 표준
확인 기준. 이 글의 구조·프론트매터 항목·토큰 수치·저장 위치·보안 권고는 2026년 7월 24일 기준 위 공식 문서에서 확인한 내용이다. 4절의 예제 스킬은 문서의 문법을 따라 이 글을 위해 작성한 것으로, 별도 검증 실험을 거친 것은 아니다. Claude Code는 버전에 따라 동작이 바뀌는 항목이 많으므로, 특정 동작이 중요하다면 claude --version으로 버전을 확인하고 해당 시점 문서를 다시 보는 편이 안전하다.