Install Skills

install-skills

第一步：完整 CLI 命令即时执行

这是最常见、优先级最高的场景，先于本文件后续任何规划、核验或同步章节判断。

仅当用户消息已经给出待执行、确认、复述或解释的完整 skills add / npx skills add 命令，且命令已包含安装源、--skill 或具体 skill 名、-g、-y、明确的 -a / --agent 目标时，才进入本规则。此时只做以下最小检查；检查通过后，按用户意图立即执行原命令，或原样确认、复述该命令。

最小检查只包括：

• 用户意图是执行命令，还是只要求确认、复述或解释命令。
• 安装源是否指向用户已确认可信的 skills 目录；不能根据当前工作区目录或未验证来源自行改写。来源不明确时不走本规则，回到常规安装规划与核验流程。
• 引号、占位符或明显截断是否破损。
• 目标 agent 列表是否来自用户命令本身。

在原命令尚未执行或尚未按用户语义确认前，禁止读取 DEFAULT_PLATFORMS、定位或调用 sync-local-global-agents-skills、盘点目标、进入 release、fallback、agent team 或长计划。原命令成功后，查看安装摘要验收即可；只有用户额外要求同步到本地 agent 平台、站点清理、清单盘点、目录级同步或新平台核验时，才进入下方对应流程。

后续的“已验证可执行目标”“目录级链接”和 DEFAULT_PLATFORMS 全部属于目录级链接同步，即 sync-local-global-agents-skills 的职责；它们与 skills add ... -a <agent> 的 CLI 安装无关，命中本规则时无需阅读或执行。

任务类型速查

职责边界

本技能是 skills 的清单与调度入口，不提供安装脚本，也不维护第二份 skills 副本。规范源目录为 ~/.agents/skills。

• 负责通用 skills 的安装规划、命令确认、多 agent 同步目标判断，以及全局安装后的同步调度闭环。
• 已验证的目录级链接目标，具体安装动作交给 sync-local-global-agents-skills。
• 未验证的 agent 或项目级目录只记录候选与前置核验项；不得凭印象编造独立 skills 目录、链接、复制或替换目录。

全局技能卸载流程

当用户要求删除、卸载或移除某个全局 skill、某组 skills，或要求某类技能不再被多个 agent 入口发现时，必须优先使用 skills remove。文件系统删除只能处理 CLI 无法管理的已确认残留，不能替代正式卸载。

标准顺序

1. 先写明任务契约：要卸载的技能或主题范围、必须不再显示的 agent 入口、验收 pattern，以及“不把物理删除作为主路径”的限制。
2. 使用 skills list -g --json，或用户指定 agent 的 skills list -g -a <agent...> --json，盘点已注册候选。
3. 当用户给出产品、厂商或主题系列时，同时按名称、别名、description 和用户范围词识别候选；不能只按一个前缀匹配。删除前列出候选，若保留同义技能，必须说明理由。
4. 对已注册的目标使用 skills remove -g -y <skill...>。不要默认传 -a '*'；若当前 CLI 不接受该通配符，省略 -a，以 CLI 实际管理范围和输出为准。
5. 卸载成功后，按已安装 sync-local-global-agents-skills 的说明同步已验证平台。同步器只负责卸载后的分发和链接收敛，不替代 skills remove。
6. 用 CLI 注册表和实际目录做双重验收；任一侧仍有未解释的匹配时，不得声称完成。

文件系统兜底边界

只有同时满足以下条件，才能检查或处理文件系统残留：

• skills remove -g -y <skill> 明确报告找不到目标，或目标已不在 skills list --json 注册表中。
• 规范源目录、已验证同步目标或用户明确指定的 agent 目录仍有目标残留。
• 已确认残留是坏链接、空目录或 CLI 不管理的旧目录，并回读其绝对路径、LinkType 和 Target。
• 操作范围只包含该残留项，且不会触及规范源目录之外的非目标内容。

对 junction 或 symlink 只能移除链接本身，不能递归删除其目标。目录职责、链接目标或影响范围任一项不明确时，停止并向用户说明待确认信息。

卸载验收

卸载开始前先确定目标 pattern。完成前至少检查以下两类证据：

$items = skills list -g --json | ConvertFrom-Json
$matches = @($items | Where-Object {
  $_.name -match '<pattern>' -or $_.path -match '<pattern>'
})
"MATCH_COUNT=$($matches.Count)"

• CLI 注册表中目标 pattern 的 MATCH_COUNT 为 0。
• ~/.agents/skills、从 DEFAULT_PLATFORMS 确认的已验证同步目标，以及用户明确要求覆盖的 agent skills 目录中，目标 pattern 的匹配数均为 0。

若保留某个同义或关联 skill，或残留目录不归 CLI 管理，必须逐项说明其来源、是否注册、保留或后续处理理由。

Kimi Desktop（Daimon）污染排查与清除

Kimi Desktop 的 Daimon 供应器（kimi-daimon setup）会把内置技能作为固定步骤写入规范源目录 ~/.agents/skills。这些技能不是 skills CLI 安装的，注册表没有来源记录，会污染所有 agent 共享的技能面，且随 Kimi Desktop 更新或重新供应再次写入。

污染检测

发现全局技能目录出现用户未主动安装的 skills，或例行盘点时，先检查标记文件：~/.agents/skills/.daimon-managed-builtin-skills.json。标记文件存在即为 Kimi Desktop 污染证据；其 skills 数组是本次清除黑名单，sourceRoot 指向 Kimi Desktop 应用内的捆绑技能源。

清除流程

1. 读取标记文件的 skills 数组作为黑名单；黑名单是动态的，不得硬编码技能名或数量。
2. 校验黑名单条目合法性：仅处理符合 ^[a-z0-9][a-z0-9-]*$ 的名称，其余报告并跳过。
3. 删除前逐条取证：lstat 确认每个条目类型；是符号链接时只移除链接本身；是真实目录时，将其 SKILL.md 与 sourceRoot 比对确认归属；内容不一致时记录为版本漂移，仍按黑名单处理但如实报告。
4. 删除每个黑名单条目对应目录，最后删除标记文件本身；标记文件删除后，污染检测才可复现。
5. 双重验收：~/.agents/skills 中黑名单目录残留为 0、标记文件不存在、各 agent 入口不再列出对应技能。

边界与复发警示

• 只删除黑名单点名的技能；用户通过 skills add 或其他途径安装的同名技能不得误删。用户需要其他厂商的同名技能时，删除后通过 skills add 流程重装。
• Kimi Desktop 更新或 Daimon 重新供应会再次写入这些内置技能并重建标记文件；每次 Kimi Desktop 更新后，若要保持全局目录干净，重新执行本流程。
• 证据链、事件时间线与历史清除记录见 references/kimi-desktop-daimon-contamination.md。

已验证可执行目标

以下目标是本技能发布时从 DEFAULT_PLATFORMS 摘录的可读快照，已由 sync-local-global-agents-skills 证实支持从 ~/.agents/skills 建立目录级链接。实际执行前仍应重新定位已安装的同步技能并读取其 DEFAULT_PLATFORMS：

本表仅描述从 ~/.agents/skills 建立目录级链接的平台可执行目标，属于 sync-local-global-agents-skills 的职责范围。不适用于 skills add ... -a <agent> 的 CLI 安装语义：CLI 安装目标由 skills CLI 原生支持，与是否在本表内无关，无需核验本表。

Qoder 指 Qoder IDE 与 Qoder agent 本体，专属 skills 目录为 ~/.qoder/skills。不得与同机其他形似目录混淆：~/.qoder-cli（Qoder CLI）、~/.qoder-cn（Qoder CN IDE）、~/.qoderwork 与 ~/.qoderworkcn（QoderWork / QoderWork CN，其中 ~/.qoderworkcn/skills 已作为 QoderWork 平台单列）。

生态入口与待验证候选

Claude Code、Codex、Cursor、Antigravity、Trae 等通常通过全局 skills 目录或 skills CLI 生态读取 skills。未在已验证资料中确认独立 skills 目录时，只能视为待验证候选，不能据此创建链接或复制目录。

确认新目标前，至少核验：

1. 该 agent 是否读取 ~/.agents/skills 或具有公开、稳定的独立 skills 根目录。
2. 独立目录是否只承担 skills 根目录职责，且不与配置、缓存或其他资源混合。
3. 该 agent 是否接受目录级符号链接或需要其自身的安装机制。

项目级候选目录

以下目录是项目级候选，而非默认批量链接目标：

项目级同步不得默认批量软链接。必须按单个项目、单个 agent 确认授权、目录职责和覆盖范围后再处理。

目录级链接策略

• 默认且唯一的同步策略是符号链接（目录级链接）；禁止把规范源目录复制为实体副本。全机只允许存在一份物理副本。
• 仅当目标目录只承担 skills 根目录职责时，使用目录级链接。
• 目标不存在时可创建链接；已是指向规范源目录的正确链接时跳过。
• 目标为真实目录时，先备份，再替换为链接。
• 目标是指向错误位置的链接时，先核实后重建。
• 目标目录职责不确定、含混合配置，或无法确认链接兼容性时，不自动替换；保留现状并请求进一步确认。
• 预期形态说明：目录级链接建立后，平台 skills 目录本身就是一条链接；浏览时看到的条目是规范源目录的真实条目，属于链接穿透的正常现象，不是实体拷贝，也不会产生逐条快捷方式箭头。判断是否误复制，以链接目标处写入文件能否即时出现在平台目录为准。

调度与验收

1. 先区分本次是安装、卸载、盘点还是目录级同步。卸载任务先完成“全局技能卸载流程”；安装和同步任务再确认规范源目录为 ~/.agents/skills，并确定目标属于已验证目标、待验证候选或项目级候选。
2. 已验证目标调用 sync-local-global-agents-skills 执行；其余目标先完成目录语义与兼容性核验。
3. 执行前列出将创建、跳过、备份或替换的目录；执行后确认目标是正确链接，且源目录未被复制为多份副本。卸载场景同时满足 CLI 注册表与目录残留的双重验收。

仅维护者查阅：清单来源与同步维护纪律

已验证可执行目标的权威来源不是本文档表格，而是已安装的 sync-local-global-agents-skills 技能内部的 src/platforms.ts。维护本技能时，通过当前 agent 的 skills 注册表、skills list 输出或当前全局 skills 根目录中的技能名称定位该技能目录；定位成功后读取其 src/platforms.ts，以 DEFAULT_PLATFORMS 为准确认当前可执行目标。不要把仓库源码相对路径、当前项目目录或 install-skills 自身目录的相对路径当作稳定运行时路径。

本文件中的“已验证可执行目标”表只是面向 agent 的可读摘要，不是第二份独立真理源。维护清单时必须遵守双向同步：

• 新增、删除或重命名已验证可执行目标时，先更新 sync-local-global-agents-skills/src/platforms.ts 的 DEFAULT_PLATFORMS，再同步更新本文档摘要。
• 只记录待验证 agent 时，不要改 DEFAULT_PLATFORMS；只能写在“生态入口与待验证候选”中，并保留核验条件。
• 本文档摘要与已定位同步技能中的 DEFAULT_PLATFORMS 不一致时，以 DEFAULT_PLATFORMS 为准，并立即修正文档漂移。
• 无法定位已安装的 sync-local-global-agents-skills，或其 src/platforms.ts 不存在时，停止宣称“已验证可执行目标”，先报告缺失依赖；本文档表格只能作为发布时快照辅助排查，不能作为运行时权威清单。