Deep Agent의 스킬 기능 개선점

주요 요약

도구를 스킬에 바인딩할 수 있게 되었습니다. 도구 스키마는 에이전트가 해당 스킬을 읽기 전까지 컨텍스트 밖에 유지되며, 대화 중간에 새로운 도구를 받아들이는 모델의 경우 이를 추가해도 프롬프트 캐시를 온전히 유지합니다.
앱은 런타임 시점에 스킬을 고정(pin)할 수 있습니다. 따라서 첫 번째 모델 호출 전에 지침이 컨텍스트에 포함되며, read_file 라운드 트립이 필요 없습니다.
스킬은 스레드 중간에도 다시 로드될 수 있습니다. 따라서 장시간 실행되는 에이전트가 새로운 스킬을 추가하거나 편집/삭제해도 새 스레드를 시작할 필요 없이 이를 반영합니다.

스킬은 에이전트에게 도메인 지식을 부여하는 가장 좋은 방법 중 하나입니다. 스킬이란 에이전트에게 고객 미팅 준비나 영업팀 방식대로 통화 녹취록 검토와 같은 작업을 수행하는 방법을 가르치는 일련의 지침, 스크립트 및 참고 파일들의 폴더를 의미합니다. Agent Skills는 모든 모델에서 작동하며 수십 개의 에이전트 제품에서 지원되는 오픈 표준입니다. 또한 기술 전문가가 아니어도 작성할 수 있습니다. 근본적으로 스킬은 마크다운(markdown) 파일이기 때문입니다.

스킬이 작동하는 이유는 점진적 공개(progressive disclosure) 덕분입니다. 에이전트는 처음에 각 스킬의 이름과 설명만 보고, 작업에 필요할 때만 전체 지침을 읽습니다. 이는 컨텍스트를 작게 유지시켜주며, 컨텍스트 엔지니어링은 효과적인 에이전트를 구축하는 핵심 요소입니다.

사용량이 증가함에 따라 팀들이 스킬에게 요구하는 것도 변화하고 있습니다. 저희는 수천 개의 스킬로 성장하여 여러 팀과 에이전트가 공유하는 기업용 스킬 레지스트리를 목격하고 있습니다. 저희는 일반적인 요청들을 해결하기 위해 Deep Agents의 스킬 지원 기능을 개선했습니다:

스킬에 도구 바인딩: 스킬에 바인딩된 도구는 에이전트가 해당 스킬을 읽을 때만 로드됩니다.
고정된 스킬(Pinned skills): 사용자가 /meeting-prep와 같이 특정 스킬을 명시적으로 요청할 경우, 앱은 다음 모델 호출 전에 이를 로드할 수 있습니다.
스킬 재로드: 장시간 실행되는 스레드는 처음부터 다시 시작하지 않고도 새롭거나 변경된 스킬을 반영할 수 있습니다.

스킬 작동 방식

스킬이란 SKILL.md 파일이 있는 디렉토리입니다: YAML 프론트매터와 name, 그리고 description을 포함합니다.

, followed by the instructions the agent follows. A skill can also bundle supporting files under scripts/, references/, and assets/ (spec).

Only a skill's name and description are always in context. The agent reads the instructions on demand, and loads scripts, references, and assets only when needed.

이 게시물 전체에서 우리는 GTM 에이전트를 실행 예시로 사용할 것입니다. 이 에이전트는 Deep Agents를 기반으로 하며, 50개가 넘는 스킬 라이브러리는 meeting-prep, call-transcripts, competitive-intel-card와 같은 영업 사원의 반복적인 작업을 다룹니다.

발견(Discovery). 에이전트는 시작 시 각 스킬의 name과 description을 시스템 프롬프트에서 확인합니다.활성화(Activation). 작업이 특정 스킬과 일치하면, 에이전트는 read_file을 사용하여 전체 SKILL.md를 읽습니다.실행(Execution). 에이전트는 지침을 따르고, 호출할 때만 스크립트나 참고 파일을 읽습니다.

The agent's context grows only by what the task needs: every skill's name and description at startup, then one skill's instructions, then one reference file.

스킬이 사용되기 전까지는 시스템 프롬프트에서 한 줄의 비용을 차지하므로, 라이브러리는 컨텍스트를 복잡하게 만들지 않으면서도 풍부한 스킬에 대한 참조를 보유할 수 있습니다. 이제 Deep Agents에서 우리가 만든 개선 사항들을 살펴보겠습니다.

스킬에 도구 바인딩하기(Binding tools to skills)

스킬은 종종 에이전트에게 특정 도구를 사용하는 방법을 알려주며, 일부 도구는 에이전트가 해당 지침을 읽었을 때만 잘 작동합니다. 이전까지 스킬과 도구는 별도로 공개되었습니다. 도구 검색(tool search)을 통해 도구 스키마를 컨텍스트에서 제외할 수는 있었지만, 도구를 설명하는 것이 도구와 스킬을 연결해 주는 것은 아무것도 없었습니다. 에이전트는 스킬을 읽지 않고도 도구를 찾고 호출하거나, 스킬은 읽었더라도 여전히 도구를 검색해야 했습니다.

이제 도구를 스킬에 바인딩할 수 있어, 스킬과 그 도구들이 함께 공개됩니다. 바인딩된 도구는 에이전트가 해당 스킬을 읽기 전까지 컨텍스트에 추가되지 않으며, 그 이전에 호출하면 알 수 없는(unknown) 도구로 실패합니다. 이는 컨텍스트를 간결하게 유지하며, 에이전트가 도구를 호출하기 전에 사용 방법을 읽었음을 의미합니다. 우리의 GTM 에이전트에서 call-transcripts는 통화를 검색하고 녹취록을 읽는 방법을 설명하므로, 이 도구들을 바인딩할 자연스러운 장소입니다.

스킬의 프론트매터(frontmatter)에 있는 metadata.include_tools 아래에 도구 목록을 지정하세요:

call-transcripts SKILL.md frontmatter listing include_tools: search_calls get_transcript

그 도구들을 에이전트에게 전달하는 대신 SkillsMiddleware에 전달합니다:

Python: create_deep_agent with SkillsMiddleware(tools=[search_calls, get_transcript])

Reading call-transcripts unlocks search_calls and get_transcript. They arrive in a new system message, so the cached prefix above it stays unchanged.

이전에는 대화 도중에 tools를 추가하는 것은 요청의 tool list를 편집해야 했고, 이는 prompt cache를 무효화했습니다. Anthropic과 OpenAI은 이제 최신 모델들이 대화 중간에 tools를 수용할 수 있게 하여, 해당 모델들에서는 Deep Agents가 스킬에 바운드된 tools를 스킬이 읽힌 직후에 추가하며 캐시된 prefix는 그대로 유지됩니다 (Anthropic 및 OpenAI 통합 문서 참조). 다른 모델들의 경우, 이전과 같이 요청에 tools를 덧붙입니다.

목록은 대부분의 스킬을 다룹니다. 더 많은 제어를 위해, 스킬이 tool 이름 대신 레이블(label)을 지정할 수 있으며, SkillsMiddleware에 전달하는 함수가 각 레이블을 tools로 변환합니다. 이를 통해 다음 작업을 수행할 수 있습니다:

전체 tool 그룹 공개: 예를 들어, MCP 서버의 모든 tools를 하나에 묶어 이름으로 표시하고, 스킬 내에서 각각의 tools를 나열할 필요가 없습니다.런타임 권한 기반 tools 제어: 이 함수는 그래프의 런타임(runtime)을 받기 때문에 사용자가 누구인지 확인하고 그들이 사용할 수 있는 tools만 반환할 수 있습니다.

여기서, call-transcripts는 calls MCP 서버의 모든 tools를 가져오고, pipeline-forecast는 CRM tools를 가져오지만 관리자만이 예측(forecast)을 업데이트할 수 있습니다:

SKILL.md frontmatter for call-transcripts (include_tools: call_tools) and pipeline-forecast (include_tools: crm_tools)

Python: resolve_skill_tools returns every calls MCP tool for call_tools, and update_forecast only for managers

더 자세한 내용은 스킬에 tools 추가하기(Add tools to skills)를 참조하세요.

고정된 스킬 (Pinned skills)

때로는 사용자가 원하는 스킬을 이미 알고 있습니다. 저희 GTM agent의 경우, 담당자는 '내일 Acme 통화 준비 /meeting-prep for my Acme call tomorrow'와 같이 입력할 수 있습니다. pinning이 없는 경우, 모델은 스킬의 설명만 보고 이를 읽어야 합니다. 이는 작업 시작 전에 왕복(round trip)을 추가하며, 모델이 올바른 스킬을 로드한다고 보장되지 않습니다. 고정된 스킬을 사용하면, 앱이 메시지에서 스킬 이름을 찾거나 (또는 UI에서 파싱하여) pinned_skills에 전달하고, 미들웨어는 다음 모델 호출 전에 각 스킬의 지침(instructions)을 대화에 추가합니다. Deep Agents가 직접 메시지를 파싱하지 않으므로, 구문(syntax)을 선택할 수 있습니다:

Typing /meeting-prep names the skill, so the app can pin it for the agent's next model call.

Python: parse /meeting-prep from the message and pass it as pinned_skills to agent.invoke

A pinned skill's instructions are already in the conversation, so the agent starts the work on model call 1 instead of model call 2.

이는 지연 시간(latency)을 줄이고 동작을 더 예측 가능하게 만듭니다. 명령어는 컨텍스트에 포함되는 것이 보장되며, 고정된 스킬(pinned skill)의 바운드 도구(bound tools)도 함께 제공됩니다. 각 고정된 스킬은 태그가 지정된 메시지로 한 번 추가되므로 이전 메시지는 변경되지 않고, 프롬프트 캐시(prompt cache)는 유효하게 유지되며, 채팅 UI에서는 전체 텍스트 대신 레이블로 해당 스킬을 표시할 수 있습니다.

세션 중간에 스킬 다시 로드하기 (Reloading skills mid-thread)

스킬은 모든 스레드의 시작 시점에 로드되어 에이전트 상태(agent state)에 유지되므로, 이후의 모든 턴에서 동일한 스킬 세트를 재사용합니다. 이제 skills_metadata를 None으로 설정하여 에이전트를 호출할 때 이 목록을 무효화(invalidate)할 수 있습니다. 만약 팀원이 라이브러리에 competitive-intel-card 스킬을 추가하면, 애플리케이션은 스킬 목록을 무효화하기로 선택할 수 있으며 다음 실행에서 모든 소스를 다시 검색합니다:

Python: agent.invoke with skills_metadata set to None

Setting skills_metadata to None makes the next run rescan the skill library and pick up a skill added since the last run.

새로운 스킬을 찾아 재로드하는 것은 시스템 프롬프트(system prompt)를 변경하며, 이는 프롬프트 캐시를 무효화합니다. 오랫동안 유휴 상태였던 세션의 경우, 이 비용은 보통 이미 지불된 상태입니다. 제공업체 캐시(provider caches)는 일반적으로 비활성 상태로부터 몇 분에서 한 시간 내에 만료되기 때문에, 사용자가 돌아올 때쯤이면 캐시는 차가운(cold) 상태일 것입니다 (Anthropic, OpenAI).

재설정은 단순히 실행 입력(run input)이기 때문에 사용자에게 제어권을 넘길 수도 있습니다. 예를 들어, 클라이언트 측에서 /reload 명령어를 사용할 수 있습니다:

Python: a /reload command sets skills_metadata to None in the run payload

또한 update_state나 미들웨어(middleware)로부터 재설정할 수 있으므로, 애플리케이션이 스킬 재로드 시점을 제어할 수 있습니다. '스킬 다시 로드하기'를 참조하십시오.

시작하기 (Get started)

스킬은 에이전트에게 체계적인 도메인 지식을 제공하는 업계 표준 메커니즘입니다. 이러한 업데이트는 스케일에서 실행하기 더 쉽게 만듭니다: 도구는 스킬이 필요할 때만 로드되고, 워크플로우가 필요한 스킬은 미리 로드되며, 라이브러리가 변경되어도 장기 실행되는 세션은 최신 상태를 유지합니다. 그리고 스킬은 개방형 표준(open standard)이기 때문에 팀이 작성한 스킬은 여러 모델과 에이전트에서 작동합니다.

이 모든 기능은 최신 deepagents에 포함되어 있습니다. 시작하려면 스킬 문서를 읽어보시고, GitHub 이슈, 포럼 또는 X를 통해 의견을 알려주십시오.

감사의 글 (Acknowledgements)

새로운 기능을 개발하는 데 앞장선 Rich Scarrott님과, 기능 및 블로그 리뷰를 담당해주신 Hunter Lovell님께 감사드립니다!