Claude Code 서브에이전트 스킬 로드 문제 해결법

Claude Code에서의 멀티 에이전트 스킬 로딩 문제

Claude Code v2.1.91에서 멀티 에이전트 시스템을 구축하는 한 개발자가 중요한 제한 사항을 발견했습니다: 서브에이전트는 .claude/skills/ 디렉터리에 정의된 스킬에 접근할 수 없지만, 메인 세션은 트리거 키워드, 컨텍스트 내 전체 스킬 내용, 품질 게이트를 완벽하게 따르며 스킬을 로드합니다.

문제 상세

subagent_type을 사용하여 에이전트 도구를 통해 서브에이전트를 생성할 때, 해당 에이전트는 스킬에 전혀 접근할 수 없습니다. 개발자는 여섯 가지 접근 방식을 테스트했습니다:

에이전트 프론트매터의 skills: - "시작 시 전체 스킬 내용이 주입됨"으로 문서화되었지만 효과가 없음
tools: 목록의 Skill - 인식되지 않음, Skill 도구는 서브에이전트에서 사용할 수 없음
--agent myagent CLI 플래그 - 동일한 결과, 스킬이 로드되지 않음
에이전트 팀 (TeamCreate) - 동일한 결과
부모 세션에서 스킬을 기본적으로 로드한 후 에이전트 생성 - 에이전트가 부모 컨텍스트를 상속받지 않음
기본 Claude 스킬 (frontend-design, claude-api)조차 서브에이전트에서 사용할 수 없음

구성 예시

에이전트 파일 구조:

---
name: Sales
description: "영업 에이전트"
model: opus
skills:
- outreach
- validator
tools:
- Bash
- Read
- Write
- WebSearch
---

스킬은 .claude/skills/outreach/SKILL.md에 적절한 프론트매터와 함께 존재하며 메인 세션에서 완벽하게 작동합니다.

영향

이 제한 사항으로 인해 개발자에 따르면 멀티 에이전트 아키텍처가 "도메인 지식을 요구하는 모든 작업에 쓸모없게" 됩니다. 에이전트는 스킬 파일을 Read만 할 수 있어(시스템 지시사항이 아닌 채팅 내용으로 로드됨) 상당히 저조한 결과를 생성합니다. 메인 세션(스킬이 기본적으로 로드됨)과 서브에이전트(스킬이 마크다운으로 읽힘) 간의 품질 차이는 "엄청나다"고 설명됩니다.

개발자는 macOS에서 Claude Code 2.1.91을 실행 중이며, 누군가가 커스텀 에이전트 프론트매터에서 skills:를 성공적으로 사용했는지, 아니면 이 문제가 알려진 제한 사항, 버그 또는 구성 오류인지 묻고 있습니다.

📖 전체 소스 읽기: r/ClaudeAI