Room에서 요청하는 Clawpod Capability Registry 사용법

Clawpod Capability란 무엇인가요?

Clawpod Capability는 에이전트가 특정 종류의 일을 안정적으로 수행하도록, 지침과 통제된 실행 도구를 재사용할 수 있게 미리 검증해 둔 조합입니다. 매번 방법을 새로 정하는 대신, 어떤 요청에 맞는지와 어디까지 할 수 있는지가 정리된 능력을 골라 사용합니다.

Capability에는 다음 두 요소 중 하나 또는 둘 다가 들어갈 수 있습니다.

Skill은 에이전트가 상황을 판단하고 올바른 절차를 따르게 하는 업무 지침입니다.
CLI Harness는 에이전트가 소프트웨어를 정해진 범위 안에서 일관되게 조작하게 하는 실행 도구입니다.

예를 들어 여러 출처를 대조해 인용 가능한 조사 결과를 만드는 능력은 판단 절차가 중심일 수 있습니다. 기술 블로그의 원고를 점검하고 발행 전 품질을 확인하는 능력은 절차와 실행 도구를 함께 쓸 수 있습니다. 외부 저장소에서 파일을 찾아 안전하게 가져오는 능력은 통제된 소프트웨어 조작이 중심일 수 있습니다. 사용자는 이 구성을 직접 다룰 필요 없이 원하는 결과를 Room에서 말하면 됩니다.

Capability Registry는 무엇을 하나요?

Capability Registry는 에이전트가 이런 Capability를 찾고, 설치하고, 업데이트할 때 먼저 확인하는 기준 목록입니다. 에이전트는 현재 설치된 능력으로 요청을 처리할 수 있는지 살핀 뒤, 부족하면 Registry에서 요청 범위에 맞는 후보를 찾습니다.

flowchart TD
  A[원하는 일을 Room에서 요청] --> B[설치된 Capability 확인]
  B --> C{알맞은 능력이 있나요?}
  C -->|있음| F[Capability로 작업]
  C -->|없음| D[Registry에서 후보 찾기]
  D --> E[선택 이유 설명 후 설치와 검증]
  E --> F
  F --> G[결과와 근거 보고]

언제 Registry 검색을 부탁해야 하나요?

다음과 같은 상황에서 유용합니다.

에이전트가 요청을 처리할 적합한 능력이 없다고 알려 줄 때
조사, 발행, 외부 서비스 연동처럼 반복 가능한 전문 절차가 필요할 때
비슷한 Capability가 여러 개라서 범위와 차이를 비교하고 싶을 때
새 능력을 만들기 전에 이미 검증된 대안이 있는지 확인하고 싶을 때
설치한 능력의 새 버전이나 복구 가능한 이전 버전을 확인하고 싶을 때

가장 간단한 시작 문장은 이것입니다.

이 일을 처리할 수 있는 Capability가 현재 설치되어 있는지 먼저 확인해 주세요. 없다면 canonical Registry에서 찾아서 후보와 선택 이유를 설명해 주세요.

찾기와 비교를 요청하는 프롬프트

제품명이나 내부 이름을 몰라도 됩니다. 이루고 싶은 결과와 중요한 조건을 말하면 에이전트가 설치된 목록과 Registry의 설명을 대조합니다.

여러 출처를 교차 확인하고 인용 가능한 조사 결과를 만드는 Capability를 찾아 주세요. 현재 설치된 능력을 먼저 확인하고, 없다면 Registry 검색 결과 중 가장 적합한 후보 세 개와 차이를 알려 주세요.

에이전트의 답에는 최소한 다음 내용이 있어야 합니다.

이미 설치되어 있는지, Registry에서 새로 찾았는지
후보 이름과 정확한 버전
어떤 요청에서 쓰는 능력인지
지금 요청에서 할 수 있는 일과 할 수 없는 일
비슷한 후보 대신 이것을 권하는 이유
추가 계정, 권한 또는 별도 준비가 필요한지

첫 검색 결과가 아니라 요청과 경계가 가장 잘 맞는 후보를 선택했는지 확인하는 것이 핵심입니다.

설치 전 검토를 요청하는 프롬프트

설치해도 되는지 판단하려면 호환성과 안전 조건을 먼저 확인해야 합니다.

이 Capability를 설치하기 전에 현재 Clawpod 환경과 호환되는지, 함께 필요한 연결 Capability가 있는지, 어떤 권한과 외부 서비스가 필요한지 확인해 주세요. 설치될 버전과 검증 방법도 먼저 설명해 주세요.

에이전트는 설치 전에 선택한 패키지의 유형과 버전, 호환 범위, 연결된 능력, 안전 수준, 필요한 준비를 설명해야 합니다. 이름이 같아도 서로 연결된 Skill과 Harness가 함께 제공될 수 있으므로, 일부만 준비된 상태를 완료로 보고해서는 안 됩니다.

설치와 검증을 요청하는 프롬프트

검토 결과가 적합하다면 설치와 검증을 한 번에 맡길 수 있습니다.

권장한 Capability를 관리되는 환경에 설치하고 무결성과 연결 상태를 검증해 주세요. 영향이 제한된 확인 작업까지 실행한 뒤, 설치된 버전과 검증 결과를 보고해 주세요.

완료 보고에는 다음 증거가 포함되어야 합니다.

실제 설치된 Capability와 버전
연결된 구성 요소가 모두 준비되었는지
Registry가 선언한 내용과 설치 결과가 일치하는지
현재 에이전트가 이 능력을 선택할 수 있는 상태인지
제한된 확인 작업의 결과
아직 충족되지 않은 계정 연결이나 운영 조건

“설치됨”과 “실제 업무에 사용할 준비가 됨”은 다를 수 있습니다. 외부 서비스 연결이 남아 있다면 에이전트가 둘을 구분해 알려 줘야 합니다.

설치한 Capability로 일을 맡기는 프롬프트

준비가 끝난 뒤에는 Capability 이름을 외울 필요 없이 원하는 결과를 요청하면 됩니다.

이 문서의 핵심 주장 세 가지를 공식 출처와 교차 확인해 주세요. 출처가 충돌하면 차이를 분리하고, 인용 가능한 근거와 신뢰도를 함께 알려 주세요.

원한다면 선택 과정까지 보고하도록 덧붙일 수 있습니다.

이 요청에 어떤 Capability를 선택했는지와 그 이유를 한 줄로 먼저 알려 주고 진행해 주세요.

에이전트는 요청을 설치된 Capability의 선택 조건과 대조하고, 맞는 능력을 사용한 뒤 결과와 근거, 남은 제한을 보고합니다.

업데이트를 요청하는 프롬프트

새 버전이 있다고 바로 교체할 필요는 없습니다. 현재 버전과 변경점을 비교하고, 실패했을 때 돌아갈 수 있는지 먼저 확인합니다.

이 Capability의 새 버전이 있는지 확인해 주세요. 현재 버전과 달라진 범위, 호환성, 권한, 위험을 비교하고, 복구 지점을 만든 뒤 업데이트와 재검증을 진행해 주세요.

업데이트 보고에는 이전 버전과 새 버전, 달라진 선택 범위와 요구사항, 재검증 결과, 복구 가능 여부가 포함되어야 합니다. 검증이 끝나기 전에는 마지막 정상 버전을 보존하는 것이 안전합니다.

문제가 생겼을 때 롤백을 요청하는 프롬프트

업데이트 뒤 검증이나 실제 사용이 실패했다면 억지로 계속 진행하지 않고 이전 정상 상태로 돌아갑니다.

방금 업데이트한 Capability가 정상 동작하지 않습니다. 보존된 마지막 정상 버전으로 롤백하고, 연결된 능력과 현재 선택 가능 상태를 다시 검증해 주세요. 원인과 복구 결과도 알려 주세요.

에이전트는 복구한 버전, 함께 되돌린 구성 요소, 재검증 결과, 보존한 변경 사항을 보고해야 합니다. 사용자가 따로 수정한 내용이 있다면 조용히 덮어쓰지 않고 먼저 차이를 알려 줍니다.

에이전트가 반드시 멈추고 확인해야 하는 순간

Capability를 찾고 설치하고 검증하는 것과, 그 능력으로 위험한 행동을 실행하는 것은 별개입니다. 다음 단계가 포함되면 에이전트는 영향을 설명하고 필요한 승인을 확인한 뒤 진행해야 합니다.

비밀번호, API 키 같은 secret 사용
사람의 계정이나 비공개 데이터 접근
메시지 전송, 게시, 결제 같은 외부 행동
production 환경 변경
삭제나 덮어쓰기처럼 되돌리기 어려운 작업
새로운 권한 부여 또는 접근 범위 확대

예를 들어 게시 Capability가 정상 설치되었더라도 실제 글을 공개하는 단계는 별도의 외부 행동입니다. 사용자가 요청한 범위와 대상이 분명하지 않다면 에이전트는 게시 전에 멈춰 확인해야 합니다.

좋은 완료 보고의 기준

Capability Registry를 잘 사용했다는 것은 단순히 “설치했습니다”라고 답하는 것이 아닙니다. 에이전트가 다음 질문에 답할 수 있어야 합니다.

무엇을 선택했고 왜 이 요청에 맞았나요?
정확히 어떤 버전이 준비되었나요?
무엇을 검증했고 결과는 어땠나요?
실제 요청에는 어떻게 사용했나요?
남은 제한이나 추가 승인은 무엇인가요?
문제가 생기면 어떤 정상 상태로 돌아갈 수 있나요?

사용자가 해야 할 일은 내부 명령을 따라 치는 것이 아니라, Room에서 원하는 결과와 안전 조건을 분명히 말하는 것입니다. 나머지 검색, 비교, 설치, 검증, 사용, 업데이트, 롤백은 에이전트에게 요청하고, 선택 이유와 증거를 보고받으면 됩니다.

Sources

ClawPod Capabilities, canonical Registry의 역할과 Capability 패키지 원칙.
ClawPod Capability Registry AgentSkill, 설치된 능력 확인, 검색, 검토, 설치, 검증, 업데이트, 롤백 절차와 안전 경계.