"Skills" 태그로 연결된 2개 게시물개의 게시물이 있습니다.

에이전트에게 "이 PDF 읽고 저 웹 포털에 대신 입력해 줘"를 시키는 데 필요한 조각이 셋인데, 그 셋이 같은 날 정식 출시됐습니다. 2026년 8월 20일입니다.

Anthropic이 computer use, Skills API, Files API 세 가지의 정식 출시를 발표했습니다. 각각 따로 보면 기능 추가인데, 셋을 붙여 놓으면 성격이 달라집니다.

세 조각이 각각 맡는 일​

발표문이 든 예시가 구성을 잘 보여 줍니다. 보험 청구 처리 에이전트입니다. Files API에서 접수 문서를 읽고, 팀의 접수 절차를 담은 skill을 따라, browser use tool로 보험사 웹 포털에서 제출을 마치고, 확인서를 다시 파일로 저장합니다.

역할 분담이 사람의 업무 구조와 닮았습니다. 문서, 절차서, 그리고 소프트웨어를 조작하는 손입니다. 지금까지는 이 셋 중 손 쪽이 가장 불안했습니다.

computer use: 도구 식별자가 toolset으로 바뀌었다​

여기가 실무에서 가장 먼저 걸리는 부분입니다. 도구 타입 문자열이 바뀌었습니다.

{
  "type": "computer_toolset_20260801",
  "name": "computer"
}

Claude API에서는 beta 헤더가 필요하지 않습니다. 이전 버전인 computer_20251124는 anthropic-beta: computer-20251124-api 헤더가 필요했고, 지금은 구형 모델용으로 남았습니다.

지원 모델이 갈립니다. computer_toolset_20260801은 claude-opus-5, claude-sonnet-5, claude-opus-4-8, claude-fable-5, claude-mythos-5에서 동작합니다. Opus 4.7과 4.6, Sonnet 4.6, Opus 4.5는 이전 computer_20251124를 써야 합니다.

파라미터에서 사라진 게 하나 있습니다. 화면 너비와 높이입니다. 이전 버전은 display_width_px 같은 값을 받았는데, computer_toolset_20260801은 받지 않습니다. 좌표를 돌려주는 스크린샷에서 직접 읽습니다. 기존 코드를 옮길 때 이 두 파라미터를 그대로 두면 거부됩니다.

이름이 tool에서 toolset으로 바뀐 이유는 안에 든 것이 하나가 아니기 때문입니다. member tool이 17개입니다.

zoom이 눈에 띕니다. 지정한 영역을 원본 해상도로 다시 캡처합니다. 전체 화면 스크린샷은 축소되어 작은 글자를 놓치기 쉬운데, 그 문제를 영역 재촬영으로 풉니다. hold_key와 wait는 최대 300초까지 받습니다.

turn당 한 동작에서 여러 동작으로​

베타에서 정식 출시로 오면서 가장 크게 바뀐 지점입니다. 이전에는 모델 호출 한 번에 동작 하나였습니다. 지금은 한 응답에 여러 tool_use 블록을 담습니다.

로그인 폼을 채우는 작업을 생각해 보면 차이가 큽니다. 아이디 칸 클릭, 입력, 비밀번호 칸 클릭, 입력, 로그인 클릭이면 모델 호출 5회였던 것이 1회가 됩니다. 지연과 비용이 함께 줄어듭니다.

대신 실패 처리 규칙을 알아야 합니다. 동작은 순서대로 실행되고 첫 실패에서 멈춥니다. 실행되지 않은 나머지 동작에는 이런 결과를 돌려줘야 합니다.

{
  "type": "tool_result",
  "tool_use_id": "toolu_01...",
  "toolset_name": "computer",
  "is_error": true,
  "content": "Not executed: an earlier computer action in this turn failed."
}

toolset_name 필드가 모든 결과에 들어가야 합니다. 값은 "computer"입니다. 예전 방식으로 tool_use_id와 content만 채우면 통과하지 않습니다.

한 동작씩 진행하고 싶으면 병렬 도구 사용을 끕니다.

{
  "tool_choice": { "type": "tool", "disable_parallel_tool_use": true }
}

화면 상태를 매 단계 확인해야 하는 작업이라면 이쪽이 안전합니다. 화면이 예상과 달라졌는데 나머지 클릭이 그대로 나가면 엉뚱한 곳을 누릅니다.

browser use tool은 여기서 한 겹 더 갑니다. 픽셀 좌표만 쓰는 것보다 웹 요소를 안정적으로 겨냥하도록 페이지 구조 분석을 더했습니다. 웹 애플리케이션만 다룰 거라면 이쪽이 맞습니다.

의료 쪽 이야기도 붙었습니다. computer use가 BAA 아래 HIPAA 규제 대상 워크로드에 쓸 수 있게 됐습니다.

Skills API: skill이 저장 객체가 됐다​

Claude Code의 Skills를 다룬 적이 있는데, 그때는 로컬 디렉터리에 마크다운 파일을 두는 구조였습니다. 이제 API 층으로 올라와 저장되고 버전이 붙는 객체가 됐습니다.

skill은 지시문과 스크립트, 템플릿이 든 폴더입니다. 작업이 필요할 때만 Claude가 읽어 들이고, Claude의 코드 실행 sandbox 안에서 돕니다. 직접 호스팅할 서버가 없습니다.

엔드포인트 구성입니다.

POST   /v1/skills                                    # 생성 (multipart/form-data)
GET    /v1/skills                                    # 목록
GET    /v1/skills/{skill_id}                         # 조회
DELETE /v1/skills/{skill_id}                         # 삭제
POST   /v1/skills/{skill_id}/versions                # 새 버전 업로드
GET    /v1/skills/{skill_id}/versions                # 버전 목록
GET    /v1/skills/{skill_id}/versions/{version}      # 버전 조회
DELETE /v1/skills/{skill_id}/versions/{version}      # 버전 삭제

버전 참조에 latest 리터럴을 쓸 수 있습니다. latest_version_id 필드가 가리키는 곳으로 해석됩니다. 다만 skills-2025-10-02 beta 헤더를 붙인 요청은 버전을 Unix epoch 타임스탬프로 주소지정합니다. 예시가 "1759178010641129" 형태입니다. beta 경로와 정식 경로에서 버전 식별 방식이 다르니 여기서 한 번 헤맬 수 있습니다.

name 필드의 성격이 중요합니다. 첫 업로드의 SKILL.md frontmatter에 있는 name(없으면 그 폴더 이름)에서 kebab-case slug로 정해지고, 이후 바뀌지 않습니다. 나중 업로드도 같은 값으로 해석돼야 합니다. 이 slug가 마운트된 파일의 최상위 디렉터리 이름이 되고, 내려받을 때 아카이브 파일명이 됩니다.

skill의 출처는 네 종류로 구분됩니다.

요청에 붙이는 방법에서 혼동이 잘 생깁니다. Skills를 쓰려면 세 가지를 함께 넣습니다.

client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    container={"skills": [{"skill_id": "skill_01...", "version": "latest"}]},
    tools=[{"type": "code_execution_20260521", "name": "code_execution"}],
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    messages=[...],
)

container에 skill을 얹고, 코드 실행 도구를 선언하고, beta 두 개를 붙입니다. skill이 sandbox 안에서 도니까 코드 실행 도구가 함께 필요합니다.

Managed Agents와 헷갈리지 않기​

여기가 정말 자주 어긋나는 지점입니다. Skills는 Managed Agents가 아닙니다.

Managed Agents는 별개 표면입니다. POST /v1/agents로 에이전트 설정을 저장해 두고, 세션을 만들어 실행합니다. 세션마다 컨테이너가 workspace로 할당되고 에이전트 루프 자체를 Anthropic이 돌립니다. beta 헤더도 다릅니다. managed-agents-2026-04-01입니다.

반면 Skills로 문서를 만들게 하려면 위처럼 client.beta.messages.create에 container와 코드 실행 도구를 얹으면 끝입니다. client.beta.agents나 세션 API를 쓰는 게 아닙니다. Skills가 Managed Agents 안에서도 쓰이기 때문에 문서를 훑다 보면 두 경로가 섞여 보입니다.

Files API: 한 번 올리고 ID로 부른다​

성격은 단순합니다. PDF나 스프레드시트를 한 번 올려 두고, 이후 요청에서는 다시 보내지 않고 ID로 참조합니다.

POST /v1/files

beta 헤더는 files-api-2025-04-14입니다. 업로드할 때와, 그 파일을 참조하는 messages.create 양쪽에 모두 붙여야 합니다. 한쪽만 붙이면 실패합니다.

참조할 때는 content block 타입이 파일의 MIME 타입과 맞아야 합니다.

{
  "type": "document",
  "source": { "type": "file", "file_id": "file_01..." }
}

PDF와 텍스트는 document, 이미지는 image입니다.

정식 출시로 오면서 늘어난 것이 셋입니다. 파일 자동 만료가 들어왔고, rate limit이 5배로 올랐고, 조직당 저장 용량이 1TB가 됐습니다. 자동 만료는 편의 기능처럼 보이지만 실무에서는 정리 부담을 덜어 줍니다. 업로드해 둔 파일을 지우는 코드를 따로 관리하지 않아도 됩니다.

base64로 PDF를 매번 실어 보내는 방식과 비교하면 차이가 분명합니다. base64 경로는 요청 32MB, 600페이지 제한이 걸립니다. 같은 문서를 여러 번 물어볼 거라면 매 요청마다 그 크기를 다시 전송하는 셈입니다.

어디서 쓸 수 있나​

플랫폼마다 갈립니다. 세 기능 모두 Claude 플랫폼에서 쓸 수 있습니다. Skills API와 Files API는 Microsoft Foundry에서도 접근됩니다. computer tool과 browser tool은 Google Cloud Vertex AI에 들어올 예정입니다.

computer use는 플랫폼별로 버전이 다릅니다. computer_toolset_20260801 전체 지원은 Claude API고, Claude Platform on AWS와 Bedrock, Google Cloud, Foundry는 이전 버전이 beta로 올라가 있습니다. 특정 클라우드에 묶여 있다면 도구 식별자와 모델을 같이 확인해야 합니다.

무엇이 실제로 달라지나​

세 기능의 정식 출시를 하나로 묶으면, 에이전트가 API를 가진 시스템만 다루던 단계에서 벗어난다는 뜻입니다. 화면만 있는 소프트웨어, 예를 들어 사내 레거시 웹 콘솔이나 외부 기관 포털은 자동화 대상이 아니었습니다. 사람이 대신 클릭했습니다.

다만 ClaudeBleed 사례를 다루면서 봤듯이, 브라우저를 조작하는 권한은 그 자체로 공격 표면입니다. 화면을 보고 클릭하는 에이전트에게는 세션 쿠키가 붙은 브라우저가 그대로 열려 있습니다. 웹 포털에 자동 입력을 맡기기 전에, 그 에이전트가 어떤 페이지까지 갈 수 있는지 경계를 먼저 정해 두는 편이 좋습니다.

turn당 여러 동작이 묶이는 변화는 그래서 양면입니다. 비용과 지연이 줄지만, 잘못된 화면 판단 하나가 다섯 번의 클릭으로 번집니다. 되돌리기 어려운 작업에서는 disable_parallel_tool_use를 켜는 쪽이 낫다고 봅니다.

참고​

• computer use, Skills API, Files API 정식 출시 발표 (2026-08-20)
• computer use tool 공식 문서
• Skills API 레퍼런스

commands가 사라졌다?​

Claude Code를 쓰면서 .claude/commands/ 디렉토리에 커스텀 명령어를 만들어 쓰던 분들이 있을 거예요. /deploy, /review, /commit 같은 것들이에요.

그런데 어느 날 문서를 보니 "Skills"라는 게 나옵니다. commands는 어디로 간 것인지 의문이 듭니다.

결론부터 말하면, commands가 skills로 통합됐습니다. 정확히는 v2.1.3 (2026년 1월)부터입니다.

"Merged slash commands and skills, simplifying the mental model with no change in behavior" — Claude Code v2.1.3 Changelog

타임라인​

공식 deprecation 일정은 아직 없습니다. 하지만 방향은 명확합니다.

commands와 skills의 차이​

기존: commands​

.claude/commands/deploy.md

마크다운 파일 하나. 프롬프트를 적어두면 /deploy로 호출할 수 있었습니다. 단순하고 직관적이었습니다.

현재: skills​

.claude/skills/deploy/
├── SKILL.md           # 주요 지침 (필수)
├── template.md        # Claude가 채울 템플릿
├── examples/
│   └── sample.md      # 예제 출력
└── scripts/
    └── validate.sh    # Claude가 실행할 스크립트

디렉토리 구조입니다. SKILL.md가 진입점이고, 지원 파일을 함께 둘 수 있습니다.

핵심 차이: frontmatter​

Skills의 가장 큰 차이는 YAML frontmatter입니다.

---
name: deploy
description: 프로덕션 배포
disable-model-invocation: true
allowed-tools: Bash(ssh *) Bash(rsync *)
model: claude-opus-4-7
context: fork
---

배포 순서:
1. 테스트 실행
2. 빌드
3. 서버에 전송

frontmatter로 할 수 있는 것들:

commands에서는 이런 제어가 전부 불가능했습니다.

자동 호출이 핵심​

commands는 /명령어로 직접 호출해야만 동작했습니다. skills는 다릅니다.

description에 적절한 키워드를 넣어두면, Claude가 대화 맥락에서 관련이 있다고 판단할 때 자동으로 로드합니다. 예를 들면 다음과 같습니다.

---
name: api-conventions
description: API design patterns for this codebase
---

API 엔드포인트 작성 시:
- RESTful 명명 규칙 사용
- 일관된 에러 포맷 반환
- 요청 유효성 검사 포함

이 skill은 /api-conventions으로 호출할 수도 있고, Claude가 API 코드를 작성할 때 알아서 참조하기도 합니다.

반대로 배포처럼 사람이 타이밍을 통제해야 하는 작업은 disable-model-invocation: true를 설정해서 자동 호출을 막습니다.

마이그레이션은 어떻게​

안 해도 된다​

기존 .claude/commands/ 파일은 그대로 동작합니다. 이름이 같으면 skill이 우선할 뿐입니다.

하고 싶다면​

1. .claude/skills/<이름>/ 디렉토리 생성
2. 기존 .md 파일 내용을 SKILL.md로 이동
3. 필요하면 frontmatter 추가
4. 기존 commands 파일 삭제

예시:

Before — .claude/commands/deploy.md

프로덕션에 배포해줘.
1. 테스트 실행
2. 빌드
3. rsync로 서버에 전송

After — .claude/skills/deploy/SKILL.md

---
name: deploy
description: 프로덕션 빌드 및 배포
disable-model-invocation: true
---

프로덕션에 배포해줘.
1. 테스트 실행
2. 빌드
3. rsync로 서버에 전송

내용은 같고, frontmatter만 추가됐습니다.

번들 Skills​

Claude Code가 기본으로 제공하는 skills도 있습니다.

이것들도 전부 skill입니다. 프롬프트 기반으로 Claude가 도구를 조율해서 실행합니다.

Skills 저장 위치​

skill을 어디에 저장하느냐에 따라 적용 범위가 달라집니다.

제가 자주 쓰는 건 Personal에, 프로젝트 팀원과 공유할 건 Project에 넣으면 돼요.

커뮤니티 반응​

병합이 발표됐을 때 커뮤니티에서 혼란이 있었습니다. GitHub에 "Merged slash commands and skills"가 뭔 말이냐는 이슈가 올라왔고, "no change in behavior"면 왜 changelog에 넣느냐는 비판도 있었습니다.

실제로 사용자 입장에서는 기존 commands가 그대로 동작하기 때문에 체감할 수 있는 변화가 거의 없었습니다. 하지만 앞으로 새로 만들 때는 skills로 만드는 편이 맞습니다. frontmatter의 자동 호출 제어, 도구 제한, subagent 실행 같은 기능은 commands에서는 쓸 수 없습니다.

정리​

기존 commands를 당장 마이그레이션할 필요는 없어요. 하지만 새로 만들 건 skills로, 기존 것도 기능이 필요하면 skills로 전환하는 게 좋아요.

참고 자료​

• Extend Claude with skills (Claude Code Docs)
• Claude Code v2.1.3 Changelog (X)
• Changelog entry confusion (GitHub Issue #17288)
• Track full deprecation of commands (GitHub Issue #37447)
• Slash Commands Are Dead. Long Live Skills. (Medium)
• Claude Code Skills vs Slash Commands 2026 (YingTu)