# Skill Installation

审查、安装、配置、验证、更新和移除 AgentDock Skill 时使用；负责来源校验、安全评估、环境配置、content digest、精确 skill_ref 与当前...

- Repository: https://github.com/uvwt/agentdock (1293 stars)
- Category: Engineering
- License: Apache-2.0
- Last updated: 2026-10-27
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add uvwt/agentdock --skill skill-installation -g -a claude-code -y`
Codex: `npx skills add uvwt/agentdock --skill skill-installation -g -a codex -y`
Cursor: `npx skills add uvwt/agentdock --skill skill-installation -g -a cursor -y`
Gemini CLI: `npx skills add uvwt/agentdock --skill skill-installation -g -a gemini-cli -y`

## Description

审查、安装、配置、验证、更新和移除 AgentDock Skill 时使用；负责来源校验、安全评估、环境配置、content digest、精确 skill_ref 与当前 managed 内容验收。

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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 安装目标是：

```text
~/.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 使用：

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

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

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

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

The rest: https://github.com/uvwt/agentdock/blob/HEAD/core-skills/skill-installation/SKILL.md