[Agent Skills 완전정복 #8] 내 에이전트에 스킬 기능 붙이기 (클라이언트 구현)

Agent Skills 시리즈 마지막 편. 지금까지는 "스킬 쓰는/만드는 사람" 시점이었다면,
이번엔 시점을 뒤집어 내가 만든 에이전트·개발툴에 '스킬 기능'을 붙이는 법을 봅니다.

전체 생애주기는 발견 → 파싱 → 카탈로그 노출 → 활성화 → 컨텍스트 관리 5단계입니다. 아키텍처가 달라도 핵심은 같고, 두 가지가 구현 디테일을 가릅니다 — 스킬이 어디 사나(로컬 파일시스템 vs 클라우드), 모델이 내용을 어떻게 읽나(파일 읽기 vs 전용 도구).

---

🎯 핵심 원리 — 점진적 로딩 3계층

계층	로드	시점 / 비용
1. Catalog	name + description	세션 시작 / 스킬당 ~50-100토큰
2. Instructions	SKILL.md 본문	활성화 시 / <5000토큰 권장
3. Resources	scripts·references·assets	본문이 참조할 때 / 가변

스킬 20개를 깔아도 20개 본문을 미리 다 로드하지 않습니다 — 실제로 쓰는 것만 펼쳐집니다.

---

① 스킬 발견(Discover)

세션 시작 시 가능한 스킬을 찾아 메타데이터만 로드합니다. 보통 프로젝트 단위와 사용자 단위 두 스코프를 스캔해요.

• 각 스코프에서 클라이언트 전용 경로(.<your-client>/skills/)와 크로스 클라이언트 관례(.agents/skills/)를 함께 스캔 → 다른 호환 클라이언트가 깐 스킬도 자동으로 보임
• SKILL.md가 정확히 든 하위 폴더를 찾되, .git/·node_modules/는 건너뛰고 깊이·개수 상한을 둠
• 이름 충돌 시 결정적 규칙 — 보편 관례는 프로젝트 > 사용자. 가려진 스킬은 경고 로그
• 신뢰 검사 — 프로젝트 스킬은 갓 클론한 미신뢰 저장소일 수 있음. 폴더를 신뢰 표시했을 때만 로드해 지침 주입(prompt injection)을 막아라
• 클라우드/샌드박스 — 로컬 파일시스템이 없으니, 사용자·조직 스킬은 설정 저장소 클론·업로드 등 외부 소스로 공급. 내장 스킬은 정적 자산으로 패키징

---

② SKILL.md 파싱(Parse)

• 앞쪽 --- 사이 YAML에서 name·description(필수)과 선택 필드를 추출, 닫는 --- 뒤를 본문으로
• 관대한 검증 — 이름이 폴더명과 불일치/64자 초과면 경고 후 그대로 로드, description이 비었거나 YAML이 완전 깨지면 건너뛰고 로그
• 다른 클라이언트용 파일은 콜론 포함 비인용 값 등 기술적으로 깨진 YAML이 흔함 → 따옴표로 감싸 재시도하는 폴백이 호환성↑
• 스킬 레코드는 최소 name·description·location(절대경로)을 저장, name으로 빠르게 조회

---

③ 카탈로그 노출(Disclose)

본문은 빼고 어떤 스킬이 있는지만 모델에게 알립니다(계층 1). XML·JSON·불릿 등 형식은 자유.

<available_skills>
  <skill>
    <name>pdf-processing</name>
    <description>Extract PDF text, fill forms, merge files. Use when handling PDFs.</description>
    <location>/home/user/.agents/skills/pdf-processing/SKILL.md</location>
  </skill>
</available_skills>

• 배치 위치는 시스템 프롬프트 섹션(가장 단순) 또는 전용 활성화 도구의 description
• 옆에 짧은 행동 지침("작업이 설명과 맞으면 해당 위치의 SKILL.md를 읽어라" 등)을 붙임
• 필터링 — 비활성/권한 거부/모델 호출 옵트아웃된 스킬은 아예 카탈로그에서 숨겨라(나열 후 차단 X). 스킬이 하나도 없으면 카탈로그 자체를 생략

---

④ 활성화(Activate)

모델/사용자가 스킬을 고르면 본문을 컨텍스트에 넣습니다(계층 2). 대부분 모델의 판단에 맡깁니다(하니스가 키워드 매칭하지 않음).

• 파일 읽기 활성화 — 모델이 표준 파일 읽기 도구로 SKILL.md를 읽음. 가장 단순
• 전용 도구 활성화(activate_skill) — 파일 접근이 없을 때 필수. 반환 내용 제어·구조화 태깅·리소스 목록·권한 적용 가능. name 파라미터를 유효 스킬 enum으로 제한해 환각 방지
• 사용자 명시 활성화 — /skill-name 같은 슬래시 명령으로 하니스가 직접 주입

전용 도구라면 구조화 래핑이 유용합니다 — 스킬 내용을 식별 태그로 감싸고, 디렉토리 경로와 번들 리소스 목록을 함께 알리되 미리 읽지는 않습니다(모델이 필요할 때 로드).

<skill_content name="pdf-processing">
[SKILL.md 본문]
Skill directory: /home/user/.agents/skills/pdf-processing
  <skill_resources>
    <file>scripts/extract.py</file>
    <file>references/pdf-spec-summary.md</file>
  </skill_resources>
</skill_content>

권한 시스템이 있다면 스킬 디렉토리를 allowlist 하세요. 안 그러면 번들 스크립트를 읽을 때마다 권한 팝업이 떠 흐름이 끊깁니다.

---

⑤ 컨텍스트 관리(Manage)

• 압축(compaction)에서 보호 — 컨텍스트가 차 옛 메시지를 잘라낼 때 스킬 내용은 제외하라. 조용히 사라지면 에러 없이 성능만 저하됨. 계층 4의 구조화 태그로 식별·보존
• 중복 활성화 제거 — 이미 로드된 스킬은 재주입 생략
• 서브에이전트 위임(고급·일부 클라이언트) — 복잡한 워크플로우는 별도 서브에이전트 세션에서 돌리고 요약만 본 대화로 반환

---

✍️ 시리즈 마무리

여덟 편에 걸쳐 Agent Skills를 개념 → 규격 → 만들기 → 다듬기 → 평가 → 스크립트 → 구현까지 훑었습니다. 핵심을 한 줄로 압축하면 —

스킬은 SKILL.md 폴더 하나로 에이전트에 전문성을 끼우고, 점진적 로딩으로 그 비용을 최소화하는, 벤더 중립 오픈 표준이다.

이제 직접 만들어 볼 차례입니다. 끝까지 함께해 주셔서 감사합니다! 🙌

---

📎 출처: 이 글은 Agent Skills 공식 문서 — How to add skills support to your agent (© Anthropic, CC BY 4.0)를 한국어로 번역·재구성한 것입니다.

---