에이전트 스킬 – 반복 작업을 절차로 묶는 방법
에이전트 스킬은 AI 에이전트가 특정 작업을 할 때 찾아서 불러오는 폴더입니다. SKILL.md라는 파일에 지침을 적고, 그 작업에 쓰는 참고 문서와 스크립트를 같은 폴더에 함께 넣어 둡니다.
이 글의 앞쪽은 에이전트 스킬이 어떻게 생겼고 언제 읽히는지를 공식 문서를 근거로 정리한 내용이고, 뒤쪽은 앱인토스 미니앱을 만들 때 제가 쓰는 스킬 파일을 실제 내용 그대로 보여 드리는 부분입니다.
에이전트 스킬이란 무엇인가
Anthropic이 2025년 10월 16일에 낸 엔지니어링 글은 스킬을 이렇게 설명합니다. 지침과 스크립트, 자료를 정리해 담은 폴더이고, 에이전트가 이것을 찾아내서 필요할 때 불러와 특정 작업을 더 잘하게 된다는 거예요. 가장 단순한 스킬은 SKILL.md 파일 하나가 든 폴더입니다.
언제 만드는지는 Claude Code 공식 문서에 적혀 있습니다. 같은 지시나 체크리스트, 여러 단계짜리 절차를 채팅에 계속 붙여 넣고 있을 때, 그리고 규칙 파일(CLAUDE.md)의 한 부분이 사실이 아닌 절차로 자라났을 때입니다. 스킬을 만들어 두면 Claude가 관련 있는 작업에서 스스로 쓰고, 사용자가 /스킬이름으로 직접 부를 수도 있어요.
이름과 설명만 먼저 읽는다
에이전트 스킬은 한꺼번에 읽히지 않습니다. 엔지니어링 글은 이 방식을 단계적 공개라고 부르고, 스킬을 유연하고 확장 가능하게 만드는 핵심 설계 원칙으로 꼽습니다.
| 단계 | 읽는 것 | 읽는 때 |
|---|---|---|
| 1단계 | 설치된 스킬의 이름과 설명 | 에이전트가 시작할 때 |
| 2단계 | SKILL.md 본문 |
지금 작업과 관련 있다고 판단할 때, 또는 직접 부를 때 |
| 3단계 | 폴더에 딸린 파일 | 본문이 가리키는 것을 필요할 때 |
1단계의 이름과 설명은 “이 스킬을 언제 써야 하는지”를 알 만큼만 담습니다. 엔지니어링 글은 파일 시스템과 코드 실행 도구가 있는 에이전트라면 스킬 전체를 컨텍스트에 올릴 필요가 없어서, 스킬 하나에 묶어 둘 수 있는 분량에 사실상 한계가 없다고 설명해요.
Claude Code 문서에는 이 구조와 관련된 숫자가 몇 개 나옵니다.
규칙 파일, 서브에이전트, MCP와의 관계
아래 표는 두 공식 자료에 적힌 범위만 옮긴 것입니다.
| 비교 대상 | 공식 자료에 적힌 것 |
|---|---|
| 규칙 파일(CLAUDE.md) | CLAUDE.md 내용과 달리 스킬 본문은 쓰일 때만 불려 온다 |
| 서브에이전트 | 스킬에 context: fork를 적으면 새 서브에이전트가 스킬 내용을 지시문으로 받아 실행한다. 이 서브에이전트는 대화 기록을 보지 못한다 |
| MCP | 외부 도구와 소프트웨어가 얽힌 복잡한 작업 흐름을 스킬이 가르쳐 MCP 서버를 보완하는 방향을 살펴보겠다고 엔지니어링 글이 밝혔다 |
SKILL.md 파일의 구조
SKILL.md는 두 부분으로 되어 있습니다. 맨 위 --- 사이에 적는 frontmatter와, 그 아래에 마크다운으로 쓰는 지침입니다.
frontmatter에서 먼저 볼 항목은 name과 description입니다. 엔지니어링 글은 이 둘을 필수 메타데이터로 소개하고, Claude Code 문서는 모든 항목이 선택이며 description을 권장한다고 적습니다. Claude Code에서는 name을 빼면 폴더 이름이 명령 이름이 됩니다. description은 Claude가 이 스킬을 쓸지 정할 때 보는 글이라, 문서는 핵심 사용 사례를 앞쪽에 쓰라고 안내해요.
누가 부를 수 있는지도 frontmatter로 정합니다. 기본값은 사용자와 Claude 양쪽 모두 부를 수 있는 상태입니다.
disable-model-invocation: true
- Claude가 스스로 부르지 못한다
- 배포처럼 시점을 직접 정하고 싶은 작업에 쓴다
user-invocable: false
/메뉴에 나오지 않고 Claude만 부른다- 명령으로 실행할 일이 아닌 배경 지식에 쓴다
본문은 짧게, 중요한 지시는 위쪽에
Claude Code 문서는 본문을 간결하게 쓰라고 합니다. 스킬이 한 번 불려 오면 그 내용이 이후 대화에도 계속 남아 있어서, 한 줄 한 줄이 반복되는 토큰 비용이 되기 때문입니다. 대화가 압축될 때는 스킬마다 앞쪽 5,000토큰까지만 다시 붙고, 그마저도 전체 예산 안에서 최근에 쓴 스킬부터 채워집니다. 그래서 가장 중요한 지시는 위쪽에 두라는 안내도 있습니다.
공식 자료에 나온 스킬 사례
엔지니어링 글이 예로 든 것은 PDF 스킬입니다. Claude는 PDF를 이해하는 데는 익숙하지만 양식을 채우는 것처럼 PDF를 직접 조작하는 능력은 제한적이어서, 이 스킬이 그 부분을 맡는다고 해요.
PDF 스킬의 SKILL.md는 reference.md와 forms.md 두 파일을 가리킵니다. 양식을 채우는 지침은 forms.md로 옮겨 두었고, Claude는 양식을 채울 때만 그 파일을 읽습니다. 폴더에는 PDF에서 양식 필드를 뽑아내는 파이썬 스크립트도 들어 있는데, Claude는 이 스크립트와 PDF를 컨텍스트에 올리지 않고 실행할 수 있습니다.
미니앱 제작에 쓰는 에이전트 스킬
여기부터는 제 프로젝트 이야기입니다. 앱인토스 미니앱을 만드는 저장소에 있는 스킬 가운데 직접 만든 에이전트 스킬 세 개가 역할별로 나뉘어 있습니다.
어떤 일에 어떤 스킬을 쓰는지는 규칙 파일의 첫 번째 항목에 적어 두었습니다. 기획은 기획 스킬, 제작과 출시는 제작 스킬을 쓰고, 역할이 없는 유지보수에만 공용 스킬을 쓴다는 내용이에요.
공용 스킬의 앞부분입니다.
---
name: apps-in-toss-factory
description: Create, upgrade, monetize, validate, and build Apps in Toss WebView projects in this repository. Use for project numbers, app concepts, console metadata, ad IDs, SDK upgrades, MCP console work, icons, preflight, and .ait builds.
---
# Apps in Toss factory
Use the deterministic harness instead of reading the repository's legacy Markdown guides.
If the user assigns a role, use the narrower `apps-in-toss-planner` or `apps-in-toss-builder`
skill instead. This shared skill is for role-neutral maintenance and harness work.
## Start
1. Run `node scripts/ait-harness.mjs context <N>`. It also works before a new project directory
exists, provided an approved plan has already been assigned to N.
2. Read only the files listed in `readNext`, and only the ones the task needs. The `context`
output already returns the spec's displayName, subtitle, category, categoryRationale,
keywords, ads, notifications, storage, and corsOrigins — do not re-read `app.spec.json`
just to look those up. Open it when you are about to edit it, or when you need a field
`context` does not emit.
3. Update `app.spec.json` first when product identity, console copy, ads, or imagery changes.
4. Run `node scripts/ait-harness.mjs sync <N>` after spec changes.description에는 무엇을 하는 스킬인지와 어떤 요청에 쓰는지가 한 줄에 같이 들어 있습니다. 본문 앞부분에 역할이 정해졌으면 더 좁은 스킬을 쓰라는 안내가 있고, “Start” 절에 작업을 시작하는 순서가 번호로 적혀 있어요. 첫 단계인 context 명령은 AI 하네스 글에서 설명한 그 명령입니다.
Claude Code가 읽는 스킬 폴더에 있는 SKILL.md는 하네스 폴더에 둔 원본 파일로 가는 링크라서, 두 곳의 내용이 같습니다.
기획과 제작을 스킬 두 개로 나눴다
역할 스킬 두 개는 description부터 다릅니다. 기획 스킬의 머리 부분이에요.
---
name: apps-in-toss-planner
description: Use when 기획자 또는 Planner 역할로 Apps in Toss 신규 서비스 조사, 제품 기획, pending 계획서, 승인 요청을 맡았을 때.
---
# Apps in Toss Planner
목표는 Builder가 제품 판단 없이 구현할 수 있는 승인 계획 하나다.제작 스킬은 이렇게 시작합니다.
---
name: apps-in-toss-builder
description: Use when 제작자 또는 Builder 역할로 승인된 Apps in Toss 계획을 projectN에 구현, 콘솔 등록, 빌드 또는 테스트 푸시할 때.
---
# Apps in Toss Builder
승인된 계획을 구현하며 새 제품 범위나 프로젝트 번호를 정하지 않는다.두 파일 모두 첫 줄에서 그 역할의 범위를 정하고, 그 아래에 번호 붙인 절차가 이어집니다.
기획 스킬
- 조사하고 계획서를 써서 승인을 요청한다
- 코드, 앱 설정 파일, 앱 폴더, 콘솔은 건드리지 않는다
제작 스킬
context명령으로 시작해 승인된 계획을 구현한다- 실제 출시는 사용자가 한다
두 파일 다 맨 끝에 자세한 참고 문서는 필요한 경우에만 읽는다는 줄이 있습니다.
이 블로그도 스킬로 쓴다
이 블로그의 글을 쓰는 절차도 에이전트 스킬 하나로 묶여 있습니다. SKILL.md에는 무엇을 쓸지 정하기, 글감 모으기, 뼈대를 만들고 쓰기, 기계 검사, 사실 검증, 임시글로 올리기, 사용자에게 알리기가 번호 순서대로 적혀 있어요.
같은 폴더에는 문체와 글 구조를 적은 파일이 하나 더 있고, SKILL.md는 쓰기 전에 그 파일을 읽으라고 가리킵니다. 앞에서 본 3단계 구조의 세 번째 단계에 해당하는 파일입니다.
참고한 공식 문서
- Extend Claude with skills (Claude Code 공식 문서)
- Equipping agents for the real world with Agent Skills (Anthropic 엔지니어링 글)
수치와 항목 이름은 바뀔 수 있으니 원문을 확인해 주세요.
스킬이 가리키는 스크립트가 무슨 일을 하는지는 AI 하네스 글에 정리해 두었습니다.
에이전트 스킬 자주 묻는 질문
에이전트 스킬이 뭔가요?
에이전트가 특정 작업을 할 때 찾아서 불러오는 폴더입니다. SKILL.md 파일에 지침을 적고, 필요하면 참고 문서와 스크립트를 같은 폴더에 함께 둡니다.
스킬은 언제 읽히나요?
이름과 설명은 시작할 때 먼저 읽힙니다. SKILL.md 본문은 지금 작업과 관련 있다고 판단될 때나 사용자가 직접 부를 때 읽히고, 딸린 파일은 본문이 가리키는 것을 필요할 때 읽습니다.
규칙 파일(CLAUDE.md)과는 무엇이 다른가요?
Claude Code 공식 문서에 따르면 CLAUDE.md 내용과 달리 스킬 본문은 쓰일 때만 불려 옵니다. 문서는 CLAUDE.md의 한 부분이 절차로 자라났을 때 스킬로 만들라고 안내합니다.
글에 나온 규칙 파일과 에이전트는 Claude Code에서 쓰는 방식이고, 공식 안내는 Claude Code 공식 문서에 있습니다.
이 글은 직접 만들고 운영하며 남긴 기록입니다. 적힌 수치는 작성 시점의 제 계정 기준이며, 같은 결과나 수익을 보장하지 않습니다.
8 Comments