Cloud Skills

程序性记忆与 Skill 架构

Cloud Skills 在 XMemo 中提供用户编写的程序性记忆，使开发人员和团队能够将标准操作规程（SOP）、Runbook、清单和可复用 Prompt 直接保存到持久存储中。一旦保存，支持工具中的已连接 Agent 即可发现、召回并解释它们，无需为每个 Agent 独立安装或手动复制 Prompt。已存储的 Cloud Skill 与安装的 XMemo Skill 客户端运行时（@xmemo/skill，node scripts/xmemo-skill.mjs）截然不同，后者用作 Agent 端的连接桥梁。

• Preview 功能：Cloud Skills 目前在 Memory Console（#skills）中处于 Preview 状态。
• 身份与资产：每个 Skill 都有唯一的 skill_id、易读的 slug、名称、描述、所有者作用域（Personal 或 Team）以及资产状态（active 或 archived）。
• 不可变修订链：Skill 包含 SkillRevision 快照的仅追加（append-only）序列。每个修订版携带 revision_id、revision_number、instruction_body、canonical_hash 以及可选的类型化 SkillComponent 资源。
• 大小限制：根指令主体限制在 64 KiB UTF-8 以内。一个修订版最多可包含 50 个声明的组件，每个组件限制在 128 KiB 以内。
• 组件资源类型：组件声明明确的语义类型，包括 reference、example、template、document、artifact 和 script。

发布生命周期与团队审核

Cloud Skill 修订版通过结构化生命周期转换，以保护生产工作流并支持协同创作：

• draft：创作和私有暂存期间的初始修订版状态，尚未公开发布激活。
• proposed：在 Team 工作区内编写的修订版会转换为 proposed 状态，等待团队所有者或管理员的明确审核与激活。
• published：具备 Agent 发现资格和默认 Level 1 召回资格的有效修订版。每个 slug 在任何给定时间仅有一个修订版被指定为 published。
• deprecated：较旧或被取代的修订版可标记为 deprecated 以提示下线，同时保留历史可复现召回能力。
• 个人与团队发布区别：在个人工作区中，带有发布意图的保存会直接转换为 published。在团队工作区中，提议的（proposed）修订版可防止未经审核的规程变更修改 Agent 工作流。

渐进式召回：Level 0、Level 1、Level 2

已连接的 Agent 使用 Progressive Recall 按需召回技能，防止未使用的文档挤满 LLM 上下文窗口：

• Level 0（发现）：查询搜索返回与用户任务匹配的轻量描述符（slug、name、description），无需加载完整指令。
• Level 1（根召回）：召回指定 slug 的技能根指令和组件清单，默认使用已发布修订版并具备最新修订版回退能力。
• Level 2（资源召回）：召回单个声明的组件（例如清单模板或参考 Schema），要求调用者提供明确的 revision_id 以避免资源分歧（resource tearing）。

recall_cloud_skill(query="incident response")  # Level 0: lightweight descriptors
recall_cloud_skill(slug="incident-response-checklist")  # Level 1: root instructions + manifest
recall_cloud_skill(
  slug="incident-response-checklist",
  revision_id="<revision-id-from-level-1>",
  resource="templates/triage-template.md",
)  # Level 2: one pinned resource component

固定 revision 可避免 resource tearing

当 Skill 更新时，XMemo 会创建下一个不可变修订版，而不是覆盖历史内容。Level 1 根召回提供根指令以及不可变的 revision_id 和组件清单。Level 2 资源请求要求调用者固定该确切的 revision_id。如果作者在 Agent 执行工作流时发布了新修订版，Agent 的固定读取仍会继续解析其开始时的确切快照，从而彻底消除资源分歧。

{
  "kind": "root",
  "data": {
    "skill_id": "skill_inc_triage_01",
    "revision_id": "rev_v1_inc_triage",
    "revision_number": 1,
    "canonical_hash": "c7b14d8e9f2a4c10...",
    "resources": [
      {
        "logical_path": "templates/triage-template.md",
        "type": "template",
        "content_hash": "e3b0c44298fc1c14..."
      }
    ]
  }
}

导入、导出与创作界面

开发人员可以在 Web 控制台中交互式编写 Cloud Skills，或从标准分发包导入现有技能：

• 控制台创作：在 Memory Console（#skills）中使用 Markdown 编辑器和组件管理交互式创建技能。
• 软件包导入：导入标准 SKILL.md 文件（带有 YAML 前言）、多文件 ZIP 压缩包或通过 URL（ClawHub 或 GitHub）导入远程仓库。
• 修订版差异对比：通过词级 Diff 对比任意两个修订版之间的指令变更和组件修改。
• Source Capsule 导出：将任何 Skill 修订版导出为无损 Source Capsule ZIP 压缩包，包含 SKILL.md、组件资源和元数据清单。

Agent 访问配置文件与 Sandbox 隔离

获授权的 Agent 在支持的客户端环境中通过契约化定义的 MCP 工具访问 Cloud Skills：

• 契约化 MCP 工具：工具 recall_cloud_skill（只读）和 save_cloud_skill（创作）在 cursor-plugin 和 ordinary-full 客户端配置文件中按契约公开（config/mcp-documentation-contract.json）。它们不会在 generic-public、chatgpt-public 或 claude-code 配置文件中公开。
• Prompt 可执行规程：大多数 Cloud Skills 都是标准操作规程，由 Agent 直接解释为 Prompt 指导而无需代码执行。
• Sandbox 执行边界：通过 execute_cloud_skill 进行的可选后端脚本执行是由 SandboxExecutionEngine 治理的高级服务端功能（目前未向任何客户端配置文件公开）。当本地缺乏 bubblewrap 容器隔离时，执行将以 SANDBOX_UNAVAILABLE 进行闭环失败处理（fail closed）。

可用性与生命周期边界

如果您的账户启用了程序性 Cloud Skills，则可以使用 Cloud Skill 功能。修订版是不可变的内容寻址快照，保存更改会创建新修订版而不会覆盖历史记录。当存在候选技能时，控制台会显示需要显式手动提升的审核横幅。