Cloud Skills 指南

用户目标

在连接的 agent 之间编写、审核、发布和召回可复用的过程性技能（例如运行手册、核对清单和标准操作程序），无需手动复制粘贴、重复的每 agent 配置或引起上下文窗口膨胀。

可用性与前提条件

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) 在经过身份验证的团队成员之间共享技能，并提供基于角色的治理。
• Agent 令牌作用域：Agent 召回需要 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：用 markdown 编写根过程性指导（限制为 64 KiB UTF-8）。
• Components：添加包含事件问卷且类型为 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"，使其可立即被授权的 agent 发现。
• 团队审核工作流：在团队工作区中，保存会创建状态为 "proposed" 的修订版本 v1。在团队所有者或管理员发布修订版本之前，团队成员可以审核指令、检查组件 diff 并测试执行。
• 草稿暂存：如果未勾选发布意图，修订版本将保持在 "Draft" 状态，以便进行私密编辑和测试，而不会暴露给 agent 发现。

4. 验证 agent 渐进式召回

连接的 agent 根据需要在三个渐进式层级中查询和检索已发布的技能，以节省上下文预算：

• 第 0 层（发现）：Agent 按任务查询进行搜索，并在没有完整指令的情况下接收轻量级描述符。
• 第 1 层（根指令）：Agent 使用技能 slug 召回根指令和组件清单。
• 第 2 层（固定资源）：Agent 通过提供从第 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 的进行中 agent 工作流将继续读取 v1 资源而不会撕裂，而新的第 1 层查询会自动解析已发布的 v2 修订版本。

可观察结果

成功的 Cloud Skill 创建和发布会在控制台和 agent 界面上产生可观察的变化：

• 控制台状态徽章：技能卡片显示 "Published" 徽章、活动修订版本标签（例如 v1 或 v2）和组件数量。
• 资源管理器：详细信息视图显示声明的 templates/triage-template.md 组件，并带有语法预览和复制操作。
• Agent 召回封装：第 1 层返回带有 instruction_body、revision_id 和 resources 列表的类型化根响应。第 2 层返回确切的组件文本。
• 导出可用性：在详细信息视图中，点击 "Export" 可下载包含 SKILL.md、清单元数据和声明组件的 Source Capsule ZIP 归档。

Agent 可以访问的内容

Agent 和人类用户在严格的身份验证和能力边界下运行：

• 客户端配置文件：MCP 工具 recall_cloud_skill 和 save_cloud_skill 契约化地在 cursor-plugin 和 ordinary-full 配置文件中提供；通用的公共和聊天客户端配置文件不公开它们。
• 作用域强制执行：Agent 使用带有 skills:read 或 skills:write 作用域的 API 密钥或 OAuth 令牌进行身份验证。作用域限定为个人记忆的令牌无法检查团队技能，除非显式绑定到该团队。
• 草稿和提议保护：Agent 无法在第 0 层查询发现中发现或召回草稿修订版本、等待审核的提议修订版本或已归档的技能。
• Prompt 可执行指导：连接的 agent 将过程性指令直接解释为 prompt 上下文；技能不会在主机上自动执行代码。

共享与生命周期边界

Cloud Skills 在个人运行手册与协作团队资产之间保持明确的租户隔离：

• 空间边界：个人技能 (/me#skills) 对创建者私有。团队技能 (?space=<team_id>#skills) 与经过身份验证的团队成员共享。
• 团队审批：团队修订版本在从 proposed 状态转换到 published 状态之前需要所有者或管理员审核。
• 归档与删除：归档技能 (DELETE /v1/skills/{skill_id}) 会禁用 agent 发现并将其从活动列表中隐藏，同时保留不可变修订版本历史。
• 修订版本不可变性：修订版本是内容寻址的不可变快照；保存更新会创建新修订版本，而不是覆盖现有记录。
• 候选者审核横幅：当存在候选者时，控制台可以显示带有 Promote 和 Dismiss 操作的候选者横幅；候选者需要人工审核。

故障恢复

使用以下补救步骤诊断并解决常见的 Cloud Skill 问题：

• 资源召回错误 (REVISION_PINNING_VIOLATION)：第 2 层资源请求需要显式的 revision_id。如果省略，服务器将拒绝请求以防止资源撕裂。修复方法：传递第 1 层响应中返回的 revision_id。
• 未找到技能 (SKILL_NOT_FOUND)：验证 slug 是否完全匹配，以及查询是否在正确的工作区中执行（个人对比团队 ?space=<team_id>）。
• 访问被拒绝 (403 Forbidden)：检查 agent 令牌是否包含 skills:read（用于召回）或 skills:write（用于保存），以及经过身份验证的用户是否属于目标团队。
• 团队修订版本保持提议状态：查询团队技能的 agent 将接收当前发布的修订版本，直到团队所有者或管理员审核并发布提议的修订版本。
• 运行时不可用 (503)：如果您的部署环境中禁用了 Cloud Skills 子系统或未进行配置，则返回此错误。

相关参考

有关概念架构、工具参数和团队协作，请参阅相关文档：

• Cloud Skills 概念：/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 了解 Web 控制台布局、空间选择和设置。
• Teams：/docs/capabilities/teams 了解团队工作区协作和角色权限。