Revamping Skills in Deep Agents

🖼️ 인포그래픽

🖼️ 4컷 인포그래픽

💡 한 줄 요약

Deep Agents는 스킬에 도구를 연결하고 런타임에 스킬을 고정하거나 스레드 중간에 다시 로드하는 기능을 추가해, 필요한 지식과 도구를 단계적으로 제공하고 장기 실행 에이전트의 스킬을 최신 상태로 유지하도록 개선했다.

📌 핵심 요약

• 스킬은 지침·스크립트·참조 파일 등을 묶은 공개 표준이며, 처음에는 이름과 설명만 컨텍스트에 제공하고 필요한 지침과 파일을 단계적으로 읽는다. 기업의 스킬 저장소가 수천 개 규모로 커지면서 Deep Agents는 도구 연결, 스킬 고정, 스킬 재로딩을 강화했다.
• metadata.include_tools로 스킬에 연결한 도구는 에이전트가 해당 스킬을 읽어야 제공되며, 그전에 호출하면 알 수 없는 도구로 실패한다. Anthropic과 OpenAI의 대화 중 도구 추가를 지원하는 최신 모델에서는 새 시스템 메시지로 도구를 추가해 기존 프롬프트 캐시를 유지하고, 다른 모델에서는 기존처럼 요청의 도구 목록에 추가한다.
• SkillsMiddleware에 전달하는 함수로 도구 이름 대신 지정한 레이블을 실제 도구에 연결할 수 있다. 이를 통해 MCP 서버의 도구 전체를 묶어 제공하거나 런타임 사용자 권한에 따라 도구를 제한할 수 있으며, 원문의 pipeline-forecast 예시에서는 관리자만 예측을 수정할 수 있다.
• 앱이 /meeting-prep 같은 사용자 요청이나 UI에서 스킬 이름을 추출해 pinned_skills로 전달하면, 다음 모델 호출 전에 지침과 연결된 도구가 제공된다. 이 방식은 read_file 왕복을 없애 작업 시작을 두 번째 모델 호출에서 첫 번째 호출로 앞당기며, 스킬별 태그 메시지를 한 번만 추가해 기존 메시지와 프롬프트 캐시를 보존한다.
• skills_metadata를 None으로 설정하면 다음 실행에서 모든 스킬 소스를 다시 검색해 추가·수정·삭제된 스킬을 새 스레드 없이 반영할 수 있다. 새 스킬이 발견되어 시스템 프롬프트가 바뀌면 프롬프트 캐시가 무효화되지만, 공급자 캐시는 보통 수분에서 한 시간의 비활성 기간 뒤 만료되므로 오래 쉬었던 스레드는 이미 캐시가 차가운 상태일 수 있다.

🧩 주요 포인트

1. 스킬을 읽은 뒤에만 도구를 제공하고 런타임 권한으로 도구를 선별한다 → 컨텍스트 사용을 줄이면서 도구 사용 지침과 접근 권한을 함께 적용할 수 있다.
2. pinned_skills가 명시적으로 선택한 스킬을 첫 모델 호출 전에 제공한다 → read_file 왕복에 따른 지연과 모델의 스킬 선택 불확실성을 줄이며, 요청 해석은 앱이 담당한다.
3. 도구 추가와 스킬 재로딩은 프롬프트 캐시에 서로 다른 영향을 준다 → 모델의 대화 중 도구 추가 지원 여부와 스레드의 비활성 기간을 고려해 최신성 확보 비용을 판단해야 한다.

🧠 상세 정리

1. 공개 표준 스킬과 규모 확장의 요구

원문은 스킬을 에이전트에 도메인 지식을 제공하는 효과적인 방식으로 소개하며, 고객 미팅 준비나 영업팀 방식에 따른 통화 기록 검토를 예로 든다. 스킬은 지침, 스크립트, 참조 파일을 담은 폴더이며 핵심은 마크다운 파일이므로, 작성에 반드시 기술 전문성이 필요한 것은 아니라고 설명한다. Agent Skills는 어떤 모델에서도 사용할 수 있는 공개 표준이고 수십 개 에이전트 제품이 지원한다는 점도 강조한다. 기업의 스킬 저장소가 수천 개 규모로 성장하고 여러 팀과 에이전트가 이를 공유하면서, 필요한 도구를 지침과 함께 제공하고 명시적으로 선택한 스킬을 미리 로드하며 장기 실행 스레드의 변경 사항을 반영하려는 요구가 커졌다는 것이 이번 개편의 배경이다.

2. 발견·활성화·실행의 단계적 공개

스킬 디렉터리의 SKILL.md는 name과 description을 담은 YAML frontmatter와 에이전트가 따라야 할 지침으로 구성되며, scripts/, references/, assets/ 아래에 보조 파일을 포함할 수 있다. 발견 단계에서는 각 스킬의 이름과 설명만 시스템 프롬프트에 들어가고, 활성화 단계에서는 작업에 맞는 스킬의 전체 SKILL.md를 read_file로 읽는다. 실행 단계에서는 지침을 따르면서 실제로 필요할 때만 스크립트나 참조 파일을 추가로 읽으므로, 컨텍스트는 작업에 필요한 만큼 확장된다. 원문의 GTM agent는 meeting-prep, call-transcripts, competitive-intel-card 등 50개가 넘는 스킬을 갖추고 있으며, 사용 전 스킬 하나의 비용을 시스템 프롬프트 한 줄 수준으로 제한하는 방식이 큰 라이브러리를 유지하는 근거로 제시된다.

3. 스킬과 도구를 함께 공개하는 연결 방식

기존에는 스킬과 도구가 따로 공개되어, tool search로 도구 스키마를 컨텍스트 밖에 두더라도 도구와 그 사용법을 설명하는 스킬 사이의 연결은 보장되지 않았다. 따라서 에이전트가 스킬을 읽지 않고 도구를 찾아 호출하거나, 스킬을 읽은 뒤에도 필요한 도구를 별도로 검색해야 하는 문제가 있었다. 새 기능에서는 스킬의 metadata.include_tools에 도구를 나열하고 해당 도구들을 에이전트 대신 SkillsMiddleware에 전달하면, 스킬을 읽을 때 연결된 도구도 함께 제공된다. 그전에 도구를 호출하면 알 수 없는 도구로 실패하므로, 도구 사용에 앞서 지침을 읽도록 만들면서 컨텍스트도 작게 유지한다. GTM agent의 call-transcripts는 통화 검색과 기록 읽기를 설명하므로 search_calls와 get_transcript를 연결할 자연스러운 위치로 제시된다.

4. 대화 중 도구 추가와 프롬프트 캐시

원문은 대화 도중 도구를 추가하기 위해 요청의 도구 목록을 수정하면 기존 프롬프트 캐시가 무효화되던 문제를 설명한다. Anthropic과 OpenAI의 최신 모델 중 대화 중간에 새 도구를 받는 모델에서는, Deep Agents가 스킬을 읽은 직후 연결된 도구를 새 시스템 메시지에 넣어 제공한다. 이 경우 앞부분의 캐시된 프롬프트는 바뀌지 않으므로, 필요한 도구를 뒤늦게 공개하면서도 기존 캐시를 유지할 수 있다. 다만 이 동작은 해당 기능을 지원하는 모델에 한정되며, 다른 모델에서는 이전과 같이 요청의 도구 목록에 도구를 추가한다. 따라서 도구를 스킬과 함께 공개한다는 기능 자체와, 그 과정에서 프롬프트 캐시를 보존할 수 있다는 효과는 모델 지원 조건을 구분해 이해해야 한다.

5. 레이블을 통한 도구 묶음과 권한 제어

대부분의 스킬은 도구 이름을 목록으로 지정하는 방식으로 충분하지만, 더 세밀한 제어가 필요하면 도구 이름 대신 레이블을 적을 수 있다. SkillsMiddleware에 전달한 함수가 각 레이블을 실제 도구로 변환하므로, MCP 서버의 모든 도구를 하나의 이름 아래 묶어 공개하고 개별 도구를 일일이 나열하지 않아도 된다. 이 함수는 그래프의 런타임을 전달받아 사용자 신원을 확인할 수 있으며, 그 사용자에게 허용된 도구만 반환하는 방식으로 접근을 제한한다. 원문의 예시에서는 call-transcripts에 calls MCP 서버의 모든 도구를 제공하고 pipeline-forecast에는 CRM 도구를 제공하되, 예측을 수정하는 기능은 관리자에게만 허용한다. 도구 연결은 단순한 지연 로딩을 넘어, 실제 실행 시점의 권한에 맞춰 사용할 도구를 결정하는 수단으로도 제시된다.

6. 명시적으로 선택한 스킬의 사전 고정

사용자가 /meeting-prep for my Acme call tomorrow처럼 원하는 스킬을 이미 지정한 경우에도, 고정 기능이 없으면 모델은 설명만 보고 스킬을 읽어야 하므로 작업 전에 왕복이 추가되고 올바른 스킬의 로드도 보장되지 않는다. pinned_skills를 사용하면 앱이 메시지나 UI에서 스킬 이름을 찾아 전달하고, 미들웨어가 다음 모델 호출 전에 해당 지침을 대화에 추가한다. Deep Agents 자체가 메시지를 해석하지는 않으므로 명령 문법과 이름 추출 방식은 앱이 정한다. 지침과 연결된 도구가 이미 제공되기 때문에 작업은 두 번째 모델 호출 대신 첫 번째 호출에서 시작할 수 있어 지연이 줄고 동작의 예측 가능성이 높아진다. 각 스킬은 태그가 붙은 메시지로 한 번만 추가되어 이전 메시지와 프롬프트 캐시를 유지하며, 채팅 UI는 전체 지침 대신 스킬 레이블을 표시할 수 있다.

7. 장기 실행 스레드에서 스킬 다시 읽기

기존에는 스레드 시작 시 스킬을 로드해 에이전트 상태에 보관하고, 이후 모든 턴에서 같은 스킬 집합을 재사용했다. 이제 에이전트를 호출할 때 skills_metadata를 None으로 설정하면 이 목록을 무효화하고, 다음 실행에서 모든 소스를 다시 검색해 스킬 라이브러리의 변경 사항을 반영할 수 있다. 원문은 팀원이 competitive-intel-card를 새로 추가했을 때 앱이 목록을 무효화해 다음 실행에서 이를 발견하는 예를 들며, 핵심 요약에서는 추가·수정·삭제된 스킬을 새 스레드 없이 반영할 수 있다고 설명한다. 초기화는 실행 입력으로 전달되므로 클라이언트의 /reload 명령을 통해 사용자에게 재로딩 제어권을 줄 수도 있다. update_state나 미들웨어에서도 초기화할 수 있어, 앱이 스킬을 다시 읽는 시점을 선택할 수 있다는 점이 강조된다.

8. 재로딩 비용과 개편의 적용 범위

재로딩으로 새 스킬을 발견하면 시스템 프롬프트가 바뀌므로 프롬프트 캐시가 무효화되며, 이는 연결 도구를 새 메시지로 추가할 때 캐시를 보존하는 동작과 구분되는 비용이다. 다만 원문은 공급자 캐시가 보통 수분에서 한 시간 정도의 비활성 기간 뒤 만료되므로, 오래 쉬었던 스레드에서는 사용자가 돌아왔을 때 이미 캐시가 차가워져 있을 수 있다고 설명한다. 결론에서는 도구를 필요한 스킬과 함께 로드하고, 워크플로에 필요한 스킬은 앞서 제공하며, 라이브러리 변경을 장기 실행 스레드에 반영하는 것이 규모 확장에 도움이 된다고 정리한다. 또한 스킬이 공개 표준이므로 팀이 작성한 스킬을 여러 모델과 에이전트에서 사용할 수 있다는 점을 다시 강조한다. 이 기능들은 최신 deepagents에서 제공되며, 시작 방법은 스킬 문서에서 확인하고 의견은 GitHub issues, 포럼 또는 X로 전달할 수 있다고 안내한다.

🧾 핵심 주장 / 시사점

• 단계적 공개의 대상이 지침과 참조 파일에서 연결 도구까지 확장되면서, 도메인 지식의 제공 시점과 도구 사용 가능 시점을 함께 관리할 수 있게 됐다.
• pinned_skills는 사용자의 명시적 선택을 컨텍스트에 직접 반영하지만, 요청 문법을 해석하는 책임은 앱에 있으므로 동작의 예측 가능성은 앱의 이름 추출 방식에도 달려 있다.
• 프롬프트 캐시 보존은 모든 변경에 공통으로 적용되지 않는다. 지원 모델에서의 도구 추가는 기존 캐시를 유지할 수 있지만, 새 스킬을 발견하는 재로딩은 시스템 프롬프트를 바꿔 캐시를 무효화한다.

✅ 액션 아이템

• Deep Agents의 metadata.include_tools와 SkillsMiddleware를 활용해 스킬 지침을 읽은 뒤 도구를 제공하고, 런타임 사용자 권한에 따라 도구를 제한하는 적용 방식을 검토한다.
• /meeting-prep 같은 명시적 요청의 해석 방식을 앱에서 정하고, pinned_skills로 지침과 연결 도구를 첫 모델 호출 전에 제공하는 방식을 적용한다.
• skills_metadata를 None으로 설정하는 재로딩 시점을 스레드의 비활성 기간과 프롬프트 캐시 무효화 비용을 고려해 결정한다.

❓ 열린 질문

• 사용 중인 Anthropic 또는 OpenAI 모델은 대화 중 도구 추가를 지원해 스킬의 연결 도구를 제공할 때 프롬프트 캐시를 유지할 수 있는가?
• 앱은 /meeting-prep 같은 요청이나 UI에서 어떤 방식으로 스킬 이름을 추출해 pinned_skills에 전달할 것인가?
• 추가·수정·삭제된 스킬의 반영 필요성과 스레드의 비활성 기간을 고려할 때 skills_metadata를 None으로 설정하는 시점은 언제가 적절한가?