스킬

스킬 vs. 도구

이 둘의 차이를 명확히 해두는 것이 좋습니다. 서로 다른 문제를 해결하기 때문입니다:

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

기억하기 쉬운 방법: 도구는 Claude가 무엇을 할 수 있는지에 관한 것이고, 스킬은 여러분이 어떻게 그것이 이루어지길 원하는지에 관한 것입니다.



한 가지 더 알아둘 점: 스킬은 시작 시 컨텍스트에 전체가 로드되지 않습니다. 처음에는 이름과 설명만 로드됩니다. 에이전트가 어떤 스킬이 관련 있다고 판단하면, 그때 전체 스킬을 컨텍스트에 로드합니다. 이를 통해 많은 스킬이 사용 가능한 상황에서도 컨텍스트를 가볍게 유지할 수 있습니다.

스킬 업로드하기

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

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

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

요청에 스킬 첨부하기

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

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를 호출하고 있습니다. 스킬은 Claude API에서 정식 출시되었으므로 skills-2025-10-02 베타 헤더는 더 이상 필요하지 않습니다. 여전히 이를 보내는 요청도 변경 없이 계속 작동합니다.
• container.skills는 스킬이 첨부되는 위치입니다. 이는 리스트이므로 하나의 호출에 여러 스킬을 겹쳐서 적용할 수 있습니다.
• 여기서는 코드 실행도 켜져 있습니다. 이는 필수입니다: API에서 스킬은 코드 실행 도구의 컨테이너 내부에서 실행되며, 이것이 스킬 절차가 터미널에서 스크립트를 실행하는 것과 같은 실제 작업을 할 수 있게 해줍니다.

실행하기

출력 결과는 스킬이 지정한 형식 그대로 포맷된 상태 보고서입니다. 섹션, 어조, 블로커 처리 — 이 모든 것이 여러분이 업로드한 SKILL.md 파일에서 비롯됩니다. 사용자 프롬프트는 한 줄이고, 절차는 스킬 안에 들어 있습니다.



프로덕션 앱에서는 이런 방식으로 팀이 전체 기능에 걸쳐 출력을 표준화합니다. 이 일일 상태 보고서 엔드포인트를 사용하면, 모든 PM이 동일한 구조, 동일한 어조, 동일한 섹션을 동일한 순서로 얻게 됩니다 — 누구도 프롬프트에 템플릿을 복사-붙여넣기 할 필요 없이 말이죠.



요약

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