Skill Installation

用于把本地或外部 Skill 安全地纳入当前 AgentDock，并验证所选来源候选确实可用。

AgentDock 的 managed Skill 只有“当前内容”，没有独立版本选择、activate 或 rollback。更新同名 managed Skill 等价于审查新内容后原子替换当前目录；相同 content_digest 为 no-op。

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

核心原则

1. 先静态审查，后安装；安装器基础校验不能替代安全审查。
2. 来源、安全风险、source digest、content digest 和缺失配置必须可追溯。
3. 默认只读；写入、删除、上传、权限变化和依赖安装必须明确识别。
4. 不替用户生成、猜测或迁移真实秘密。
5. managed Skill 环境与包内容分离；更新当前内容不得覆盖环境或持久数据。
6. 同名不同来源是不同候选，运行时只使用宿主返回的精确 skill_ref。
7. 不通过历史版本、activate 或 rollback 恢复旧内容；需要恢复时重新安装一个经过审查的来源快照。

来源与身份

安装来源可以是：

• 本地目录；
• 本地 ZIP；
• HTTPS URL。

安装前记录安全来源标签；URL 中认证信息、query 和 fragment 不写入报告或日志。

Skill 的文档身份由 SKILL.md.name 给出。managed 安装目标是：

~/.agentdock/skills/<name>/

目录本身就是“已安装当前内容”的事实来源，不存在额外 active pointer 或 revision 目录。

Frontmatter

确认根目录 SKILL.md：

• name 存在并符合命名规则；
• description 非空且能表达触发场景；
• 正文非空；
• name 遵守 1, 64 字符、仅小写 ASCII 字母/数字/-、不首尾 -、不含连续 --；
• description 最长 1024 字符；
• 其他第三方 frontmatter 原样保留，不因 AgentDock 不认识字段或字段形状而拒绝安装；
• 未把 version、active_version、activate、rollback 当作 AgentDock Skill 生命周期。

发现 agentdock.yaml、旧统一执行协议或旧 Skill Runtime 设计时，停止安装并要求迁移。

静态安全审查

至少检查：

• 所有普通、隐藏、脚本、测试、依赖与锁文件；
• 网络目标、协议、上传数据和下载后执行；
• Shell/子进程和用户输入拼接；
• 文件读取、写入、覆盖、删除、路径穿越；
• 权限、启动项、计划任务和持久化；
• API Key、Token、Cookie、私钥、浏览器状态、SSH/云凭据；
• 外部依赖、安装钩子和二进制；
• 日志和异常是否泄露秘密；
• 破坏性动作是否要求用户确认；
• 符号链接与特殊文件。

风险分级：

等级	含义	默认处理
low	纯文档或行为明确且低风险	可继续
medium	有明确网络、写入或普通依赖	展示风险后继续
high	涉及敏感数据、广泛访问、删除或持久化	需明确确认
blocked	危险行为不可接受或无法解释	停止

环境变量

从正文提取变量名、类型、必填性与用途。

standalone managed Skill 使用：

~/.agentdock/env/skill/<skill-name>.env
~/.agentdock/data/skills/<skill-name>/

Plugin-owned Skill 使用精确 skill_ref 管理独立环境和数据：

~/.agentdock/env/skill/plugin/<plugin>/<skill>.env
~/.agentdock/data/skills/.plugin/<plugin>/<skill>/

通过 skill_manage env_list/env_set/env_unset 管理环境；工具不会返回真实值。