Agent 엔지니어링
실제 Skill 해부하기
Alice 릴리스 어시스턴트를 예시로: 각 섹션을 클릭하여 세부 내용을 펼치고, Agent가 Skill을 어떻게 읽고 실행하는지 확인하세요.
SKILL.md 섹션별 분석
SKILL.md
alice-release
Alice 프로젝트 릴리스 어시스턴트
1
메타데이터
Skill 이름, 기능 설명, 트리거 구문
▶
📌 설계 결정: 트리거 구문의 커버리지가 Skill의 재현율을 결정합니다. 너무 적으면 → 트리거되어야 할 때 발동되지 않고; 너무 광범위하면 → 트리거되지 말아야 할 때 잘못 발동됩니다. 좋은 트리거 구문 = 사용자가 자연스럽게 표현할 수 있는 모든 방식을 열거하는 것입니다.
2
적용 조건
Agent가 이 Skill을 트리거할지 판단하는 의사결정 체인
▶
사용자가 트리거 구문을 말했나요?
→
YES
→
현재 Alice 프로젝트 디렉토리에 있나요?
→
YES
→
Skill 트리거
↓
NO
→
일반 기능으로 처리
마찬가지로, 두 번째 판단 노드가 NO(Alice 디렉토리가 아님)이면 "일반 기능으로 처리"로 이동합니다.
조건이 충족되지 않으면 Skill은 자동으로 종료되어 일반 대화를 방해하지 않습니다.
조건이 충족되지 않으면 Skill은 자동으로 종료되어 일반 대화를 방해하지 않습니다.
📌 설계 결정: 적용 조건 = 잘못된 트리거를 방지하는 안전장치입니다. 적용 조건이 없으면, 어떤 프로젝트에서든 "릴리스"라고 말하면 Alice의 릴리스 워크플로우가 실행됩니다 — 재앙적인 버그입니다.
3
실행 단계
7단계 파이프라인: Git 확인부터 랜딩 페이지 동기화까지
▶
Git 확인
→
테스트 실행
→
앱 빌드
→
버전 업데이트
→
릴리스 노트 작성
→
COS 업로드
→
랜딩 페이지 동기화
클릭하여 Agent의 단계별 실행을 시뮬레이션하세요
📌 설계 결정: 단계 순서가 매우 중요합니다: "테스트 후 빌드" vs "빌드 후 테스트"? Skill의 단계 순서 = 당신이 올바르다고 생각하는 SOP 흐름입니다. Agent는 이 순서를 엄격하게 따릅니다.
4
허용된 도구
이 Skill 실행 중 Agent가 사용할 수 있는 도구 목록
▶
허용
run_command
edit_file
read_file
git
web_search
금지
delete_file
agent (서브 Agent 실행 불가)
📌 설계 결정: 허용 도구 = 안전 경계. 이 Skill을 실행할 때 Agent가 사용할 수 있는 도구를 제한합니다. delete_file 금지는 릴리스 과정에서 실수로 파일을 삭제하는 것을 방지하고; 서브 Agent 금지는 실행 체인의 예측 가능성을 유지하기 위함입니다.
5
안전 제약 조건
넘을 수 없는 레드라인 — Agent의 교통 규칙
▶
force push 금지: 다른 사람의 커밋을 덮어쓰는 것을 방지합니다
테스트 건너뛰기 금지: 아무리 긴급해도 테스트 실패 시 릴리스하지 않습니다
실패 시 중단 및 보고, 자동 재시도 금지: 제어권을 인간에게 반환합니다
📌 설계 결정: 안전 제약 조건은 Skill에서 가장 중요한 부분입니다. 단계가 잘못되면 Agent는 잘못된 일을 할 뿐이지만, 제약 조건이 빠지면 Agent는 위험한 일을 할 수 있습니다. 좋은 제약 조건 = 명확한 금지 사항 + 실패 시 그레이스풀 디그레이데이션 전략.
더 많은 Skill 예시
content-creator
콘텐츠 창작 시작점: 스타일 분석부터 최종 납품까지의 완전한 작성 워크플로우
스타일 프로파일→
요구사항 확인→
개요 설계→
심층 연구→
글 작성
트리거 구문: 글 써줘, 글을 쓰고 싶어, 초안 작성, 포스트 작성
핵심 설계: 초안 작성 전 사용자의 글쓰기 스타일을 먼저 분석 — 모델이 직접 생성하는 기회를 주지 않습니다. 이를 통해 출력이 항상 사용자의 개인 스타일에 맞도록 하고 일반적인 AI 느낌을 피합니다.
도구 권한: web_search 허용 (심층 연구는 인터넷 필요); 직접 발행 금지 (인간 검토 필요).
핵심 설계: 초안 작성 전 사용자의 글쓰기 스타일을 먼저 분석 — 모델이 직접 생성하는 기회를 주지 않습니다. 이를 통해 출력이 항상 사용자의 개인 스타일에 맞도록 하고 일반적인 AI 느낌을 피합니다.
도구 권한: web_search 허용 (심층 연구는 인터넷 필요); 직접 발행 금지 (인간 검토 필요).
web-importer
웹 임포터: 웹 페이지 콘텐츠를 WPS 노트에 고품질로 저장
URL 감지→
콘텐츠 크롤링→
형식 변환→
노트에 저장
트리거 구문: 이 페이지 노트에 저장, 이 기사 임포트, 웹 페이지를 노트로
핵심 설계: 세 가지 페이지 유형(WeChat 기사, Twitter/X, 일반 웹 페이지)을 자동으로 감지하고 다른 크롤링 로직을 적용합니다. 사용자 입장에서는 하나의 요청이지만 내부적으로는 세 가지 전략이 있습니다.
안전 제약: 로그인이 필요한 페이지는 저장하지 않습니다 (개인정보 유출 방지).
핵심 설계: 세 가지 페이지 유형(WeChat 기사, Twitter/X, 일반 웹 페이지)을 자동으로 감지하고 다른 크롤링 로직을 적용합니다. 사용자 입장에서는 하나의 요청이지만 내부적으로는 세 가지 전략이 있습니다.
안전 제약: 로그인이 필요한 페이지는 저장하지 않습니다 (개인정보 유출 방지).
tag-organize
태그 정리: 모든 태그를 스캔하고 중복을 찾아 지능적으로 병합
태그 스캔→
중복 분석→
병합 제안→
정리 실행
트리거 구문: 노트 태그 정리, 태그 청소, 태그가 너무 많아, 태그가 너무 복잡해
핵심 설계: 먼저 제안을 제시하고, 사용자 확인 후 실행하며, 자동으로 병합하지 않습니다. 이는 "Human-in-the-loop" 설계 원칙을 구현합니다.
안전 제약: 태그를 삭제하지 않고 병합만 합니다; 실행 전 사용자 확인이 필수입니다.
핵심 설계: 먼저 제안을 제시하고, 사용자 확인 후 실행하며, 자동으로 병합하지 않습니다. 이는 "Human-in-the-loop" 설계 원칙을 구현합니다.
안전 제약: 태그를 삭제하지 않고 병합만 합니다; 실행 전 사용자 확인이 필수입니다.
📌 핵심 인사이트: 좋은 Skill = 좋은 SOP. Skill을 작성하는 사람은 도메인 전문가이고, Skill을 사용하는 사람은 Agent입니다. 이상적인 Skill 세분화 수준은 하나의 완전한 워크플로우입니다: 너무 거칠면 지침이 없고, 너무 세밀하면 캡슐화할 가치가 없습니다.
Takeaway
Takeaway — Skill 하나는 Agent를 위한 SOP입니다: 언제 트리거할지, 어떤 단계로 실행할지, 어떤 도구를 사용할 수 있는지, 어떤 안전 제약 조건이 있는지. Skill을 작성한다는 것은 본질적으로 인간 전문가의 경험을 Agent가 실행할 수 있는 프로세스로 인코딩하는 것입니다.