Claude Managed Agents 가이드: 재사용 스킬과 컨텍스트 예산
Answer in brief
Claude Managed Agents는 에이전트에 첨부하거나 마운트된 GitHub 저장소에서 발견하는 재사용 가능한 파일 시스템 기반 스킬을 지원합니다. 관련 스킬은 자동으로 선택되며, 스킬을 추가할 때마다 세션 컨텍스트 창의 일부를 사용하고 스킬이 많아질수록 샌드박스 시작 시간이 늘어날 수 있습니다.
Key facts at a glance
| Product / model | Current ID or version | Use case | Evidence |
|---|---|---|---|
| claude-managed-agents | Official source does not specify a selectable model ID | Confirm the current product surface | Official source |
Failure modes and verification
| Failure mode | Verification action |
|---|---|
| Stale model or version reference | Compare the model name and ID with the official source before release. |
| Unstructured or incomplete output | Validate the response against the documented contract and a deterministic fixture. |
| Unverified factual claim | Keep the claim qualified or remove the claim when the official source does not support it. |
FAQ
Claude Managed Agents에 재사용 가능한 스킬을 어떻게 추가합니까?
Anthropic 사전 구축 스킬이나 사용자 지정 스킬을 에이전트의 skills 배열에 추가하거나, 규정된 구조의 저장소 스킬이 있는 GitHub 저장소를 세션에 마운트합니다. 지원되는 방식은 공식 스킬 문서에서 확인할 수 있습니다.
사용자가 스킬을 수동으로 활성화해야 합니까?
아닙니다. Claude Managed Agents는 현재 작업과 관련된 스킬을 자동으로 호출합니다. 저장소 스킬은 세션 시작 시 발견되며, 필요할 때 일치하는 파일을 읽습니다. 자세한 동작은 공식 문서에 설명되어 있습니다.
시작 시 자동 발견하려면 저장소 스킬을 어디에 배치해야 합니까?
마운트된 저장소 루트의 .claude/skills/<skill-name>/SKILL.md에 배치해야 합니다. .claude/skills 아래에 스킬별 디렉터리를 정확히 한 단계 사용해야 합니다. 다른 위치는 시작 시 에이전트에 알려지지 않지만, 에이전트가 나중에 해당 하위 트리를 읽으면 스킬이 확인될 수 있습니다. 공식 경로 규칙을 참고하십시오.
read 도구를 비활성화하면 어떻게 됩니까?
저장소 스킬 발견은 에이전트 도구 모음의 read 도구에 의존하므로, 시작 시 자동 발견 방식으로 해당 스킬을 불러올 수 없습니다. 이 제약은 공식 문서에 명시되어 있습니다.
스킬은 컨텍스트 창을 얼마나 사용합니까?
스킬을 추가할 때마다 지침과 메타데이터 때문에 세션 컨텍스트 창의 일부를 사용합니다. 공식 자료는 정확한 토큰 수를 제시하지 않으며, 사용할 수 있는 스킬이 많아지면 샌드박스 시작 시간도 늘어난다고 설명합니다.
한 세션에서 몇 개의 스킬을 지원합니까?
한 세션에서는 참여하는 모든 에이전트의 스킬을 중복 제거한 집합을 기준으로 최대 500개까지 지원합니다. 한도와 계산 방식은 공식 스킬 문서에 설명되어 있습니다.
저장소를 마운트하기 전에 스킬을 검토해야 하는 이유는 무엇입니까?
마운트된 저장소는 에이전트의 신뢰 경계에 포함되며, 저장소 스킬은 별도의 검토 단계 없이 세션 시작 시 로드됩니다. 특히 강력한 세션 도구가 활성화되어 있다면 .claude/skills를 검토하고 신뢰할 수 있는 저장소만 마운트해야 합니다. 자세한 내용은 공식 보안 지침을 참고하십시오.
Sources and freshness
- Official source
- Last verified: 2026-08-27
Extended guide
Claude Managed Agents에서는 워크플로, 업무 컨텍스트, 모범 사례를 재사용 가능한 파일 시스템 기반 스킬로 구성할 수 있습니다. 스킬은 에이전트 설정에 직접 첨부하거나 세션에 마운트된 GitHub 저장소에서 발견되도록 만들 수 있습니다.
근거와 범위
이 문서는 2026-08-27 기준 Claude Platform 공식 문서를 바탕으로 검증했습니다. 해당 페이지에서 확인할 수 있는 내용은 스킬 생성과 첨부, 저장소 스킬 발견, 자동 활성화, 컨텍스트 창 사용량, 샌드박스 시작 시간에 미치는 영향, 저장소 신뢰 경계입니다.
스킬 제공 방식과 활성화
| 제공 방식 | 구성 방법 | 활성화 방식 | 주요 제약 |
|---|---|---|---|
| Anthropic 사전 구축 스킬 | 에이전트의 skills 배열에 type: anthropic과 xlsx 같은 짧은 skill_id를 추가합니다. |
현재 작업과 관련 있을 때 에이전트가 스킬을 자동으로 호출합니다. | 모든 워크스페이스에 이미 제공되므로 별도로 업로드할 필요가 없습니다. |
| 워크스페이스 사용자 지정 스킬 | SKILL.md와 선택적인 보조 파일이 있는 디렉터리를 업로드한 뒤, 반환된 skill_* ID를 type: custom으로 첨부합니다. |
작업이 스킬의 용도와 일치할 때 에이전트가 자동으로 호출합니다. | 스킬 번들은 Files API를 거치지 않고 Skills API에 직접 업로드됩니다. |
| 저장소 스킬 | 세션의 github_repository 리소스로 GitHub 저장소를 마운트합니다. |
세션 시작 시 발견된 스킬의 메타데이터가 에이전트에 제공되고, 관련 작업이 생기면 해당 SKILL.md, 스크립트, 리소스를 읽습니다. |
시작 시 자동 발견하려면 read 도구가 필요하며, 클라우드 샌드박스에서만 지원됩니다. |
설정 절차
-
제공 방식을 선택합니다. 에이전트 구성에 스킬을 명시적으로 포함하려면 사전 구축 스킬이나 워크스페이스 사용자 지정 스킬을 첨부합니다. 지침과 보조 리소스를 코드와 함께 관리하려면 저장소 스킬을 사용합니다. 등록 방식은 다르지만, 두 방식 모두 작업 관련성을 기준으로 자동 활성화됩니다.
-
스킬을 준비합니다. 사용자 지정 스킬은
SKILL.md와 필요한 보조 파일로 구성된 디렉터리입니다. zip 아카이브 또는 개별 파일로 업로드할 수 있으며, 생성이 완료되면 에이전트 설정에서 사용할skill_*식별자가 반환됩니다. 저장소 자동 발견을 사용하려면 각 스킬을 저장소 루트의 정확한.claude/skills/<skill-name>/SKILL.md경로에 배치해야 합니다. -
에이전트에 첨부하거나 저장소를 마운트합니다. 첨부할 스킬은 에이전트를 생성할 때
skills배열에 추가합니다. 선택적인version필드에는 특정 버전이나latest를 지정할 수 있으며, 생략하면latest가 기본값입니다. 저장소 스킬은 별도로 업로드하거나 에이전트의skills배열에 추가할 필요가 없습니다.github_repository리소스가 포함된 세션에서 저장소를 마운트하면 사용할 수 있습니다. -
저장소 발견에 필요한 읽기 기능을 유지합니다. 사용자가 별도의 명령으로 스킬을 수동 활성화할 필요는 없습니다. 에이전트는 작업과 관련된 스킬을 자동으로 선택합니다. 저장소 스킬의 경우 기본으로 활성화된
read도구를 통해 세션 시작 시 스킬을 발견하고, 이후 필요한 파일을 읽습니다.read를 비활성화하면 이 자동 발견 방식으로 저장소 스킬을 불러올 수 없습니다. -
시작 시 발견되는 경로 규칙을 정확히 지킵니다.
.claude/skills/SKILL.md처럼 스킬별 하위 디렉터리가 없는 파일,.claude/skills/tools/code-review/SKILL.md처럼 두 단계 이상 중첩된 파일, 또는.claude밖의skills/code-review/SKILL.md는 세션 시작 시 에이전트에 알려지지 않습니다. 패키지 하위 디렉터리에 있는 별도의.claude/skills도 시작 시 자동 발견 대상이 아닙니다. 다만 에이전트가 나중에 해당 하위 트리의 파일을 읽으면 그곳의 스킬이 확인될 수 있습니다. -
컨텍스트와 시작 비용을 관리합니다. 스킬을 추가할 때마다 모델이 스킬의 사용 시점과 방법을 판단하는 데 필요한 지침과 메타데이터가 포함되므로, 적은 양이지만 세션 컨텍스트 창의 일부를 사용합니다. 공식 문서는 스킬별 정확한 토큰 수를 제시하지 않습니다. 한 세션에서는 참여하는 모든 에이전트의 스킬을 중복 제거한 집합을 기준으로 최대 500개까지 지원합니다. 사용할 수 있는 스킬이 많아지면 샌드박스 시작 시간도 늘어나므로, 각 에이전트에는 실제 작업에 필요한 스킬만 제공해야 합니다.
신뢰 경계와 API 유의 사항
마운트된 저장소는 에이전트의 신뢰 경계에 포함됩니다. 기여자의 변경, 병합된 외부 풀 리퀘스트 또는 손상된 의존성 경로를 통해 악의적인 스킬 지침이 저장소에 들어올 수 있습니다. 플랫폼은 별도의 검토 단계 없이 세션 시작 시 저장소 스킬을 불러오므로, 외부 기여를 받는 저장소를 마운트하기 전에 .claude/skills를 검토해야 합니다. bash나 web_fetch 같은 도구는 로드된 지침이 실제로 영향을 미칠 수 있는 범위를 넓힙니다.
Managed Agents API 요청에는 managed-agents-2026-04-01 베타 헤더가 필요합니다. 메모리 저장소 엔드포인트에는 대신 agent-memory-2026-07-22를 사용하며, SDK는 요청에 맞는 베타 헤더를 자동으로 선택합니다.
배포 전 체크리스트
- 시작 시 발견해야 하는 모든 저장소 스킬에
.claude/skills/<skill-name>/SKILL.md경로를 사용합니다. - 저장소 자동 발견이 필요하면
read도구를 활성화합니다. - 저장소 스킬을 신뢰 경계 안에서 실행되는 에이전트 지침으로 검토합니다.
- 컨텍스트 사용량과 시작 지연을 줄이기 위해 작업에 필요한 스킬만 제공합니다.
모델 제공 범위 안내: 공식 출처는 선택 가능한 모델 ID를 지정하지 않습니다.
근거와 최신성
근거 수준: 공식 문서 검증
AI-assisted editorial content; verify current product details against the linked official sources.
마지막 검증: