skill-installation

Skill Installation

用于把本地或外部 Skill 安全地纳入当前 AgentDock，并验证当前激活版本确实可用。Skill 只提供审查和安装流程；真实读取、校验、配置、安装、命令执行和回滚由工具完成。

何时使用

使用本 Skill 处理：

• 安装本地或第三方 Skill；
• 审查未知 Skill 的代码、权限和数据行为；
• 配置已安装 Skill 的环境变量；
• 更新并激活新版本；
• 验证 Skill 是否已进入索引并可读取；
• 对当前激活版本运行只读状态检查；
• 回滚到上一已安装版本。

不要使用本 Skill 创建新 Skill、重写核心设计、替作者决定业务边界，或大范围修改第三方包。需要修改源码、补测试、升级文档或重新设计时，切换到 skill-authoring。

完整安全审查规范见 skill://skill-installation/references/skill-security-review.md。

核心原则

1. 先审查，后安装；不能把 skill_package validate 当作完整安全审计。
2. 来源、摘要、版本、风险和缺失配置必须可追溯。
3. 默认只读检查；写入、删除、上传、权限变化和依赖安装必须显式识别。
4. 不替用户生成、猜测或迁移真实秘密。
5. 环境变量只通过 AgentDock 的 Skill 独立环境管理能力配置。
6. 安装成功不等于可用；必须验证当前激活版本、索引、正文、引用和只读状态。
7. 回滚只切换已安装版本，不删除私有状态，也不覆盖共享环境配置。

标准流程

1. 识别来源

先记录：

• 来源类型：本地目录、本地压缩包或 HTTPS 下载地址；
• 来源位置和发布者；
• 目标 Skill 名称和版本；
• 用户期望安装、更新、验证还是回滚；
• 是否提供预期 SHA-256 摘要；
• 是否为首次接触的第三方包。

远程来源优先要求可信发布页和可验证摘要。URL 认证信息、查询参数和片段不得写入报告或日志。

2. 在安装前获取静态内容

在隔离的临时审查位置查看包，不直接从未知目录运行脚本。至少读取：

• 根目录文件清单；
• SKILL.md；
• references/；
• 所有脚本和测试；
• 依赖清单和锁文件；
• 包内二进制、压缩包或生成文件；
• 隐藏文件；
• 符号链接和特殊文件。

只读检查不应加载包内环境文件、不应执行安装钩子，也不应运行未知脚本。

3. 检查结构和 Frontmatter

确认：

• 包根目录存在 SKILL.md；
• Frontmatter 只依赖当前正式字段 name、description、version；
• name 稳定且与安装目标一致；
• description 能明确触发场景；
• version 是语义化版本；
• 正文非空；
• 包内引用路径存在且不越界；
• 没有符号链接逃逸、父目录穿越或绝对路径写入。

发现 agentdock.yaml、旧式统一执行协议或旧 Skill Runtime 设计时，至少标记为 blocked，不得直接安装。

4. 执行安全审查

逐项检查：

• 网络访问目标、协议和上传内容；
• Shell 命令和子进程；
• 文件系统读取、写入、覆盖和删除；
• 权限、启动项、计划任务和持久化变化；
• 凭据、Cookie、浏览器数据、SSH 配置和主目录敏感文件读取；
• 外部依赖安装；
• 下载后执行、动态代码加载和混淆代码；
• 二进制文件和无法审查的构件；
• 运行状态和秘密是否被打包；
• 日志、错误和返回值是否可能泄露秘密；
• 破坏性动作是否要求用户确认。

风险分类：

等级	含义	默认处理
low	纯文档或行为明确、只读、无敏感访问	可继续校验
medium	有明确网络、写入或普通依赖，但范围可解释	展示风险后继续
high	涉及敏感凭据、广泛文件访问、上传、删除或持久化	未经明确确认不安装
blocked	存在不可接受或无法解释的危险行为	停止安装

必须阻止：

• 包内真实密钥、Cookie、私钥或认证缓存；
• 自动读取浏览器全部 Cookie；
• 自动读取用户主目录敏感文件；
• 隐蔽下载并执行；
• 修改系统权限或持久化配置而未明确说明；
• 未经确认删除或覆盖数据；
• 未说明的外部上传；
• 路径穿越或符号链接逃逸；
• 无法审查且会被执行的二进制；
• agentdock.yaml 旧清单。