Agent Skill 安装

hb-sdk Agent Skill 随 @heybox/hb-sdk npm 包发布，确保 CLI、SDK 与 Skill 版本严格对应。运行环境要求 Node.js >=22.20.0。

随包内容只是 Skill 入口和完整性 manifest，不内置 API、CLI 或示例副本。Agent 每次处理 hb-sdk 任务时都需要联网读取 llms.txt，再按索引加载当前任务需要的 Markdown 页面；这样公开文档是唯一事实源，不需要在 npm 包内同步维护第二份说明。

如果索引或必需页面不可访问、返回 HTML / 登录页或其他非 Markdown 内容，Agent 应停止 hb-sdk 专项工作并说明文档不可用，不能退回已安装 Skill 快照、npm registry 副本或记忆中的 API。项目安装的 SDK 版本可能早于线上文档时，Agent 还应先读取索引中的兼容性与 Changelog 页面。

安装

在小程序项目目录执行，默认安装到项目 .agents/skills 并更新 skills-lock.json：

hb-sdk skill install

安装到当前用户的 Agent 目录：

hb-sdk skill install --global

可用 --agent codex cursor 指定目标，--all-agents 安装到所有检测到的 Agent；已有内容被修改时，使用 --force 明确覆盖。项目模式要求当前项目声明并解析到与 CLI 相同版本的 @heybox/hb-sdk。

版本与诊断

Skill manifest 位于 npm 包的 skill/skill.json，包含 SDK 版本、分发路径和完整性校验。安装后可用以下命令检查本地各 Agent 目标：

hb-sdk doctor
hb-sdk doctor --json

doctor 只读取本地 npm 包、项目依赖和 Skill 目录，不访问网络，也不会修改文件。它校验的是入口版本和本地完整性，不代表线上文档当前可访问。缺失、过期、版本不匹配、内容被手工修改或残留旧版 references/ 时返回非零退出码；修复后重新执行 hb-sdk skill install --force。

从 Open 迁移

0.8.0 起 npm 包是唯一持续更新的分发源。此前从 open.xiaoheihe.cn 安装的未修改 Skill 会在首次安装时自动迁移；检测到内容已被修改时必须显式增加 --force。Open 上的旧快照仅用于兼容读取，不再更新。