Skills

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

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

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

커스텀 skills를 작성하는 방법은 Agent Skills 및 Skill 작성 모범 사례를 참조하세요. 워크스페이스에 커스텀 skill을 업로드하려면 커스텀 skill 생성을 참조하세요.



커스텀 skill 생성

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

Skills API는 베타 헤더가 필요하지 않습니다. cURL 예제는 여전히 anthropic-beta: skills-2025-10-02를 전송하며, CLI 및 SDK beta 명령은 이를 자동으로 추가합니다. 이 헤더를 포함하는 요청은 변경 없이 계속 작동합니다.

이 예제들은 선택적 display_title 필드를 생략하므로 skill의 제목은 SKILL.md에서 파생됩니다. 명시적으로 전달된 display_title은 워크스페이스의 커스텀 skills 중에서 고유해야 합니다.

ant beta:skills create \
  --file example_skill.zip

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



에이전트에 skills 연결

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

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 리포지토리에서 skills 로드

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

검색은 리포지토리 루트에서 정확히 한 단계 깊이의 .claude/skills/<skill-name>/SKILL.md 위치에서 skills를 찾습니다.

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

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

• .claude/skills/SKILL.md: skill 디렉터리 없이 존재하는 SKILL.md
• .claude/skills/tools/code-review/SKILL.md: 한 단계 이상 깊이로 중첩됨
• skills/code-review/SKILL.md: .claude 외부의 skills 디렉터리

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

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

리포지토리에서 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 액세스를 참조하세요.

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

리포지토리 skills는 에이전트의 skills 배열을 통해 연결된 skills와 함께 작동합니다. 리포지토리 skill이 연결된 skill 또는 다른 마운트된 리포지토리의 skill과 이름을 공유하는 경우, 둘 다 사용 가능하며 각각 고유한 경로와 함께 알려집니다.



다음 단계