로드 중
로드 중

Skills

Skills는 Claude가 전문화된 작업의 수행 능력을 높이기 위해 동적으로 로드하는 지침, 스크립트, 리소스 폴더입니다. 모든 Skill의 핵심에는 SKILL.md 파일이 있습니다 — 한 번 업로드하면 모든 messages.create 호출에 연결할 수 있는 패키지화된 지침 모음입니다. 여러분은 Claude에게 여러분이 특정 작업을 수행하는 방식, 즉 상태 보고서 형식, 검토 체크리스트, 릴리스 노트를 가르치는 것입니다. Claude는 Skill을 읽고, 절차를 따르며, 여러분이 원하는 형태로 결과물을 만들어 냅니다.

Skills와 도구 비교

두 가지는 서로 다른 문제를 해결하기 때문에 차이를 명확히 아는 것이 중요합니다:

  • 도구는 Claude를 데이터와 액션에 연결합니다. "이 코드 섹션을 찾아봐", "이 이메일을 보내줘" — Claude가 도구를 호출하면 다른 무언가가 실행됩니다.
  • Skills는 Claude에게 절차를 가르칩니다. "이 템플릿에 따라 일일 상태 보고서를 생성해줘" — Claude가 읽고 따르는 플레이북이며, 때로는 번들로 제공된 스크립트를 직접 실행하는 것을 의미하기도 합니다.

간단히 기억하는 방법: 도구는 Claude가 무엇을 할 수 있는지에 관한 것이고, Skills는 어떻게 그것이 수행되기를 원하는지에 관한 것입니다.

도구와 Skills의 나란한 비교: 도구는 데이터에 연결하고, 액션을 취하고, 코드를 실행합니다 — Claude가 할 수 있는 것; Skills는 오직 지침만으로 절차를 가르치며, 코드가 실행되지 않습니다 — 여러분이 원하는 방식으로 수행되는 것

한 가지 더 알아둘 점: Skills는 시작 시 전체가 컨텍스트에 로드되지 않습니다. 처음에는 이름과 설명만 로드됩니다. 에이전트가 어떤 Skill이 관련 있다고 판단하면, 그때 전체 Skill을 컨텍스트에 로드합니다. 이를 통해 많은 Skills가 제공되는 경우에도 컨텍스트를 간결하게 유지할 수 있습니다.

Skill 업로드하기

Skills는 워크스페이스에 한 번 업로드된 후 ID로 참조됩니다. Claude Platform에서 직접 업로드하거나 프로그래밍 방식으로 업로드할 수 있습니다:

python
import anthropic
from anthropic.lib import files_from_dir

client = anthropic.Anthropic()

skill = client.skills.create(
    display_name="Status Report Generator",
    files=files_from_dir("status-report-skill"),  # folder containing SKILL.md
)

print(skill.id)  # reference this ID in future requests

이 예제에서는 상태 보고서 생성기를 만들고자 합니다. 좋은 상태 보고서를 만드는 모든 규칙 — 섹션, 어조, 요약 방법, 블로커 처리 방법 — 은 미리 패키지화된 Skill 안에 존재합니다. 활동 로그 자체는 요청 시점에 전달되는 단순한 문자열일 뿐입니다.

요청에 Skill 연결하기

Skills는 컨테이너 구성을 통해 요청에 연결됩니다 — 컨테이너 내부의 skills 배열이며, 각 항목은 skill_id와 version을 지정합니다. 다음은 상태 보고서 생성기의 전체 호출입니다:

python
response = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    container={
        "skills": [
            {
                "type": "custom",
                "skill_id": skill.id,
                "version": "latest",
            }
        ]
    },
    tools=[
        {
            "type": "code_execution_20250825",
            "name": "code_execution",
        }
    ],
    messages=[
        {
            "role": "user",
            "content": f"Generate the daily status report from this activity log:\n\n{activity_log}",
        }
    ],
)

몇 가지 짚어볼 점이 있습니다:

  • 베타 헤더 없이 표준 client.messages.create를 호출하고 있습니다. Skills는 Claude API에서 일반적으로 사용 가능하므로, skills-2025-10-02 베타 헤더는 더 이상 필요하지 않습니다. 여전히 이를 보내는 요청도 변함없이 계속 작동합니다.
  • container.skills는 Skill이 연결되는 위치입니다. 이는 목록이므로 하나의 호출에 여러 Skills를 중첩해서 쌓을 수 있습니다.
  • 코드 실행도 여기서 활성화되어 있습니다. 이는 필수입니다: API에서 Skills는 코드 실행 도구의 컨테이너 내부에서 실행되며, 이것이 Skill 절차가 터미널에서 스크립트를 실행하는 것과 같은 실제 작업을 수행할 수 있게 해줍니다.

실행하기

결과물은 Skill이 지정한 방식 그대로 형식이 맞춰진 상태 보고서입니다. 섹션, 어조, 블로커 처리 — 이 모두가 여러분이 업로드한 SKILL.md 파일에서 비롯됩니다. 사용자 프롬프트는 한 줄이며, 절차는 Skill 안에 존재합니다.

Done과 Blockers 섹션, 그리고 Skill에 의해 형식이 맞춰진 요약이 포함된 생성된 일일 상태 보고서의 터미널 출력

프로덕션 애플리케이션에서는 이러한 방식으로 팀이 전체 기능에 걸쳐 결과물을 표준화합니다. 이 일일 상태 보고서 엔드포인트를 사용하면, 모든 PM이 누군가 프롬프트에 템플릿을 복사해 붙여넣지 않아도 동일한 구조, 동일한 어조, 동일한 섹션을 동일한 순서로 얻게 됩니다.

각 프로젝트의 활동 로그에 Skill이 뒷받침하는 원클릭 Generate report 버튼이 있는 Daily reports 페이지를 보여주는 프로젝트 관리 앱

요약

  • Skills는 여러분의 절차를 패키지화합니다. SKILL.md 파일(그리고 스크립트와 리소스)은 원하는 방식으로 작업이 수행되도록 Claude에게 가르칩니다.
  • 도구 대 Skills: 도구는 Claude가 무엇을 할 수 있는지에 관한 것이고, Skills는 여러분이 원하는 방식으로 수행되는 것에 관한 것입니다.
  • Skills는 점진적으로 로드됩니다. 시작 시에는 이름과 설명만 로드되며, 에이전트가 사용하기로 결정하면 전체 Skill이 컨텍스트에 로드됩니다.
  • client.skills.create로 한 번 업로드한 다음, 어떤 messages.create 호출에서든 container.skills로 연결합니다 — 목록이므로 여러 Skills를 중첩해서 쌓을 수 있습니다.
  • Skill의 절차가 실제 작업을 수행해야 할 때는 코드 실행과 짝을 이루세요.
  • 어떻게가 무엇만큼 중요할 때는 Skill을 활용하세요.