스킬

"Skills"(스킬)는 에이전트에 도메인별 전문 지식을 제공하는 재사용 가능한 파일시스템 기반 리소스입니다. 범용 에이전트를 전문가로 바꿔 주는 워크플로, 컨텍스트, 모범 사례가 여기에 해당합니다. 추가하는 각 스킬은 모델이 해당 스킬을 사용하는 데 도움이 되는 지침과 메타데이터를 추가하므로 세션의 "context window"(컨텍스트 윈도우)에 약간의 비용을 발생시킵니다. 자세한 내용은 Agent Skills 개요에서 알아보세요.

스킬은 두 가지 방법으로 에이전트에 전달됩니다. 에이전트의 skills 배열을 통해 연결하거나, 세션에 마운트된 GitHub 리포지토리에서 로드할 수 있습니다. 연결되는 스킬에는 두 가지 유형이 있습니다. 모든 스킬은 동일한 방식으로 작동합니다. 즉, 작업과 관련이 있을 때 에이전트가 자동으로 호출합니다.

• 사전 구축된 Anthropic 스킬: PowerPoint, Excel, Word, PDF 처리(pptx, xlsx, docx, pdf)와 같은 일반적인 문서 작업.
• 커스텀 스킬: 직접 작성하여 워크스페이스에 업로드하는 스킬.

커스텀 스킬을 작성하는 방법을 알아보려면 Agent Skills 및 스킬 작성 모범 사례를 참조하세요. 커스텀 스킬을 워크스페이스에 업로드하려면 커스텀 스킬 만들기를 참조하세요.



커스텀 스킬 만들기

커스텀 스킬은 SKILL.md 파일과 지원 파일을 포함하는 디렉터리로, zip 아카이브 또는 개별 파일로 워크스페이스에 업로드됩니다. 스킬을 생성하면 에이전트에 연결할 때 참조하는 skill_* ID가 반환됩니다. Anthropic 사전 구축 스킬은 모든 워크스페이스에서 이미 사용할 수 있으며 이 단계가 필요하지 않습니다. 사전 구축 스킬만 사용하려면 에이전트에 스킬 연결로 건너뛰세요.

Skills API에는 베타 헤더가 필요하지 않습니다. 여전히 anthropic-beta: skills-2025-10-02를 전송하는 요청도 계속 작동하며 이전 응답 필드를 반환합니다.

이 예제에서는 선택 사항인 display_name 필드를 생략하므로, 스킬의 표시 이름은 SKILL.md의 name 필드에서 파생됩니다. 명시적인 display_name은 최대 255자까지 가능하며 워크스페이스 내에서 고유할 필요는 없습니다.

ant skills create \
  --file example_skill.zip

커스텀 스킬을 나열, 조회, 삭제하고 버전을 관리하려면 커스텀 스킬 관리를 참조하세요. 전체 요청 및 응답 스키마는 Create Skill API 레퍼런스를 참조하세요. 스킬 번들은 Files API를 통하지 않고 Skills API에 직접 업로드됩니다.



에이전트에 스킬 연결

에이전트를 생성할 때 스킬을 연결합니다. 각 세션은 최대 500개의 스킬을 지원하며, 이는 세션 내 모든 에이전트에 걸쳐 중복을 제거한 집합으로 계산됩니다(멀티에이전트 오케스트레이션 참조).

skills 배열의 각 항목은 다음 필드를 사용합니다.

ant beta:agents create < agent.yaml

name: Financial Analyst
model: claude-opus-5
system: You are a financial analysis agent.
skills:
  - type: anthropic
    skill_id: xlsx
  - type: custom
    skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
    version: latest



GitHub 리포지토리에서 스킬 로드

스킬은 코드베이스에 둘 수도 있습니다. 세션이 github_repository 리소스를 통해 리포지토리를 마운트하면, 세션 시작 시 리포지토리 루트의 .claude/skills 디렉터리가 스캔되고 그곳에서 발견된 각 스킬을 에이전트가 사용할 수 있게 됩니다. 업로드도, 에이전트의 skills 배열 항목도 필요하지 않습니다. 에이전트는 발견된 각 스킬의 이름, 설명, 샌드박스 내 경로를 확인하고, 작업이 일치할 때 스킬에 포함된 스크립트와 리소스를 비롯하여 해당 스킬의 SKILL.md를 읽습니다. 검색은 에이전트 도구 세트의 read 도구에 의존하며, 이 도구는 기본적으로 활성화되어 있습니다. read가 비활성화된 에이전트는 리포지토리 스킬을 로드하지 않습니다.

검색은 리포지토리 루트에서 한 디렉터리 수준 깊이인 정확히 .claude/skills/<skill-name>/SKILL.md 위치에서 스킬을 찾습니다.

• your-repo/
  • .claude/
    • skills/
      • code-review/
        • SKILL.md
      • release-process/
        • SKILL.md
        • scripts/
          • run_checks.sh
  • src/

이 레이아웃과 일치하지 않는 위치는 세션 시작 시 검색되지 않습니다.

• .claude/skills/SKILL.md: 감싸는 스킬 디렉터리가 없는 SKILL.md
• .claude/skills/tools/code-review/SKILL.md: 한 디렉터리 수준보다 깊게 중첩됨
• skills/code-review/SKILL.md: .claude 외부에 있는 skills 디렉터리

패키지 하위 디렉터리 내부와 같이 리포지토리의 다른 위치에 있는 .claude/skills 디렉터리는 세션 시작 시 알려지지 않습니다. 이러한 스킬은 에이전트가 해당 하위 트리 아래의 파일을 읽을 때 여전히 드러날 수 있습니다.

리포지토리 스킬은 업로드하는 커스텀 스킬과 동일한 SKILL.md 형식을 사용합니다. 형식 및 작성 지침은 Agent Skills 및 스킬 작성 모범 사례를 참조하세요.

리포지토리에서 스킬을 로드하려면 해당 리포지토리를 마운트하는 세션을 생성하세요. 이는 GitHub 액세스에 표시된 것과 동일한 요청입니다. mount_path는 선택 사항이며 기본값은 /workspace/<repo-name>입니다.

SESSION_ID=$(ant beta:sessions create \
  --agent "$AGENT_ID" \
  --environment-id "$ENVIRONMENT_ID" \
  --transform id --raw-output <<'EOF'
resources:
  - type: github_repository
    url: https://github.com/org/repo
    mount_path: /workspace/repo
    authorization_token: ghp_your_github_token
EOF
)

비공개 리포지토리의 경우 리소스의 authorization_token이 해당 리포지토리에 대한 액세스 권한을 가지고 있어야 합니다. 이는 모든 리포지토리 마운트에 사용되는 것과 동일한 개인 액세스 토큰 흐름입니다. GitHub 액세스를 참조하세요.

검색된 스킬은 리포지토리의 체크아웃된 상태를 따릅니다. 리소스가 checkout 브랜치 또는 커밋을 설정한 경우 해당 상태를, 그렇지 않으면 리포지토리의 기본 브랜치를 따릅니다. 스캔은 세션이 시작될 때 한 번 실행됩니다. 세션 도중에 푸시된 커밋은 반영되지 않습니다. 업데이트된 스킬을 로드하려면 새 세션을 시작하세요.

리포지토리 스킬은 에이전트의 skills 배열을 통해 연결된 스킬과 함께 작동합니다. 리포지토리 스킬이 연결된 스킬 또는 다른 마운트된 리포지토리의 스킬과 이름이 같은 경우 둘 다 사용할 수 있으며, 각각 고유한 경로와 함께 알려집니다.



다음 단계