스킬은 에이전트가 작업 중 호출하는 재사용 가능한 지시 세트입니다. 에이전트에게 특정 작업 수행 방법을 가르치는 마크다운 파일입니다.

디렉토리 구조

skills/my-skill/
├── SKILL.md
└── references/    (선택)

SKILL.md 요구사항

YAML 프론트매터에 두 필드가 필요합니다:

---
name: my-skill          # kebab-case 고유 식별자
description: |          # 에이전트가 이 스킬을 사용할 때를 결정하는 라우팅 로직
  use when: ...
  don't use when: ...
---

description은 에이전트가 전체 내용을 로드할지 여부를 결정합니다 — 홍보 텍스트가 아니라 결정 로직입니다.

런타임 프로세스

  1. 에이전트가 컨텍스트에서 스킬 메타데이터(이름 + 설명) 확인
  2. 에이전트가 현재 태스크에 스킬이 관련 있는지 판단
  3. 관련 있으면 전체 SKILL.md 내용 로드
  4. 에이전트가 스킬의 지시를 따름

이 접근법은 필요할 때만 상세 지시를 로드하여 기본 프롬프트를 최소화합니다.

핵심 가이드라인

  • 조건부 로직으로 설명 작성 — “use when"과 “don’t use when” 기준 포함
  • 지시를 구체적으로 — 모호하지 않게 실행할 수 있도록
  • 구체적 API 호출과 명령 예시 포함 — 추상적 설명 대신
  • 하나의 관심사에 하나의 스킬 파일
  • 보충 자료는 references/ 디렉토리에 저장

스킬 디스커버리

어댑터가 에이전트에 스킬을 제공하는 방법을 제어합니다. 어댑터마다 다른 방법 사용 — 심링크가 있는 임시 디렉토리 또는 글로벌 스킬 디렉토리.