Skill 폴더 구조 설계

Skill을 처음 만들 때 많은 사람이 SKILL.md 한 파일에 모든 것을 몰아넣는다. 시작할 때는 그게 가장 빠르다. 실제로 작은 업무라면 그것만으로도 충분하다. 하지만 반복해서 쓰기 시작하면 곧 문제가 생긴다. 정책 설명은 길어지고, 예시는 쌓이고, 계산 규칙은 복잡해지고, 에이전트는 매번 긴 문서를 들고 일해야 한다. 그 순간 Skill은 더 이상 "한 장의 지침서"가 아니라, 지침과 참고자료와 자동화 코드가 함께 들어 있는 작은 작업 패키지로 봐야 한다.¹²

이번 장의 핵심은 단순하다. SKILL.md는 Skill의 출입문이고, scripts/, references/, assets/는 그 안에서 실제 일을 굴러가게 만드는 방들이다. 폴더 구조를 잘 나누면 에이전트는 덜 읽고도 더 정확하게 움직인다. 반대로 구조가 흐리면, 읽어야 할 것과 실행해야 할 것과 복사해서 써야 할 것이 한데 뒤엉킨다.

최소 Skill 구조와 확장 Skill 구조는 무엇이 다른가

Agent Skills 표준에서 Skill은 최소한 SKILL.md 하나를 가진 디렉터리다. 여기에 필요에 따라 scripts/, references/, assets/ 같은 하위 디렉터리를 붙인다.¹ 이 구조는 단순해 보이지만 꽤 중요한 철학을 담고 있다. 핵심 지침은 항상 입구에 두고, 무거운 정보는 뒤로 뺀다는 철학이다.

가장 작은 형태의 Skill은 이런 모양이다.

meeting-notes/
└── SKILL.md

이 구조는 업무가 비교적 단순할 때 잘 맞는다. 예를 들어 회의 메모를 정리해 액션 아이템 중심으로 재구성하는 정도라면, 입력과 절차와 출력 형식을 SKILL.md 안에 충분히 담을 수 있다. 별도의 계산 코드도 없고, 길게 참조할 정책 문서도 없고, 템플릿도 짧다면 이 구조가 가장 관리하기 쉽다.

하지만 업무가 조금만 복잡해져도 확장 구조가 필요해진다.

executive-report/
├── SKILL.md
├── scripts/
│   ├── validate_numbers.py
│   └── normalize_tables.py
├── references/
│   ├── report-policy.md
│   ├── kpi-definitions.md
│   └── approval-rules.md
└── assets/
    ├── one-page-template.md
    └── company-style-sample.md

이 구조가 필요한 이유는 분명하다. 에이전트가 항상 모든 내용을 다 읽을 필요는 없기 때문이다. 대부분의 구현은 먼저 Skill의 이름과 설명 같은 가벼운 메타데이터를 보고, 실제로 Skill이 선택된 뒤에야 SKILL.md 본문을 읽고, 더 자세한 자료는 필요할 때만 추가로 불러온다. 이른바 progressive disclosure, 즉 단계적 로딩 구조다.¹² 폴더를 나누는 일은 단순한 정리가 아니라, 에이전트의 집중력을 지키는 설계다.

쉽게 말하면 이렇다. SKILL.md는 "무슨 일을 어떤 순서로 할지"를 설명하고, 나머지 폴더는 "필요할 때 꺼내 쓰는 공구함"이다.

SKILL.md에는 길이를 더하지 말고 방향을 남겨라

6장에서 SKILL.md를 어떻게 쓰는지 다뤘다면, 여기서는 그 문서를 어디까지 두어야 하는지를 생각해야 한다. 좋은 폴더 구조는 SKILL.md를 비워 두는 구조가 아니라, SKILL.md를 가볍고 결정적으로 유지하는 구조다.

실전에서는 이런 기준이 유용하다. 에이전트가 거의 모든 실행에서 반드시 알아야 하는 내용은 SKILL.md에 둔다. 반대로 일부 상황에서만 필요하거나, 길고 상세하거나, 표와 규칙이 많은 자료는 다른 폴더로 뺀다.¹³

예를 들어 출판 기획 Skill을 만든다고 해 보자. "입력된 주제를 바탕으로 독자 페르소나를 정리하고, 시장 포지셔닝을 잡고, 제목 후보와 목차와 기획서 초안을 만든다" 같은 핵심 절차는 SKILL.md에 있어야 한다. 하지만 출판사 내부의 문체 기준표, 경쟁 도서 비교 프레임, 제안서 양식 예시는 별도 파일에 두는 편이 낫다. 매번 처음부터 다 읽을 필요는 없기 때문이다.

폴더 구조를 잘 설계한 Skill은 본문이 길어서 똑똑해 보이지 않는다. 오히려 본문은 길을 안내하고, 세부 파일은 필요할 때만 열리는 쪽이 더 강하다.

scripts 디렉터리는 "생각보다 계산이 더 안전한 일"을 맡긴다

scripts/는 자연어 지침만으로 처리하면 흔들리기 쉬운 작업을 맡기는 곳이다. 표준 문서들도 반복 계산, 변환, 검증, 포맷 정리처럼 결정론적으로 처리할 수 있는 작업은 스크립트로 분리하는 방식을 권장한다.¹²

여기서 중요한 판단 기준은 "코드가 더 멋진가"가 아니라 "코드가 더 안전한가"다.

예를 들어 이런 일은 scripts/에 넣는 편이 좋다.

• 숫자 합계 검증, 비율 계산, 단위 변환

• CSV나 Excel의 컬럼 정규화

• 파일 포맷 변환, 로그 추출, 텍스트 파싱

• 출력 형식 검사, 필수 항목 누락 검사

• 반복적으로 같은 명령을 실행하는 보조 작업

반대로 이런 일은 굳이 스크립트가 없어도 된다. 문단 구조를 정하는 일, 제목 톤을 맞추는 일, 독자 수준에 따라 설명 깊이를 조정하는 일처럼 해석과 판단이 필요한 작업은 자연어 지침이 더 잘 맞는다.

예를 들어 데이터 분석 Skill에서 scripts/validate_csv.py가 있다면, 이 스크립트는 파일을 열어 필수 컬럼 존재 여부, 날짜 형식 이상 여부, 결측치 비율을 확인하고 결과를 짧은 메시지로 반환할 수 있다. 그러면 에이전트는 "파일을 읽고 대충 괜찮은 것 같아 보인다"가 아니라, "누락된 컬럼은 revenue, 날짜 형식 오류는 14건, 분석 전 정리가 필요하다"처럼 더 단단한 출발점을 갖게 된다.

좋은 스크립트는 똑똑한 코드를 자랑하지 않는다. 에이전트가 바로 행동으로 옮길 수 있는 출력만 남긴다.¹³ 그래서 scripts/를 설계할 때는 세 가지를 꼭 정해 두는 편이 좋다.

첫째, 입력 형식을 명확히 한다. 파일 경로를 받는지, 인자를 받는지, 표준 입력을 읽는지 애매하면 에이전트가 실행 단계에서 흔들린다.

둘째, 출력 형식을 짧고 일관되게 한다. 성공, 실패, 경고를 구분할 수 있어야 하고, 실패 시에는 무엇을 고쳐야 하는지가 드러나야 한다.

셋째, 에러 메시지를 사람이 아니라 에이전트가 읽는다고 생각하고 쓴다. "Unknown error"보다 "Missing column: customer_id"가 백 배 낫다.

즉, scripts/는 Skill의 두뇌를 대체하는 곳이 아니라, 손이 자주 틀리는 일을 손 대신 해 주는 곳이다.

references 디렉터리는 길고 중요한 문서를 숨기는 곳이 아니라, 제때 읽게 만드는 곳이다

references/는 많은 팀이 가장 과소평가하는 폴더다. 대개 정책 문서, 기준표, 업무 규정, 도메인 설명, 긴 예외 처리 규칙은 여기에 둔다.¹² 이 폴더의 목적은 단순 보관이 아니다. SKILL.md를 짧게 유지하면서도, 깊이는 잃지 않게 만드는 것이다.

예를 들어 고객 응대 Skill을 생각해 보자. 핵심 응답 절차는 SKILL.md에 있을 수 있다. 하지만 환불 정책, 법무 검토 필요 조건, VIP 고객 응대 규칙, 금지 표현 목록까지 전부 본문에 넣으면 문서는 금세 무거워진다. 이럴 때는 이렇게 나누는 편이 낫다.

customer-support/
├── SKILL.md
└── references/
    ├── refund-policy.md
    ├── escalation-rules.md
    ├── forbidden-phrases.md
    └── tone-guide.md

이 구조의 장점은 분명하다. 일반 문의에는 refund-policy.md만 읽으면 되고, 법적 표현이 섞인 민감 문의에는 escalation-rules.md까지 읽으면 된다. 모든 상황에 모든 정책을 들고 다니지 않아도 된다.

references/를 설계할 때는 파일을 주제별로 잘게 나누는 편이 대체로 유리하다.¹³ "회사 정책 전체"처럼 커다란 한 파일을 두면, 필요한 정보가 있어도 찾기 어렵고, 불필요한 내용까지 함께 로드될 가능성이 높다. 반대로 "배송 정책", "환불 정책", "승인 규칙", "브랜드 문체"처럼 파일을 역할별로 나누면 에이전트가 필요한 문서만 읽기 쉽다.

또 하나 중요한 점이 있다. 긴 문서는 references/에 넣기만 하면 끝이 아니다. SKILL.md 안에서 언제 어떤 파일을 읽어야 하는지 분명히 적어야 한다.¹⁴ 예를 들어 "환불, 해지, 법무 표현이 보이면 references/escalation-rules.md를 먼저 읽고 답변 작성 전에 승인 필요 여부를 판단하라"처럼 연결 규칙을 써 두어야 한다. 폴더는 지도이고, SKILL.md는 길 안내판이다.

assets 디렉터리는 읽는 자료가 아니라 쓰는 재료를 담는다

assets/는 문서상으로는 정적 리소스 폴더지만, 실무적으로는 "결과물을 빨리 맞추게 해 주는 재료 창고"에 가깝다.¹³ 여기에는 템플릿, 샘플 출력물, 브랜드 로고, 아이콘, 폰트, 보일러플레이트 코드, 표 양식, 슬라이드 뼈대 같은 것이 들어간다.

이 폴더를 references/와 헷갈리면 구조가 금세 흐려진다. 구분 기준은 간단하다. 읽어서 판단에 쓰는 문서는 references/로 가고, 복사하거나 변형해 최종 결과물에 반영할 재료는 assets/로 간다.

예를 들어 사내 보고서 Skill이라면 references/brand-tone.md는 문체 기준 문서이고, assets/executive-report-template.md는 실제 보고서 초안의 뼈대다. 둘 다 결과물에 영향을 주지만 역할이 다르다. 하나는 판단 기준이고, 다른 하나는 출력 재료다.

assets/에 무엇을 둘지 고민될 때는 이런 질문을 해 보면 된다. "이 파일은 읽고 이해해야 하는가, 아니면 꺼내서 변형해 쓰면 되는가?" 후자라면 대체로 assets/다.

이 폴더가 특히 빛나는 곳은 형식 일관성이 중요한 업무다. 이메일 작성 Skill, 제안서 Skill, 프론트엔드 컴포넌트 생성 Skill, 브랜디드 콘텐츠 Skill 같은 경우다. 매번 같은 표지 구조, 같은 섹션 순서, 같은 디자인 토큰, 같은 회사 서명 블록을 재현해야 한다면, 그 재료를 assets/에 넣어 두는 것이 훨씬 안정적이다.

재미있는 비유를 하나 들면, references/는 요리책이고 assets/는 밀가루와 틀이다. 둘 다 중요하지만, 같은 서랍에 넣어 두면 요리는 늘 어수선해진다.

파일 간 연결은 한 단계 안에서 끝내라

폴더를 나누기 시작하면 또 다른 유혹이 생긴다. 파일 안에서 다른 파일을 거듭 참조하는 구조를 만드는 것이다. 예를 들어 SKILL.md가 references/overview.md를 읽게 하고, 그 문서가 다시 references/detail/finance.md를 읽게 하고, 거기서 또 다른 문서를 타고 들어가게 만드는 식이다. 이런 구조는 사람에게도 불편하고, 에이전트에게는 더 불편하다.

여러 가이드가 공통으로 권하는 방식은 단순하다. SKILL.md에서 필요한 파일로 직접 연결하고, 참조 깊이를 얕게 유지하라는 것이다.¹³ 즉, 핵심 내비게이션은 SKILL.md 하나에서 끝나야 한다.

좋은 구조는 이런 모습이다.

- 리포트 KPI 정의는 [references/kpi-definitions.md](references/kpi-definitions.md)를 본다.
- 승인 조건은 [references/approval-rules.md](references/approval-rules.md)를 본다.
- 출력 초안은 [assets/one-page-template.md](assets/one-page-template.md)를 사용한다.
- 숫자 검증은 `scripts/validate_numbers.py`를 실행한다.

이렇게 해 두면 에이전트는 길을 잃지 않는다. 반면 "자세한 내용은 overview를 보고, 거기서 관련 문서를 추가로 찾으라"는 방식은 사람에게도 귀찮고, 에이전트에게도 불안정하다.

하나의 큰 Skill로 묶을지, 여러 개의 작은 Skill로 나눌지 어떻게 판단할까

이제 가장 실전적인 질문이 남는다. 업무가 커질수록 누구나 한 번쯤 고민한다. 이걸 하나의 큰 Skill로 묶을까, 아니면 여러 개의 작은 Skill로 찢을까.

정답은 "항상 작게"도 아니고 "가능하면 통합"도 아니다. 판단 기준은 작업의 결합도다. 늘 함께 움직이는 절차와 자료라면 하나의 Skill로 묶고, 트리거와 입력과 출력이 다르면 분리하는 편이 낫다.

다음 표처럼 생각하면 판단이 쉬워진다.

예를 들어 "기술 블로그 작성"과 "릴리스 노트 요약"은 얼핏 비슷해 보이지만 실제로는 나누는 편이 더 나을 수 있다. 둘 다 문서를 읽고 글을 쓰지만, 입력 소스도 다르고, 독자도 다르고, 출력 구조도 다르기 때문이다.

반대로 "사내 보고서 작성" 안에서 숫자 검증, KPI 정의 참조, 회사 문체 적용, 1페이지 템플릿 사용은 대체로 같은 결과물을 위해 함께 움직인다. 이런 경우는 하나의 Skill 안에 scripts/, references/, assets/를 묶어 두는 편이 더 자연스럽다.

실무에서 특히 조심해야 할 것은 "너무 큰 만능 Skill"이다. 이름은 멋지지만 실제로는 문서 작성, 리서치, 데이터 분석, 슬라이드 생성, 이메일 발송까지 다 하겠다고 나서는 Skill 말이다. 이런 Skill은 대체로 description이 넓어지고, 본문이 길어지고, 참조 파일이 늘어나고, 정작 어떤 상황에서 무엇을 먼저 해야 하는지 흐려진다. 반대로 지나치게 잘게 쪼개면 작은 Skill이 너무 많아져 관리가 어려워지고, 하나의 작업을 끝내려면 여러 Skill을 오가야 한다.

좋은 기준은 이것이다. 사용자가 한 문장으로 요청했을 때, 에이전트가 비교적 분명하게 "아, 이 Skill이다"라고 고를 수 있으면 독립 Skill로 만들 만하다. 반대로 어떤 Skill을 열고 나면 거의 항상 같은 하위 절차를 함께 수행한다면, 그것은 같은 Skill 폴더 안의 리소스로 묶는 편이 낫다.

폴더 구조는 곧 운영 구조다

Skill 폴더를 잘 설계하면 작성만 편해지는 것이 아니다. 운영도 쉬워진다. 어떤 정책이 바뀌었을 때는 references/만 교체하면 되고, 계산 규칙이 바뀌었을 때는 scripts/만 수정하면 되고, 회사 템플릿이 바뀌었을 때는 assets/만 업데이트하면 된다. 즉, 폴더 구조는 유지보수의 단위이기도 하다.

이 점이 중요한 이유는 Skill이 한 번 만들고 끝나는 문서가 아니기 때문이다. 실제 업무는 계속 변한다. 승인 규칙이 바뀌고, 문체가 바뀌고, 데이터 포맷이 바뀌고, 사용하는 도구도 바뀐다. 이 변화가 모두 SKILL.md 한 파일에 뭉쳐 있으면 작은 수정도 매번 전체 수술이 된다. 하지만 구조가 나뉘어 있으면, 바뀐 부품만 갈아끼울 수 있다.

결국 Skill 폴더 구조 설계는 정리 습관의 문제가 아니다. 에이전트가 무엇을 언제 읽고, 무엇을 실행하고, 무엇을 결과물에 반영할지를 구분하는 실행 설계다. SKILL.md는 방향을 주고, scripts/는 반복 계산을 맡고, references/는 깊이를 보완하고, assets/는 결과물의 형식을 붙잡는다. 이 네 가지가 분리되어 있을 때 Skill은 비로소 "한 문서"가 아니라 "재사용 가능한 작업 패키지"가 된다.¹²³

다음 장에서는 이 패키지 안에서 특히 중요한 축, 곧 스크립트를 어떻게 설계해야 하는지를 더 깊이 들어가 보겠다. 어떤 작업을 자연어 지침으로 남기고, 어떤 작업을 코드로 내리는지의 경계가 여기서부터 본격적으로 선명해진다.

참고

¹Specification - Agent Skills

²Agent Skills | Microsoft Learn

³skills/skills/.system/skill-creator/SKILL.md at main · openai/skills · GitHub

⁴Use Agent Skills in VS Code