에이전트 생성 — 빌드 개념편

6요소 한눈에 보기

지침은 왜 짧아야 할까?

• 지침은 에이전트가 모든 대화에서 항상 참조하는 최상위 규칙입니다. 회사로 치면 헌법·취업규칙입니다.
• 스킬(필요할 때만 로드)과 달리 지침은 늘 켜져 있으므로, 길어질수록 모든 응답이 무거워지고 핵심이 묽어집니다.
• 그래서 지침에는 항상 지켜야 할 소수의 원칙만 담고, 상황별 디테일은 스킬로 내립니다.

좋은 지침 구조 (템플릿)

구조는 역할 → 작업별 규칙 → 가드레일 순서입니다. 짧은 섹션으로 끊어 한눈에 훑을 수 있게 만듭니다.

# [에이전트 이름] — 지침
[한 문단: 역할과 무엇을 도와주는지]

## [작업 A]를 할 때
- 규칙 (무엇을, 쉬운 말로)
- 세부는 스킬을 가리키기

## [작업 B]를 할 때 (되돌릴 수 없는 작업이면 "중요" 표시)
- 확인 게이트, 금지선

## 지킬 점 (가드레일)
- 항상/절대 규칙 3~5개

지침 작성 6원칙

❌ / ✅ 이렇게 바꿔 보세요

지침에 넣을 것 vs 스킬로 내릴 것

실제 사례 — 단일 출처를 어겨 디자인이 깨진 메일

SKILL.md 구조 — 필수 규격

스킬 파일 맨 위에는 YAML 머리말로 name과 description이 있어야 합니다.

---
name: excel-analysis
description: 판매 엑셀 데이터를 분석할 때 사용. 눈대중 대신
  정확히 계산하고, 결과를 표로 정리하는 규칙.
  "분석·집계·평균·순위·추세" 요청 시.
---
# 판매 데이터 분석 규칙
## 언제 쓰나      [트리거가 되는 상황]
## 규칙          [핵심 원칙 — 무엇을, 쉬운 말로]
## 예시          [자주 쓰는 사용례]

description이 가장 중요합니다

오케스트레이터는 description 한 줄만 보고 “지금 이 스킬을 꺼낼까?”를 판단합니다. 사용 상황과 트리거 키워드를 또렷하게 넣어야 제때 불려옵니다.

효과적으로 쓰는 3원칙

단계별로 키우기

가장 쉬운 시작 — 단일 파일 스킬

가장 쉬운 스킬은 리소스 없는 SKILL.md 한 장입니다. UI에 그대로 붙여 넣어 바로 등록할 수 있어 zip도, 업로드 절차도 필요 없습니다. 처음 익힐 때는 이 형태로 시작하세요 — 피드백이 가장 빠릅니다.

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

패키징 함정 — zip 구조와 이름 규칙

핵심: 폴더가 아니라 폴더 ‘안의 내용물’을 압축합니다. 그리고 스킬 이름은 소문자·숫자·하이픈(-)만 쓸 수 있고, 하이픈으로 시작하거나 끝날 수 없습니다.

올바르게 압축하는 방법

탐색기: 스킬 폴더 안으로 들어가 파일 전체를 선택 → 우클릭 → 압축.

PowerShell: 폴더 경로 끝에 \* 를 붙여 내용물만 압축합니다.

Compress-Archive -Path "스킬폴더\*" -DestinationPath out.zip

도구 선택 기준

최소 큐레이션 3원칙

• 목적당 최소 도구만 — 도구가 10개면 매 턴 “뭘 쓸지” 헷갈립니다.
• 기능 중복 금지 — 메일 커넥터와 메일 MCP를 둘 다 붙이면 모호해집니다.
• 코드로 되는 건 도구로 붙이지 않는다 — HTML·문서 생성은 기본 제공 라이브러리로 충분합니다.

두 종류의 참고자료 — 섞지 마세요

RAG에서 코드 실행으로 — 왜 더 정확할까?

연결된 에이전트 — 언제 나눌까?

메인(오케스트레이터)
├── 분석 전문   ← 깊이 파고들어 "핵심 요약"만 반환
└── 작성 전문   ← 형식·템플릿을 다뤄 "완성 산출물"만 반환

메모리 — 단기·장기 2계층

메이커가 실제로 할 일

• 대부분은 신경 쓸 게 없습니다 — 세션 안의 맥락 유지는 코어가 자동으로 처리합니다.
• 세션을 넘어 기억이 필요하면 그 데이터를 M365(프로필·SharePoint 등)에 두도록 설계합니다.
• 산출물을 영구 보관하려면 OneDrive/SharePoint에 저장합니다.

한 요청이 6요소를 관통하는 흐름

요청 예: “이 데이터를 분석해서 결과를 보고서로 만들고, 담당자에게 메일로 보내 줘.”

권장 빌드 순서

✅ 빌드 체크리스트

• 지침이 짧고 “무엇을”에 집중하는가? (구현 디테일 없음)
• 세부(색·절차)를 지침이 아니라 스킬에 뒀는가? (단일 출처)
• 되돌릴 수 없는 행동(발송)에 확인 게이트가 있는가?
• 각 스킬에 name·description(YAML)이 있는가?
• description에 트리거 키워드가 또렷한가?
• zip 루트에 SKILL.md가 있는가? (폴더 안 내용물을 압축)
• 스킬 name이 소문자·숫자·하이픈만 쓰는가?
• 핵심 디자인·규칙이 SKILL.md 본문에 직접 있는가?
• 도구가 최소인가? (겹치는 도구 없음, 코드로 되는 건 안 붙임)
• 숫자는 엑셀, 말투·형식은 Word로 분리했는가?

⚠️ 흔한 함정과 해결