# Skills 快速入门

当 agent host 无法直接挂载 hosted MCP server 时，选择独立 Skill 路径。

- Canonical: https://docs.xmemo.dev/zh/docs/skills/quickstart
- Locale: zh-CN
- Content-Locale: zh-CN
- Canonical-Content-Digest: 6ba591b56f318400d8b7be59a77c62166fdb9bfcc7a5682e373a3d37a5b27f17
- Edition-Digest: 217010b1526ace294a58bf769f7792c1ef11eed56a80d5da0691df1e222f8089
- Source-Revision: sha256:155eed78733b301c44438f3428593a7838254964821afe158cef180b6dcfda2f

## 何时选择 Skill 而不是 MCP

独立 Skill 是面向无法挂载 hosted MCP server 的 agent host 的连接器运行时，通过直接 HTTPS 与 XMemo 通信。它不同于用户创建的 Cloud Skills（存储在 XMemo 中的可复用过程化 SOP）。

- 当 agent host 原生挂载远程 MCP 服务器时，使用 hosted MCP。
- 当 host 执行本地 CLI 工具或 skill 脚本时，使用独立 Skill 运行时。
- 运行时要求：Node.js 22.22.0 或更高版本（Node.js >= 22.22.0），并具备内置 ESM 支持。
- 零外部依赖：打包的 skill 脚本仅使用标准 Node.js 内置模块。
- 直接 HTTPS 通信：出站请求直接与 https://xmemo.dev/v1/skill/operations 通信。

## 按提示词和按客户端安装

将独立 Skill 安装到您的 agent skills 目录中。您可以向 agent 提供官方安装提示词、使用 XMemo CLI，或直接运行规范的 HTTPS 安装程序。

- 向您的 agent 发送提示词：将独立 XMemo Skill 安装到您的 skills 目录中：从 https://xmemo.dev/skill/install（在 Windows 上为 https://xmemo.dev/skill/install.ps1）运行安装程序，并将 XMEMO_SKILL_DIR 设置为您的 skills 目录加上 /xmemo-memory。运行其打印的 doctor 命令以验证安装，然后重新加载您的 skills 并按照 Skill 的首次运行步骤操作。遵循正常的安全检查，不要使用提升的权限。
- Claude Code 全局：~/.claude/skills/xmemo-memory（项目级：.claude/skills/xmemo-memory）。
- Codex：~/.codex/skills/xmemo-memory（或 ${CODEX_HOME:-$HOME/.codex}/skills/xmemo-memory）。
- OpenClaw：~/.openclaw/skills/xmemo-memory 或通过 ClawHub 安装（https://clawhub.ai/xmemo/skills/xmemo）。
- XMemo CLI：xmemo skill install --client <id>（支持 claude-code、codex 和 openclaw）或 xmemo skill install --all。
- 手动安装程序回退：POSIX 'curl -fsSL https://xmemo.dev/skill/install | sh' 或 PowerShell 'irm https://xmemo.dev/skill/install.ps1 | iex'。
- 服务发布通知：父目录的自动创建和打印的安装后 doctor 行将在下一个服务版本后生效；在预发布环境中，请在运行安装程序之前确保父目录存在。

```bash
# Ask your agent to run the installer, or run it directly:
curl -fsSL https://xmemo.dev/skill/install | XMEMO_SKILL_DIR="$HOME/.claude/skills/xmemo-memory" sh

# Or install via XMemo CLI:
xmemo skill install --client claude-code
```

## 首次运行与认证

在启动记忆操作之前，从已安装的 skill 目录运行连接性和认证检查。安装、认证和激活是不同的里程碑。

- 检查可达性：运行 doctor --anonymous 以在没有 credential 的情况下验证网络和服务可达性。
- 选择 credential 来源：首选由托管密钥库（Doppler、1Password 或环境）提供的 XMEMO_KEY。
- 交互式登录：运行 login --allow-plaintext 启动基于浏览器的设备登录。--allow-plaintext 标志显式确认以 0600 POSIX 权限将 token 未加密存储在 ~/.xmemo/skill-credentials.json 中。
- 验证认证：运行 auth status --verify 以验证您的 credential 是否携带所需的记忆 scope。

```bash
node scripts/xmemo-skill.mjs doctor --anonymous
node scripts/xmemo-skill.mjs login --allow-plaintext
node scripts/xmemo-skill.mjs auth status --verify
```

## 第一个有用的记忆任务

完成完整的记忆生命周期：保存一个综合的项目事实，通过来源归属召回它，在细节发生变化时更新它，并可选择在确认后软删除它。

- 1. 保存综合事实：node scripts/xmemo-skill.mjs remember --content "Project convention: all timestamps use UTC." --path "projects/onboarding/conventions"。
- 2. 召回事实：node scripts/xmemo-skill.mjs recall --query "project timestamp convention"。检查返回的记忆是否与保存的内容匹配。
- 3. 更新记忆：node scripts/xmemo-skill.mjs update --id <id> --content "Project convention: all timestamps use UTC with ISO 8601 formatting."。
- 4. 可选清理：node scripts/xmemo-skill.mjs forget --id <id> --confirm。删除严格要求 --confirm。

```bash
node scripts/xmemo-skill.mjs remember --content "Project convention: all timestamps use UTC." --path "projects/onboarding/conventions"
node scripts/xmemo-skill.mjs recall --query "project timestamp convention"
node scripts/xmemo-skill.mjs update --id mem_01hxyz... --content "Project convention: all timestamps use UTC with ISO 8601 formatting."
node scripts/xmemo-skill.mjs forget --id mem_01hxyz... --confirm
```

## 项目 Profile 与 AGENTS.md 提议

首次运行登录完成后，agent 可以提议向您项目的 AGENTS.md 添加 XMemo 记忆部分。此提议需要用户单独的显式同意。

- 需单独同意的提议：如果项目缺少 XMemo 部分，agent 会询问一次：'Want XMemo used automatically in every session of this project? I can add a short XMemo section to AGENTS.md (yes / later / don't ask again).'
- 打印说明：node scripts/xmemo-skill.mjs profile 打印针对项目 agent 配置的推荐提示词说明。
- 记录用户偏好：node scripts/xmemo-skill.mjs profile --status later 或 node scripts/xmemo-skill.mjs profile --status never 记录回答，以便 agent 不会重复提示。
- 生态系统注册表：已验证的 Skill 清单可在 ClawHub 获取：https://clawhub.ai/xmemo/skills/xmemo；OpenClaw 配套插件位于 https://clawhub.ai/xmemo/plugins/openclaw-memory。

```bash
# Inspect agent profile instructions:
node scripts/xmemo-skill.mjs profile

# Record deferred or declined offer:
node scripts/xmemo-skill.mjs profile --status later
node scripts/xmemo-skill.mjs profile --status never
```