skill-installation

1# Skill Installation
2 
3用于把本地或外部 Skill 安全地纳入当前 AgentDock，并验证所选来源候选确实可用。
4 
5AgentDock 的 managed Skill 只有“当前内容”，没有独立版本选择、activate 或 rollback。更新同名 managed Skill 等价于审查新内容后原子替换当前目录；相同 `content_digest` 为 no-op。
6 
7完整安全审查规范见包内 `references/skill-security-review.md`。
8 
9## 核心原则
10 
111. 先静态审查，后安装；安装器基础校验不能替代安全审查。
122. 来源、安全风险、source digest、content digest 和缺失配置必须可追溯。
133. 默认只读；写入、删除、上传、权限变化和依赖安装必须明确识别。
144. 不替用户生成、猜测或迁移真实秘密。
155. managed Skill 环境与包内容分离；更新当前内容不得覆盖环境或持久数据。
166. 同名不同来源是不同候选，运行时只使用宿主返回的精确 `skill_ref`。
177. 不通过历史版本、activate 或 rollback 恢复旧内容；需要恢复时重新安装一个经过审查的来源快照。
18 
19## 来源与身份
20 
21安装来源可以是：
22 
23- 本地目录；
24- 本地 ZIP；
25- HTTPS URL。
26 
27安装前记录安全来源标签；URL 中认证信息、query 和 fragment 不写入报告或日志。
28 
29Skill 的文档身份由 `SKILL.md.name` 给出。managed 安装目标是：
30 
31```text
32~/.agentdock/skills/<name>/
33```
34 
35目录本身就是“已安装当前内容”的事实来源，不存在额外 active pointer 或 revision 目录。
36 
37## Frontmatter
38 
39确认根目录 `SKILL.md`：
40 
41- `name` 存在并符合命名规则；
42- `description` 非空且能表达触发场景；
43- 正文非空；
44- `name` 遵守 1–64 字符、仅小写 ASCII 字母/数字/`-`、不首尾 `-`、不含连续 `--`；
45- `description` 最长 1024 字符；
46- 其他第三方 frontmatter 原样保留，不因 AgentDock 不认识字段或字段形状而拒绝安装；
47- 未把 `version`、`active_version`、activate、rollback 当作 AgentDock Skill 生命周期。
48 
49发现 `agentdock.yaml`、旧统一执行协议或旧 Skill Runtime 设计时，停止安装并要求迁移。
50 
51## 静态安全审查
52 
53至少检查：
54 
55- 所有普通、隐藏、脚本、测试、依赖与锁文件；
56- 网络目标、协议、上传数据和下载后执行；
57- Shell/子进程和用户输入拼接；
58- 文件读取、写入、覆盖、删除、路径穿越；
59- 权限、启动项、计划任务和持久化；
60- API Key、Token、Cookie、私钥、浏览器状态、SSH/云凭据；
61- 外部依赖、安装钩子和二进制；
62- 日志和异常是否泄露秘密；
63- 破坏性动作是否要求用户确认；
64- 符号链接与特殊文件。
65 
66风险分级：
67 
68| 等级 | 含义 | 默认处理 |
69|---|---|---|
70| low | 纯文档或行为明确且低风险 | 可继续 |
71| medium | 有明确网络、写入或普通依赖 | 展示风险后继续 |
72…