New · Step 2

2부 · 스킬 (Skills)

load-on-demand 지침 패키지 — SKILL.md 규격·패키징·프리뷰 함정.

게시일 2026-06-15

2. 스킬 (Skills) — load-on-demand 지침 패키지

▶ 포인트 — 스킬은 “X를 어떻게 하는지”를 markdown 한 장(+선택 리소스)에 적어 필요할 때만 로드하는 재사용 자산이다(1부 3장). 효과적으로 쓰는 핵심은 (1) 단순하게 시작, (2) 모델이 혼자 못 하는 것을 인코딩, (3) description을 트리거로 잘 쓰기.

2.1 개념 — 스킬이란

재사용 가능한 markdown 지침 묶음. 평소엔 컨텍스트에 없다가 그 작업이 필요할 때 온디맨드 로드(1부 3.1).
한 번 만들면 여러 에이전트가 재사용. GitHub Copilot·Claude 스킬도 import 가능(업계 호환, 1부 3.3).
효과: 지침이 항상 가볍고 깨끗하게 유지됨 = just-in-time 컨텍스트(1부 3.2).

2.2 SKILL.md 구조 — 필수 규격

스킬 zip은 루트에 SKILL.md가 있어야 하고, 그 안에 YAML 머리말로 name·description이 있어야 합니다.

---
name: excel-analysis
description: 판매 엑셀 데이터를 분석할 때 사용. 눈대중 대신 정확히
  계산하고, 결과를 표로 정리하는 규칙. "분석·집계·평균·순위·추세" 요청 시.
---

# 판매 데이터 분석 규칙

## 언제 쓰나
[트리거가 되는 상황]

## 규칙
[지켜야 할 핵심 원칙 — 무엇을, 쉬운 말로]

## 예시
[자주 쓰는 사용례]

부분	역할	작성 팁
`name`	스킬 식별자	짧은 영문 슬러그
`description`	언제 로드할지 트리거	“~할 때 사용 + 핵심 키워드”
본문	실제 지침	when-to-use → 규칙 → 예시

짚고 가기: description이 가장 중요하다. 오케스트레이터는 이 한 줄을 보고 “지금 이 스킬을 꺼낼까”를 판단한다. 사용 상황 + 트리거 키워드를 또렷이 넣어야 제때 로드된다.

❌ 모호: “데이터 도우미” → 언제 쓸지 모름 → 안 불려옴

✅ 또렷: “판매 엑셀을 분석할 때 사용. ‘분석·집계·평균·순위·추세’ 요청 시.” → 트리거가 분명

2.3 효과적으로 쓰는 법 — 3원칙

① 단순하게 시작하라(1부 1.4). 처음부터 거대한 스킬을 만들지 말고, SKILL.md 한 장으로 시작해 필요할 때 리소스를 붙입니다. 스킬은 보통 이 세 단계로 자랍니다.

단계	구성	언제
1단계	SKILL.md 한 장	규칙·형식만 적으면 충분할 때
2단계	SKILL.md + 보조 설명 문서	용어·맥락 설명이 필요할 때
3단계	SKILL.md + 템플릿·리소스	산출물 품질을 고정해야 할 때(Skills with resources, 1부 3.4)

대부분의 스킬은 1단계로 시작해도 됩니다. 품질이 필요한 곳에서만 리소스를 더하세요.

② “모델이 혼자 못 하는 것”을 인코딩하라. 스킬의 본질은 에이전트가 스스로는 못 푸는 지식을 적어두는 것입니다. 예를 들어, 큰 파일을 메일에 첨부하는 작업:

문제: 큰 HTML 파일을 메일에 직접 첨부 → 파일을 Base64로 변환하다 토큰 폭발 → 실패
해결(스킬에 인코딩): 파일 저장소(OneDrive 등)에 업로드 → 링크로 첨부

이건 에이전트가 시행착오 없이는 찾기 어려운 지식이라, 정확한 도구·순서까지 스킬에 적습니다. (지침에는 “링크로 첨부”라고만 추상화 — 1.4)

1부 1.4의 정의 그대로다: “하네스의 모든 구성요소는 ‘모델이 혼자 못 하는 것’에 대한 가정을 인코딩한다.” 스킬이 바로 그 인코딩 장소다.

③ 단일 출처를 지켜라. 디자인 색, 절차 같은 세부는 그 스킬 한 곳에만 두고 지침·다른 스킬과 중복하지 않습니다. 그래야 바꿀 때 한 곳만 고치면 되고, 에이전트가 항상 같은 규칙을 따릅니다(1.5 참조).

2.4 단일 파일 스킬 — Copilot Studio에 바로 등록

가장 쉬운 스킬은 리소스 없는 SKILL.md 한 장입니다. 이 형태는 Copilot Studio UI에서 스킬을 만들 때 그대로 붙여넣어 바로 등록할 수 있습니다 — zip으로 묶을 필요도, 업로드 절차도 없습니다.

예를 들어 “분석 결과를 늘 같은 형식으로 요약”하는 스킬:

---
name: result-brief
description: 분석 결과를 매번 똑같은 짧은 형식으로 요약할 때.
  "요약·브리핑·정리" 요청 시.
---
# 결과 브리핑
## 무엇을 하나 — 항상 이 고정 형식으로 정리
  한 줄 요약 / 핵심 숫자 / 눈에 띄는 점 / 다음 액션
## 규칙
  숫자는 분석 결과만, 5줄 안팎으로 짧게, 증감은 +/-로

→ YAML 2줄(name·description) + “언제·무엇을·규칙”만으로 스킬이 됩니다. “스킬 = 재사용 지침 한 장”이라는 1부 3장 메시지가 그대로 보입니다.

짚고 가기: 처음 스킬을 익힐 때는 이 단일 파일 형태로 시작하라. UI에 바로 등록되니 피드백이 빠르고, 스킬의 본질(재사용 지침)을 가장 또렷이 체감할 수 있다.

2.5 스킬 패키징 — 리소스를 더한 고성능 스킬

Copilot Studio UI에서 스킬을 만들 때는 단일 스킬(파일 하나)만 추가할 수 있습니다. 하지만 스킬 패키징(ZIP 업로드)을 쓰면, SKILL.md 지침과 함께 참고할 파이썬 코드·HTML 양식·디자인 지침 같은 리소스를 동봉할 수 있습니다. 즉 에이전트가 작업할 때 함께 참조하는 고성능 스킬이 됩니다(1부 3.4 “Skills with resources”).

구분	단일 파일 스킬	패키징(ZIP) 스킬
등록 방법	UI에 바로 붙여넣기	ZIP 업로드
구성	`SKILL.md` 하나	`SKILL.md` + 리소스(.py·.html·.md 등)
적합	규칙·형식만으로 충분	코드·템플릿·디자인까지 고정해야 할 때
예	출력 형식 요약 규칙	데이터 처리 코드 + 메일 HTML 양식 + 브랜드 디자인 지침

무엇을 동봉하나 (예):

파이썬 코드 — 데이터 처리·계산의 표준 패턴(에이전트가 참고할 레시피)
HTML 양식 — 메일·보고서 템플릿(빈칸만 채우면 디자인이 자동 적용)
디자인 지침 — 색·서식 규칙을 한 파일에 모아 단일 출처로

팁 — AI 도구로 정교하게: 스킬 패키징은 Copilot 같은 AI 도구의 도움을 받으면 훨씬 정교하게 설계할 수 있습니다. “이 작업을 스킬로 만들어 줘 / 이 HTML을 템플릿으로 분리해 줘 / description을 트리거가 잘 걸리게 다듬어 줘”처럼 맡기면, SKILL.md 구조·리소스 분리·트리거 키워드를 함께 정리해 줍니다. 메이커는 무엇을 원하는지만 말하면 됩니다(1부 0.2 “코어가 코드를 작성”).

⚠️ 중요 — 리소스는 자동 주입되지 않는다: 스킬이 트리거되면 에이전트에 자동으로 주입되는 건 SKILL.md 본문뿐이다. 동봉한 design-set.md·템플릿·.py는 저장만 될 뿐, 에이전트가 “필요하다”고 판단해 직접 열어야 읽힌다. 따라서 핵심 규칙을 “자세히는 design-set.md”라고만 가리키면, 에이전트는 그 파일을 안 열고 “가이드가 없다 → 내가 알아서 한다”로 간다.

원칙: 반드시 지켜야 할 최소 규칙(팔레트 값·금지·”템플릿을 쓰라”)은 SKILL.md 본문에 직접 적는다. 확장 설명·전체 레퍼런스만 리소스 파일로 분리한다.

이건 지침·스킬 사이의 “단일 출처”(1.5)와는 결이 다르다. 지침 vs 스킬는 중복을 피하라, SKILL.md vs 리소스는 핵심은 본문에·상세는 리소스에다.

2.6 스킬 패키징 — zip 함정 (반드시 주의)

ZIP으로 스킬을 올릴 때 가장 흔한 실패가 이것입니다.

File requirements
- .zip 안에 SKILL.md 가 있어야 함
- SKILL.md 에 name·description 이 YAML 로 있어야 함

잘못된 zip	올바른 zip
`my-skill/SKILL.md` (폴더째 압축)	`SKILL.md` (루트)
→ “Bundle is missing a root-level SKILL.md”	→ 통과

핵심: 폴더가 아니라 폴더 안 내용물을 압축한다.

탐색기: 폴더 안으로 들어가 → 파일 전체 선택 → 우클릭 압축. (폴더 자체를 우클릭 압축하면 실패)
PowerShell: Compress-Archive -Path "스킬폴더\*" -DestinationPath out.zip (\* = 내용물)

반론 대응(FAQ): “분명 SKILL.md를 넣었는데 왜 실패하나?” → 십중팔구 한 단계 안(폴더명/SKILL.md)에 들어가 있다. zip을 열어 SKILL.md가 맨 위(루트)에 보이는지 확인하라.

함정 — 스킬 이름(name) 규칙: name은 소문자·숫자·하이픈(-)만 허용되고, 하이픈으로 시작·끝날 수 없습니다. 이걸 어기면 “Name must use only lowercase letters, numbers, and hyphens…” 에러로 업로드가 거부됩니다.

❌ 잘못된 이름	이유	✅ 올바른 이름
`brand_comms`	언더스코어(`_`) 불가	`brand-comms`
`brand-comms_v2`	언더스코어 포함	`brand-comms-v2`
`Brand-Comms`	대문자 불가	`brand-comms`
`-brand` / `brand-`	하이픈으로 시작·끝	`brand`

2.7 ⚠️ 프리뷰 이슈 — 개인 개발환경에서는 New CLI 에이전트가 정상 동작하지 않음 (2026-06-14 기준)

New Copilot Studio는 현재 프리뷰 상태이며, 개인 개발환경(personal developer environment)에서는 New(CLI) 에이전트가 정상 작동하지 않습니다. 스킬 패키징 업로드가 깨지는 것은 그 증상 중 하나일 뿐, 개인 개발환경 전반의 문제입니다. 이 절은 그 증상·원인·해결을 실측 기준으로 정리합니다.

확인된 이슈 (개인 개발환경)

스킬 패키징 임포트 불가 — ZIP이 UI엔 정상으로 보이지만, 실제로는 SKILL.md의 YAML(이름·설명)만 올라가고 본문·리소스가 누락됨(아래 상세).
Copilot 앱에서 에러 발생 — 게시 후 M365 Copilot 앱에서 에이전트가 오류를 냄.
Teams 챗봇에서 랜덤 비정상 동작 — 같은 입력에도 동작이 들쭉날쭉.

스킬 패키징 누락 — 무엇이 실제로 올라가나 (BIC 처리) 정상이라면 스킬 호출 시 SKILL.md 본문 + 리소스가 컨텍스트로 주입돼야 합니다. 그러나 개인 개발환경에서는 YAML 메타데이터(이름·설명)만 남고, 본문은 내부 번들 포인터(BIC)로 대체된 채 주입되지 않습니다.

# 개인 개발환경에서 확인된 SKILL.md (본문이 사라지고 포인터만 남음)
---
name: default-...-skill-brand-comms-v2
description: Default_...skill.brand-comms-v2
---
<!-- bic:bundle=crskill_brand_comms_v2_zip_... -->   ← 본문·리소스가 여기로 대체됨

증상: 에이전트가 스킬을 선택은 하는데 디자인·절차를 안 따름(“상세 가이드가 없다”며 제멋대로 디자인). UI에는 4개 파일이 정상 업로드된 것처럼 보임.
확인(UI를 믿지 말 것): 테스트 프롬프트로 실제 주입을 검증.
```
"네가 가진 app/skills 의 하위 폴더까지 모두 보여줘"
```
- ✅ 정상: 스킬 폴더 아래 SKILL.md + 리소스가 모두 보임.
- ❌ 문제: SKILL.md만, 그나마 본문이 비고 bic:bundle 포인터만 보임.

원인 — 환경 종류 에이전트 게시 여부·스킬 패키지 언어와는 무관합니다. 같은 ZIP·같은 에이전트라도 환경이 다르면 결과가 갈립니다 — 개인 개발환경에서만 깨지고, Sandbox/일반 환경에서는 정상 동작합니다. 즉 스킬·에이전트 설계 문제가 아니라 개인 개발환경 자체의 프리뷰 제약입니다.

해결 — Sandbox 환경에서 개발

New(CLI) UI 에이전트는 개인 개발환경에서 개발하지 말고, Sandbox 환경에서 개발·테스트하는 것을 권장합니다.
Sandbox에서 에이전트를 만들고 ZIP을 임포트한 뒤, 위 “app/skills 보여줘” 프롬프트로 리소스까지 전부 주입됐는지 검증하고 작업을 시작하세요.

반론 대응(FAQ): “UI에 4개 파일이 다 보이는데 왜 안 되지?” → 프리뷰 기능에 대한 일부 제약사항, 버그일수 있습니다. 현재는 특히 개인 개발환경에서 많이 발생하고 있으며, 이는 스킬을 고쳐도 해결이 되지 않습니다. Sandbox 환경에서 새로 만드는 것이 정석이며, app/skills 프롬프트로 반드시 실측하세요.