# 仓颉 Skill 安装规范

这份文档供 Agent 读取。用户会同时提供 Skill 名称、来源仓库，以及可能存在的仓库内路径。

## 目标

根据当前 Agent 和工作环境，安全地把目标 Skill 安装到能够被识别的 Skills 目录，并向用户报告安装结果。不要要求用户自己判断目录或手动复制文件。

## 一、判断安装位置

先识别当前正在运行的 Agent，再选择对应目录：

- Codex：全局 `~/.codex/skills/`；项目级 `<project>/.agents/skills/`
- Claude Code：`~/.claude/skills/`
- Cursor：`~/.cursor/skills/`
- Windsurf：`~/.codeium/windsurf/skills/` 或项目级 `.windsurf/skills/`
- Gemini CLI：`~/.gemini/skills/`
- QoderWork：`~/.qoderwork/skills/`
- WorkBuddy：`~/.workbuddy/skills/`
- 其他 Agent：检查其官方配置或当前环境中的 Skills 目录

用户明确要求安装到当前项目时，优先使用项目级目录；否则使用当前 Agent 的全局目录。已经能从当前环境确认时，不要反问用户。

## 二、检查来源

1. 确认来源 URL 可访问，并记录仓库和当前版本或 commit。
2. 在临时目录下载或克隆来源，不要直接覆盖已有 Skill。
3. 阅读 README、SKILL.md 和安装说明。
4. 检查可疑脚本、外部下载、密钥要求和同名目录冲突。
5. 遇到需要执行未审查脚本、覆盖本地修改、索取凭证或提升权限时，先向用户说明风险并请求确认。

## 三、识别并安装

1. 在指定来源或仓库内路径中查找所有 `SKILL.md`。
2. 每个包含 `SKILL.md` 的目录视为一个可安装 Skill；复制该目录及其引用的脚本、模板和资源，保持相对路径不变。
3. 不复制 `.git/`、构建缓存、原始大型素材、`.env`、密钥和无关文件。
4. 将 Skill 安装到第一节确定的目录。若同名 Skill 已存在：
   - 内容和版本一致：跳过并说明；
   - 可以安全升级：保留必要的本地配置后更新；
   - 存在本地修改或不确定：停止覆盖并询问用户。

## 四、验证

安装后完成以下检查：

1. 确认目标目录内存在可读取的 `SKILL.md`。
2. 检查 Skill 的名称、描述和触发条件是否能被当前 Agent 识别。
3. 如果当前 Agent 需要重新扫描，提示用户开启新会话或执行必要的重新加载操作。
4. 最终报告：来源、安装目录、安装或更新的 Skill 列表、跳过项、风险提示和验证结果。

安装成功后，不要立刻执行 Skill 所描述的业务任务，除非用户同时提出了该任务。