Cloud Skills 가이드

사용자 목표

수동 복사 및 붙여넣기, 에이전트별 반복 설정, 컨텍스트 창 비대화 없이 연결된 에이전트 전반에서 재사용 가능한 절차적 스킬(런북, 체크리스트, 표준 운영 절차 등)을 작성, 검토, 게시 및 리콜합니다.

이용 가능성 및 사전 요구 사항

Cloud Skills는 현재 Memory Console의 https://xmemo.dev/me#skills에서 Preview로 제공됩니다. 스킬을 작성하거나 리콜하기 전에 환경이 다음 요구 사항을 충족하는지 확인하십시오:

• 기능 활성화: 계정에 절차적 Cloud Skills가 활성화된 경우 활성 상태가 됩니다.
• 워크스페이스 선택: 개인 공간(https://xmemo.dev/me#skills)은 비공개 스킬을 저장합니다. 팀 공간(https://xmemo.dev/me?space=<team_id>#skills)은 역할 기반 거버넌스를 통해 인증된 팀 구성원 간에 스킬을 공유합니다.
• 에이전트 토큰 범위: 에이전트 리콜에는 skills:read 또는 memory:read 범위가 필요합니다. 스킬 생성 및 리비전 게시에는 skills:write 또는 memory:write 범위가 필요합니다.
• 지원되는 클라이언트 프로필: MCP 도구 recall_cloud_skill 및 save_cloud_skill은 cursor-plugin 및 ordinary-full 클라이언트 프로필에 노출됩니다. 일반 공개 및 채팅 인터페이스는 스킬 작성 도구를 직접 노출하지 않습니다.

1. Memory Console의 Cloud Skills로 이동

Memory Console을 열고 Cloud Skills 섹션을 선택합니다:

• 개인 공간: 개인 절차적 런북을 관리하려면 https://xmemo.dev/me#skills를 엽니다.
• 팀 공간: 공유된 조직 스킬을 관리하려면 https://xmemo.dev/me?space=<team_id>#skills를 엽니다.
• 콘솔 인터페이스: 패널에 스킬 목록, 검색창("Search skills by name, slug, or keywords..."), 주요 작업("New Skill" 및 "Import Skill")이 표시됩니다.

2. 절차적 스킬 및 선언된 컴포넌트 작성

"New Skill"을 클릭하여 스킬 작성 모달을 엽니다. 스킬 메타데이터, 루트 지침 및 컴포넌트 리소스를 구성합니다:

• Skill Name: "Incident Response Checklist"를 입력합니다(필수 필드).
• Slug: 소문자 식별자 "incident-response-checklist"를 입력합니다(1–64자의 영숫자 또는 하이픈).
• Description: "Standard operating procedure for triaging and resolving high-severity production incidents."를 입력합니다.
• Instructions: 마크다운으로 루트 절차 안내를 작성합니다(64 KiB UTF-8로 제한).
• Components: 인시던트 설문지가 포함된 type template의 템플릿 컴포넌트 templates/triage-template.md를 추가합니다.

# Incident Response Checklist

When a high-severity production alert triggers:
1. Identify the impacted service and declare an incident channel.
2. Verify service error rates and recent deployment events.
3. Complete the triage questionnaire at `templates/triage-template.md`.
4. Apply documented mitigation or initiate canary rollback.
5. Record timeline events and assign follow-up action items.

3. 스킬 리비전 검토 및 게시

스킬 리비전을 저장하고 개인 및 팀 공간 전반에서 게시가 어떻게 동작하는지 확인합니다:

• 개인 게시: 개인 워크스페이스에서 게시 의도로 저장하면 리비전 v1이 "Published"로 직접 전환되어 승인된 에이전트가 즉시 검색할 수 있게 됩니다.
• 팀 검토 워크플로: 팀 워크스페이스에서 저장하면 상태가 "proposed"인 리비전 v1이 생성됩니다. 팀 구성원은 팀 소유자 또는 관리자가 리비전을 게시하기 전에 지침을 검토하고 컴포넌트 차이점을 검사하며 실행을 테스트할 수 있습니다.
• 초안 스테이징: 게시 의도가 선택 해제된 경우 리비전은 에이전트 검색에 노출되지 않고 비공개 편집 및 테스트를 위해 "Draft" 상태로 유지됩니다.

4. 에이전트의 점진적 리콜 검증

연결된 에이전트는 컨텍스트 예산을 보존하기 위해 세 가지 점진적 수준에 걸쳐 게시된 스킬을 온디맨드로 쿼리하고 검색합니다:

• 수준 0 (발견): 에이전트는 작업 쿼리로 검색하고 전체 지침 없이 경량 설명자를 수신합니다.
• 수준 1 (루트 지침): 에이전트는 스킬 슬러그를 사용하여 루트 지침 및 컴포넌트 매니페스트를 리콜합니다.
• 수준 2 (고정 리소스): 에이전트는 수준 1에서 반환된 정확한 revision_id를 제공하여 선언된 템플릿 컴포넌트를 검색합니다.

# Level 0: Discover relevant skills by task query
recall_cloud_skill(query="incident response")

# Level 1: Retrieve root instructions and component manifest
recall_cloud_skill(slug="incident-response-checklist")

# Level 2: Retrieve pinned component resource without resource tearing
recall_cloud_skill(
  slug="incident-response-checklist",
  revision_id="<revision-id-from-level-1>",
  resource="templates/triage-template.md",
)

5. 절차 업데이트 및 리비전 불변성 확인

운영 요구 사항이 변경되면 스킬을 업데이트하여 변경 불가능한 새 리비전을 생성합니다:

• 스킬 세부 정보 열기: 콘솔에서 "Incident Response Checklist"를 선택하고 "New Revision"을 클릭합니다.
• 지침 수정: 롤백하기 전에 필수 카나리아 검증 단계를 추가합니다.
• 새 리비전 저장: 콘텐츠를 저장하면 리비전 카운터가 v2로 증가하여 변경 불가능한 새 revision_id 및 canonical_hash가 생성됩니다.
• 리비전 고정 보호: 리비전 v1에 고정된 진행 중인 에이전트 워크플로는 리소스 파손 없이 v1 리소스를 계속 읽는 반면, 새로운 수준 1 쿼리는 게시된 v2 리비전을 자동으로 확인합니다.

관찰 가능한 결과

성공적인 Cloud Skill 생성 및 게시는 콘솔 및 에이전트 인터페이스 전반에 걸쳐 관찰 가능한 변화를 생성합니다:

• 콘솔 상태 배지: 스킬 카드에 "Published" 배지, 활성 리비전 태그(예: v1 또는 v2) 및 컴포넌트 수가 표시됩니다.
• 리소스 탐색기: 세부 정보 보기에 구문 미리보기 및 복사 작업이 포함된 선언된 templates/triage-template.md 컴포넌트가 표시됩니다.
• 에이전트 리콜 봉투: 수준 1은 instruction_body, revision_id 및 resources 목록이 포함된 형식화된 루트 응답을 반환합니다. 수준 2는 정확한 컴포넌트 텍스트를 반환합니다.
• 내보내기 가용성: 세부 정보 보기에서 "Export"를 클릭하면 SKILL.md, 매니페스트 메타데이터 및 선언된 컴포넌트가 포함된 Source Capsule ZIP 아카이브가 다운로드됩니다.

에이전트가 액세스할 수 있는 범위

에이전트와 인간 사용자는 엄격한 인증 및 기능 경계 내에서 작동합니다:

• 클라이언트 프로필: MCP 도구 recall_cloud_skill 및 save_cloud_skill은 cursor-plugin 및 ordinary-full 프로필에 계약상 노출됩니다. 일반 공개 및 채팅 클라이언트 프로필은 이를 노출하지 않습니다.
• 범위 적용: 에이전트는 skills:read 또는 skills:write 범위를 전달하는 API 키 또는 OAuth 토큰으로 인증합니다. 개인 메모리 범위의 토큰은 해당 팀에 명시적으로 바인딩되지 않는 한 팀 스킬을 검사할 수 없습니다.
• 초안 및 제안 보호: 에이전트는 수준 0 쿼리 검색에서 초안 리비전, 검토 대기 중인 제안된 리비전 또는 보관된 스킬을 검색하거나 리콜할 수 없습니다.
• 프롬프트 실행 가능 지침: 연결된 에이전트는 절차 지침을 프롬프트 컨텍스트로 직접 해석합니다. 스킬은 호스트에서 코드를 자동으로 실행하지 않습니다.

공유 및 라이프사이클 경계

Cloud Skills는 개인 런북과 협업 팀 자산 간의 명확한 테넌트 분리를 유지합니다:

• 공간 경계: 개인 스킬(/me#skills)은 생성자에게 비공개입니다. 팀 스킬(?space=<team_id>#skills)은 인증된 팀 구성원과 공유됩니다.
• 팀 승인: 팀 리비전은 상태가 "proposed"에서 "published"로 전환되기 전에 소유자 또는 관리자의 검토가 필요합니다.
• 보관 대 삭제: 스킬을 보관하면(DELETE /v1/skills/{skill_id}) 에이전트 발견이 비활성화되고 활성 목록에서 숨겨지는 동시에 변경 불가능한 리비전 기록이 보존됩니다.
• 리비전 불변성: 리비전은 콘텐츠 주소가 지정된 변경 불가능한 스냅샷입니다. 업데이트를 저장하면 기존 레코드를 덮어쓰지 않고 새 리비전이 생성됩니다.
• 후보 검토 배너: 후보가 있는 경우 콘솔에 Promote 및 Dismiss 작업이 포함된 후보 배너가 표시될 수 있습니다. 후보는 수동 검토가 필요합니다.

장애 복구

다음 해결 단계를 사용하여 일반적인 Cloud Skill 문제를 진단하고 해결하십시오:

• 리소스 리콜 오류 (REVISION_PINNING_VIOLATION): 수준 2 리소스 요청에는 명시적인 revision_id가 필요합니다. 생략하면 서버는 리소스 파손을 방지하기 위해 요청을 거부합니다. 해결 방법: 수준 1 응답에서 반환된 revision_id를 전달하십시오.
• 스킬을 찾을 수 없음 (SKILL_NOT_FOUND): 슬러그가 정확히 일치하는지, 올바른 워크스페이스(Personal 대 Team ?space=<team_id>)에서 쿼리가 실행되었는지 확인하십시오.
• 액세스 거부 (403 Forbidden): 에이전트 토큰에 skills:read(리콜용) 또는 skills:write(저장용)가 포함되어 있는지, 인증된 사용자가 대상 팀에 속해 있는지 확인하십시오.
• 팀 리비전이 제안 상태로 유지됨: 팀 스킬을 쿼리하는 에이전트는 팀 소유자 또는 관리자가 제안된 리비전을 검토하고 게시할 때까지 현재 게시된 리비전을 수신합니다.
• 런타임 사용 불가 (503): 배포 환경에서 Cloud Skills 하위 시스템이 비활성화되었거나 구성되지 않은 경우 반환됩니다.

관련 참조

개념 아키텍처, 도구 매개변수 및 팀 협업에 대해서는 관련 문서를 참조하십시오:

• Cloud Skills 개념: 3계층 아키텍처, 컴포넌트 모델 및 리비전 고정에 대해서는 /docs/concepts/cloud-skills를 참조하십시오.
• recall_cloud_skill 참조: 매개변수 스키마 및 응답 형식에 대해서는 /docs/tools/recall-cloud-skill을 참조하십시오.
• save_cloud_skill 참조: 작성 매개변수 및 컴포넌트 업로드 형식에 대해서는 /docs/tools/save-cloud-skill을 참조하십시오.
• Memory Console: 웹 콘솔 레이아웃, 공간 선택 및 설정에 대해서는 /docs/guides/memory-console을 참조하십시오.
• Teams: 팀 워크스페이스 협업 및 역할 권한에 대해서는 /docs/capabilities/teams를 참조하십시오.