# 安装与配置 Volcengine Skills 支持 Claude Code、Codex、Cursor、Gemini CLI、OpenCode、OpenClaw 及其他兼容 Skills 的 Agent。推荐先安装四个核心 Skills，再由 `volcengine-find-skills` 或通用 Skills CLI 按任务补充所需能力。 ## 安装前准备 * 已安装并可以正常启动目标 Agent。 * 能够访问 GitHub 和 npm；使用一键安装时需要 Node.js 20 或更高版本。 * 本机已有较早版本的 `ve` 并使用兼容安装路径时，`tar` 或 `unzip` 需在 `PATH` 中可用；新版本 `ve` 使用内置的 Skills 管理能力。 * 安装阶段不需要提供火山引擎 AK/SK。 ## 选择安装方式 |方式 |安装内容 |同时准备的 CLI |适合场景 | |---|---|---|---| |一键安装 |四个核心 Skills |检测并按需安装 `ve`、`arkcli` |使用一条命令完成常用 Agent 的基础配置 | |Agent 原生 Plugin |四个核心 Skills |按实际任务准备 |使用 Agent 自带的 Plugin 机制 | |通用 Skills CLI |可选择核心、全部或指定 Skills |按实际任务准备 |精确控制目标 Agent 和安装范围 | 需要指定 Agent 或 Skill 时，请使用通用 Skills CLI 或 `volcengine-find-skills`，不要把一键安装参数作为安装范围控制方式。 ## 一键安装准备 Node.js 20 或更高版本，然后运行： ```bash npx -y @volcengine/skills-setup@latest ``` 安装程序以 npm 包 [@volcengine/skills-setup](https://www.npmjs.com/package/@volcengine/skills-setup) 发布，源码位于 [volcengine-cli/skills-setup](https://github.com/volcengine/volcengine-cli/tree/master/skills-setup)。它会检查 `ve` 和 `arkcli` 并按需安装缺失工具：首次安装 `ve` 时由 `ve` 安装四个核心 Skills；本机已有 `ve` 时，自动使用 `ve skills update` 或兼容安装路径更新核心 Skills。该命令可以重复运行；已存在的 CLI 默认不升级。本机已经安装 `ve`，只希望跳过 `ve`/`arkcli` 安装并更新核心 Skills 时运行： ```bash npx -y @volcengine/skills-setup@latest --skip-install ``` ## 只安装核心 Skills 以下命令只安装 `volcengine-cli`、`volcengine-troubleshooting`、`volcengine-knowledge-search` 和 `volcengine-find-skills`： ```bash npx skills add volcengine/volcengine-skills \ --global --yes --copy --full-depth \ --skill volcengine-cli volcengine-troubleshooting volcengine-knowledge-search volcengine-find-skills ``` 安装 Catalog 中的全部 Skills： ```bash npx skills add volcengine/volcengine-skills --full-depth ``` 安装核心 Skills 后，可以让 Agent 使用 `volcengine-find-skills` 查找并安装任务所需的其他 Skill。 ## Claude Code ```text /plugin marketplace add volcengine/volcengine-skills /plugin install volcengine-core@volcengine-skills /reload-plugins /volcengine-core:volcengine-find-skills ``` 重新加载 Plugin 后调用 `volcengine-find-skills`。如果 Finder 能返回 Skills Catalog，说明安装已生效。 ## Codex ```bash codex plugin marketplace add volcengine/volcengine-skills codex plugin add volcengine-core@volcengine-skills codex plugin list ``` 安装后在新任务中描述你的火山引擎需求。需要其他能力时，Finder 会从 Catalog 中选择并安装对应 Skill；新安装的 Skill 如果未在当前任务中加载，请新建任务后继续。 ## Cursor 在 Cursor 2.5 或更高版本的 Agent 对话中输入完整命令： ```text /add-plugin volcengine-core@https://github.com/volcengine/volcengine-skills /volcengine-find-skills ``` `/add-plugin` 可能不会显示在自动补全中。Finder 能返回 Skills Catalog，即表示安装已生效。 ## Gemini CLI Gemini CLI 需要按路径安装四个核心 Skills： ```bash gemini skills install https://github.com/volcengine/volcengine-skills --path skills/core/volcengine-cli gemini skills install https://github.com/volcengine/volcengine-skills --path skills/core/volcengine-troubleshooting gemini skills install https://github.com/volcengine/volcengine-skills --path skills/core/volcengine-knowledge-search gemini skills install https://github.com/volcengine/volcengine-skills --path skills/core/volcengine-find-skills gemini skills list ``` 首次安装时逐项确认安全提示，完成后重启 Gemini CLI。 ## OpenCode 克隆仓库： ```bash git clone https://github.com/volcengine/volcengine-skills.git ~/.config/opencode/volcengine-skills ``` 在 `opencode.json` 中加入核心 Skills 路径： ```json { "skills": { "paths": ["~/.config/opencode/volcengine-skills/plugins/volcengine-core/skills"] } } ``` 重启 OpenCode，并运行： ```bash opencode debug skill ``` 输出中应包含四个核心 Skills。 ## 安装结果验证 1. 重启目标 Agent 或重新加载 Plugin。 2. 确认 Agent 能发现 `volcengine-cli`、`volcengine-troubleshooting`、`volcengine-knowledge-search` 和 `volcengine-find-skills`。 3. 调用 `volcengine-find-skills`，确认能够读取 Skills Catalog。 4. 使用一键安装时，可运行 `command -v ve` 和 `command -v arkcli`；两条命令都返回可执行文件路径，才表示 CLI 已进入 `PATH`。 ## 配置云账号访问查询公开文档不需要云账号。需要访问云资源时，先确认 `ve` 可用并检查当前身份： ```bash ve --version ve sts GetCallerIdentity ``` `ve --version` 应返回版本号；`ve sts GetCallerIdentity` 应返回当前身份，且不包含 `ResponseMetadata.Error`。后续示例中的 `cn-beijing` 仅为示例地域，请替换为目标产品实际支持的地域。如果身份不可用，请根据 [火山引擎 CLI 文档](https://docs.volcengine.com/docs/83927/1176799?lang=zh) 完成 Console Login、AK/SK、STS 或 SSO 配置。一次任务中应保持同一 Profile 和地域。 ## 更新与卸载通过一键安装或 `ve` 管理的核心 Skills 使用以下命令更新和卸载： ```bash ve skills update ve skills uninstall ``` 需要同时升级本机已有的 `ve` 和 `arkcli` 时，使用最新版安装程序并显式指定 `--update`： ```bash npx -y @volcengine/skills-setup@latest --update ``` OpenCode 使用 Git 更新： ```bash cd ~/.config/opencode/volcengine-skills git pull ``` 卸载 OpenCode 配置时，从 `opencode.json` 的 `skills.paths` 中移除对应条目，再删除本地仓库目录。通过 Agent Plugin 或通用 Skills CLI 安装的内容，请分别使用对应宿主或 Skills CLI 的更新与卸载功能。 ## 兼容性 |Agent |验证方式 |使用提示 | |---|---|---| |Claude Code |调用 `volcengine-find-skills` |安装后执行 `/reload-plugins` | |Codex |`codex plugin list` |新增 Skill 可能需要新建任务后加载 | |Cursor |调用 `volcengine-find-skills` |要求 Cursor 2.5 或更高版本；安装命令可能无自动补全 | |Gemini CLI |`gemini skills list` |安装后重启 Gemini CLI | |OpenCode |`opencode debug skill` |通过 `skills.paths` 挂载核心目录 | |OpenClaw 和其他兼容 Agent |查看 Agent 的 Skills 列表 |优先使用通用 Skills CLI | 更多安装、发现和身份问题，请查看 [常见问题](https://docs.volcengine.com/docs/88782/2658331)。

火山引擎 Skills