Claude Skill

skill-installation

审查、安装、配置、激活、验证、更新和回滚 AgentDock Skill 时使用；负责来源校验、安全评估、环境配置和已安装版本验收。

LLM Mart · 0 points · 7 0 0

Virus-scanned Reviewed automatically before listing.

Full trust report

Download uvwt-agentdock-core-skills_skill-installation-63791c8.zip · 9 KB

uvwt/agentdock 1005 121 forks Apache-2.0 Updated 10d ago

Part of uvwt/agentdock — 2 skills

Install

skills CLI npx skills add https://github.com/uvwt/agentdock/tree/main/core-skills/skill-installation

Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install uvwt-agentdock@llmmart

Git git clone https://github.com/uvwt/agentdock.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole uvwt/agentdock collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Skill Installation

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

何时使用

使用本 Skill 处理：

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

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

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

核心原则

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

标准流程

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 旧清单。

5. 检查环境变量需求

从 SKILL.md 中提取环境变量表，确认每个变量的：

名称；
config 或 secret 类型；
是否必填；
用途；
缺失时受影响的能力；
是否会出现在日志、请求或输出中。

环境值统一保存在：

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

不得在以下位置新建环境文件：

~/.agentdock/skill-data/<skill-name>/；
Skill 源码目录；
项目根目录；
包内辅助脚本旁；
任何 wrapper 专用目录。

使用：

skill_package env_list 查看变量名称和配置状态；
skill_package env_set 写入或更新用户明确提供的值；
skill_package env_unset 删除指定变量。

这些动作不应返回真实值。不要用手工散落环境文件代替正式工具。

6. 检查脚本和依赖

辅助脚本应满足：

stdin 输入是 JSON 对象；
顶层动作字段为 skill_action；
密钥只从注入环境读取；
不通过命令行参数接收秘密；
输出结构化 JSON；
错误包含明确 code 和 message；
status 默认只读；
写操作和破坏性动作有确认机制；
日志和错误不回显秘密。

对脚本做语法或编译检查，并运行包内测试。首次审查未知脚本时，只有静态审查通过后才允许在受控环境中运行只读检查。

7. 使用 skill_package validate

调用 skill_package validate 校验来源，必要时同时传入预期摘要。确认：

valid: true；
解析出的名称、描述和版本与审查结果一致；
返回摘要已记录；
没有结构化校验问题。

校验只证明包满足 AgentDock 基础结构和安装约束，不替代前面的安全审查。

8. 安装前汇报

正式安装前向用户说明：

来源和摘要；
Skill 名称和版本；
文件清单摘要；
风险等级和具体依据；
网络、文件、Shell、权限和数据行为；
外部依赖；
必填环境变量中尚未配置的名称；
是否存在无法验证的部分；
是否应在安装后立即激活。

low 和可解释的 medium 风险可按用户原始安装意图继续。high 风险必须获得明确确认。blocked 不得继续。

9. 安装和激活

使用 skill_package install，并遵循：

一个 Skill 可以安装多个版本，但任何时刻只有一个激活版本；
需要先审查或试运行新版时，可以只安装而不激活；
需要切换版本时使用 skill_package activate 显式激活已安装的目标版本；
默认激活时确认返回的 Activated 为真；
同名同版本不同内容不得覆盖；
更新时保留旧版本以支持回滚。

安装完成后记录安装结果中的名称、版本、摘要和激活状态。

10. 配置环境变量

只配置用户明确提供或已获授权迁移的值。流程：

skill_package env_list 获取当前配置状态；
列出缺失的必填变量名；
对每个变量调用 skill_package env_set；
再次 env_list，只核对 configured 状态；
不读取、展示或记录变量值。

配置动作与安装包版本分离。更新或回滚不应自动覆盖已有 Skill 环境。

11. 验证当前激活版本

至少验证：

skill_package install 返回成功并激活预期版本；
当前 Skill 状态中的 active_version 与预期一致；
agentdock_context 中出现正确名称和描述；
read_file skill://<name>/SKILL.md 可读取，并显示预期版本正文；
包内引用可通过 skill://<name>/... 读取；
当前已安装包摘要与审查时源码摘要一致；
skill_package env_list 显示必填配置完整；
没有旧版本错误路径或过期变量名；
日志和结果没有秘密。

不要只验证源码目录。skill:// 读取的是当前激活版本，是最终验收依据之一。

12. 运行只读状态检查

只有包包含辅助脚本和 status 能力时才执行：

使用 exec_command 的 skill: "<skill-name>" 绑定当前激活版本的包根目录和独立环境；
命令使用包内相对路径，例如 python3 run.py；
stdin 使用 {"skill_action":"status"}；
不手工解析安装版本目录，不主动读取或 source 环境文件；
不进行写入、删除、上传或权限修改；
检查输出是否结构化、可诊断且不泄露秘密。

纯文档 Skill 没有辅助脚本时，不虚构 status，以索引、正文、引用和环境状态验证为准。

13. 更新

更新前比较：

旧版本与新版本的 Frontmatter；
新增和删除文件；
网络目标、权限和依赖变化；
环境变量新增、删除或含义变化；
私有状态兼容性；
破坏性行为和确认规则；
摘要和发布来源。

对新版本完整执行审查、校验、安装和验收，不因旧版本已可信而跳过差异审查。

14. 回滚

使用 skill_package rollback 切换到上一已安装版本。回滚前确认旧版本仍存在，并说明回滚原因。

回滚后验证：

active_version 已切回预期版本；
skill://<name>/SKILL.md 读取的是回滚版本；
agentdock_context 描述与回滚版本一致；
新版本私有状态没有被误删；
~/.agentdock/env/skill/<skill-name>.env 没有被覆盖；
旧版本的必填环境变量仍完整；
有辅助脚本时只读 status 通过。

若新旧版本共享状态格式不兼容，先停止并报告，不擅自删除或迁移数据。

15. 卸载

使用 skill_package uninstall 管理已安装包：

不传 version 时卸载整个非内置 Skill，包括全部已安装版本和版本选择状态；
传 version 时只卸载指定版本；当前激活版本不能直接卸载，必须先显式激活其他版本；
内置 bundled Skill 不能卸载；
卸载不会自动切换激活版本；
卸载不会删除 ~/.agentdock/env/skill/<skill-name>.env 或 ~/.agentdock/skill-data/<skill-name>/，这些用户配置和运行数据需要独立管理。

卸载后确认目标版本或 Skill 已不再出现在已安装列表中；保留的环境配置和私有运行数据不得被误删。

环境变量

本 Skill 自身不需要环境变量。它只负责通过 skill_package 管理目标 Skill 的独立环境。

完成标准

只有同时满足以下条件才算完成：

来源、版本和摘要已记录；
安全审查有明确风险等级和证据；
没有 blocked 项；
skill_package validate 通过；
安装或回滚后的当前激活版本正确；
agentdock_context 和 skill:// 验证通过；
必填环境配置完整且未泄露值；
有辅助脚本时只读 status 通过；
环境和私有状态未被安装、更新或回滚错误覆盖。

Files (agentdock)

references

skill-security-review.md 8 KB

# AgentDock Skill 安全审查规范

本规范供 `skill-installation` 在安装、更新或回滚前后使用。审查结果必须基于真实文件和工具输出，不能只依据发布者说明。

## 1. 审查输出

至少记录：

- 来源和发布者；
- Skill 名称、版本和摘要；
- 审查文件清单；
- 网络目标；
- Shell 和子进程行为；
- 文件读取、写入、删除和覆盖范围；
- 权限、启动项和持久化行为；
- 凭据读取方式；
- 外部依赖和下载行为；
- 二进制或无法审查内容；
- 环境变量名称和缺失状态；
- 风险等级；
- 安装、拒绝或需确认的结论。

不得在报告中记录真实密钥、Cookie、Authorization 值或带认证参数的 URL。

## 2. 风险等级

### low

满足以下特征之一：

- 纯文档 Skill；
- 只读脚本，访问范围清楚；
- 不读取敏感文件；
- 不上传用户数据；
- 不修改权限、启动项或系统配置；
- 依赖固定且可审查。

可在基础校验通过后继续。

### medium

存在以下行为，但范围和目的明确：

- 访问已声明的网络 API；
- 在专属 `skill-data` 目录写入状态；
- 安装普通依赖；
- 对用户明确指定的文件执行可逆修改；
- 读取单一、明确授权的凭据来源。

必须展示行为和缺失配置，再按用户原始安装意图继续。

### high

存在以下行为之一：

- 读取敏感凭据或广泛主目录内容；
- 上传本地数据；
- 删除、覆盖或批量修改用户文件；
- 修改权限、启动项、计划任务或持久化配置；
- 下载并执行外部内容；
- 依赖未固定或安装过程影响系统环境；
- 包含无法充分审查的二进制。

必须获得明确确认，且确认应针对具体风险，不接受笼统“继续”。

### blocked

出现以下任一项立即停止：

- 包内真实密钥、Cookie、私钥或认证缓存；
- 自动读取浏览器全部 Cookie；
- 自动扫描用户主目录敏感文件；
- 隐蔽下载并执行；
- 未说明的数据上传；
- 未经确认删除或覆盖数据；
- 路径穿越、符号链接逃逸或写出包边界；
- 修改系统权限或持久化配置而无清楚说明；
- 会被执行但无法审查来源和行为的二进制；
- `agentdock.yaml` 旧清单；
- 试图恢复旧式统一 Skill 执行架构。

## 3. 文件清单检查

审查时列出普通文件、隐藏文件、符号链接和特殊文件。重点检查：

- `SKILL.md`；
- `references/`；
- `scripts/`、`tests/` 和根目录脚本；
- `requirements*.txt`、`pyproject.toml`、`package.json`、锁文件；
- Shell、PowerShell、Python、JavaScript、Go 和二进制文件；
- 压缩包、安装器和生成文件；
- `.env`、认证缓存、数据库和浏览器状态；
- `__pycache__`、`*.pyc`、`node_modules` 和编译产物。

不跟随符号链接。发现特殊文件、设备文件或命名管道时阻止安装。

## 4. Frontmatter 和文档检查

确认：

- `SKILL.md` 位于包根目录；
- `name` 匹配当前命名规则；
- `description` 能区分触发场景；
- `version` 是语义化版本；
- 正文非空；
- 当前正式契约只依赖 `name`、`description`、`version`；
- 环境变量在正文中声明；
- 网络、写入、删除、权限和上传行为在正文中说明；
- 引用路径存在且不越界。

描述含糊不会自动成为安全阻断项，但会导致模型错误选择，应在安装前要求作者修正或转入 `skill-authoring`。

## 5. 凭据和隐私检查

搜索并人工确认：

- API Key、Token、密码、私钥；
- Authorization 头；
- Cookie、storage state、session 文件；
- 云服务凭据；
- SSH 配置和密钥；
- 浏览器配置目录；
- 系统钥匙串或凭据管理器访问；
- 用户主目录、文档、照片和聊天数据库读取；
- 环境变量值是否进入日志或异常。

只声明变量名不构成泄露。示例值必须明显为占位符，不能具有真实凭据格式和可用性。

## 6. 网络行为检查

列出所有：

- 域名、IP 和端口；
- HTTP 方法；
- 上传内容；
- 下载内容；
- 重定向行为；
- 代理和 TLS 配置；
- 动态拼接 URL；
- WebSocket、回调和长连接。

特别关注：

- 将本地文件、日志、剪贴板或浏览器数据上传；
- 下载后直接执行；
- 绕过 TLS 校验；
- 允许任意用户输入 URL 后访问内网；
- 未限制重定向到非预期主机；
- 在 URL 查询参数中携带秘密。

## 7. Shell 和子进程检查

检查：

- `shell=True`、`eval`、反引号和动态命令拼接；
- 用户输入是否进入命令；
- 是否调用 `sudo`、`chmod`、`chown`、`launchctl`、`systemctl`、计划任务；
- 是否安装系统包或全局依赖；
- 是否运行远程脚本；
- 是否隐藏标准输出和错误；
- 是否忽略失败继续执行；
- 是否通过命令行参数传递秘密。

能使用参数数组时不要拼接 Shell 字符串。确需 Shell 时必须有严格输入约束和错误处理。

## 8. 文件系统检查

列出脚本可能访问的路径，判断：

- 是否限定在用户明确指定目录；
- 是否优先使用 `~/.agentdock/skill-data/<skill-name>/`；
- 是否写入源码目录或已安装包；
- 是否遍历整个主目录；
- 是否跟随符号链接；
- 是否允许 `..` 或绝对路径逃逸；
- 删除和覆盖是否有显式确认；
- 临时文件权限是否安全；
- 日志是否包含秘密。

安装、更新和回滚不得自动删除 `skill-data`。

## 9. 依赖和供应链检查

确认：

- 依赖名称和用途；
- 版本是否固定；
- 是否有锁文件；
- 安装范围是项目内、用户级还是系统级；
- 是否执行安装钩子；
- 是否从非官方源下载；
- 是否拉取分支最新内容而非固定提交；
- 是否下载二进制；
- 摘要或签名是否可验证。

未知或拼写近似的依赖需要重点审查。全局安装、远程安装脚本和未固定提交至少评为 `high`。

## 10. 旧式架构检查

搜索：

- `agentdock.yaml`；
- `skill_run`；
- `skill_env_manage`；
- `AGENTDOCK_OPERATION`；
- `PLUGIN_*`；
- 旧式 `operation`、`entrypoint` 清单；
- 统一 Skill 执行器或旧 Skill Runtime 目录和调用方式。

这些词出现在明确的禁止说明或迁移文档中可以接受；出现在可执行设计、清单或调用示例中应阻止安装。

## 11. 环境配置检查

从正文提取变量名，并通过 `skill_package env_list` 检查配置状态。要求：

- 值只保存在 `~/.agentdock/env/skill/<skill-name>.env`；
- 使用 `env_set`、`env_unset`、`env_list` 管理；
- `env_list` 不返回值；
- 安装包、源码和 `skill-data` 不包含环境文件；
- 更新和回滚不覆盖共享环境；
- 缺失必填变量时明确报告不可用能力。

## 12. 安装后验收

至少验证：

- 安装结果名称、版本、摘要和激活状态；
- 状态中的 `active_version`；
- `agentdock_context` 索引；
- `read_file skill://<name>/SKILL.md`；
- 至少一份包内引用；
- 已安装包摘要与审查摘要一致；
- 必填环境状态完整；
- 有辅助脚本时只读 `status`；
- 无秘密进入日志或结果。

纯文档 Skill 没有脚本时，不要求虚构运行检查。

## 13. 回滚验收

确认：

- 已切换到上一已安装版本；
- `skill://` 返回回滚版本正文；
- 索引描述与回滚版本一致；
- 新版本私有状态未删除；
- 环境配置未覆盖；
- 旧版本所需变量仍完整；
- 状态格式不兼容时已停止自动处理并报告。

## 14. 建议报告格式

```text
Skill: <name>
Version: <version>
Source: <safe source label>
Digest: <sha256>
Risk: low | medium | high | blocked

Reviewed:
- <files and areas>

Network:
- <targets and data>

Filesystem:
- <read/write/delete scope>

Credentials:
- <names and access method, never values>

Dependencies:
- <packages and install behavior>

Missing configuration:
- <variable names only>

Decision:
- install | install after confirmation | blocked

Verification:
- <validate/install/index/read/status results>
```

SKILL.md 11.4 KB

---
name: skill-installation
description: 审查、安装、配置、激活、验证、更新、回滚和卸载 AgentDock Skill 时使用；负责来源校验、安全评估、环境配置和已安装版本验收。
version: 1.2.1
---

# Skill Installation

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

## 何时使用

使用本 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` 旧清单。

### 5. 检查环境变量需求

从 `SKILL.md` 中提取环境变量表，确认每个变量的：

- 名称；
- `config` 或 `secret` 类型；
- 是否必填；
- 用途；
- 缺失时受影响的能力；
- 是否会出现在日志、请求或输出中。

环境值统一保存在：

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

不得在以下位置新建环境文件：

- `~/.agentdock/skill-data/<skill-name>/`；
- Skill 源码目录；
- 项目根目录；
- 包内辅助脚本旁；
- 任何 wrapper 专用目录。

使用：

- `skill_package env_list` 查看变量名称和配置状态；
- `skill_package env_set` 写入或更新用户明确提供的值；
- `skill_package env_unset` 删除指定变量。

这些动作不应返回真实值。不要用手工散落环境文件代替正式工具。

### 6. 检查脚本和依赖

辅助脚本应满足：

- stdin 输入是 JSON 对象；
- 顶层动作字段为 `skill_action`；
- 密钥只从注入环境读取；
- 不通过命令行参数接收秘密；
- 输出结构化 JSON；
- 错误包含明确 `code` 和 `message`；
- `status` 默认只读；
- 写操作和破坏性动作有确认机制；
- 日志和错误不回显秘密。

对脚本做语法或编译检查，并运行包内测试。首次审查未知脚本时，只有静态审查通过后才允许在受控环境中运行只读检查。

### 7. 使用 skill_package validate

调用 `skill_package validate` 校验来源，必要时同时传入预期摘要。确认：

- `valid: true`；
- 解析出的名称、描述和版本与审查结果一致；
- 返回摘要已记录；
- 没有结构化校验问题。

校验只证明包满足 AgentDock 基础结构和安装约束，不替代前面的安全审查。

### 8. 安装前汇报

正式安装前向用户说明：

- 来源和摘要；
- Skill 名称和版本；
- 文件清单摘要；
- 风险等级和具体依据；
- 网络、文件、Shell、权限和数据行为；
- 外部依赖；
- 必填环境变量中尚未配置的名称；
- 是否存在无法验证的部分；
- 是否应在安装后立即激活。

`low` 和可解释的 `medium` 风险可按用户原始安装意图继续。`high` 风险必须获得明确确认。`blocked` 不得继续。

### 9. 安装和激活

使用 `skill_package install`，并遵循：

- 一个 Skill 可以安装多个版本，但任何时刻只有一个激活版本；
- 需要先审查或试运行新版时，可以只安装而不激活；
- 需要切换版本时使用 `skill_package activate` 显式激活已安装的目标版本；
- 默认激活时确认返回的 `Activated` 为真；
- 同名同版本不同内容不得覆盖；
- 更新时保留旧版本以支持回滚。

安装完成后记录安装结果中的名称、版本、摘要和激活状态。

### 10. 配置环境变量

只配置用户明确提供或已获授权迁移的值。流程：

1. `skill_package env_list` 获取当前配置状态；
2. 列出缺失的必填变量名；
3. 对每个变量调用 `skill_package env_set`；
4. 再次 `env_list`，只核对 `configured` 状态；
5. 不读取、展示或记录变量值。

配置动作与安装包版本分离。更新或回滚不应自动覆盖已有 Skill 环境。

### 11. 验证当前激活版本

至少验证：

1. `skill_package install` 返回成功并激活预期版本；
2. 当前 Skill 状态中的 `active_version` 与预期一致；
3. `agentdock_context` 中出现正确名称和描述；
4. `read_file skill://<name>/SKILL.md` 可读取，并显示预期版本正文；
5. 包内引用可通过 `skill://<name>/...` 读取；
6. 当前已安装包摘要与审查时源码摘要一致；
7. `skill_package env_list` 显示必填配置完整；
8. 没有旧版本错误路径或过期变量名；
9. 日志和结果没有秘密。

不要只验证源码目录。`skill://` 读取的是当前激活版本，是最终验收依据之一。

### 12. 运行只读状态检查

只有包包含辅助脚本和 `status` 能力时才执行：

- 使用 `exec_command` 的 `skill: "<skill-name>"` 绑定当前激活版本的包根目录和独立环境；
- 命令使用包内相对路径，例如 `python3 run.py`；
- stdin 使用 `{"skill_action":"status"}`；
- 不手工解析安装版本目录，不主动读取或 `source` 环境文件；
- 不进行写入、删除、上传或权限修改；
- 检查输出是否结构化、可诊断且不泄露秘密。

纯文档 Skill 没有辅助脚本时，不虚构 `status`，以索引、正文、引用和环境状态验证为准。

### 13. 更新

更新前比较：

- 旧版本与新版本的 Frontmatter；
- 新增和删除文件；
- 网络目标、权限和依赖变化；
- 环境变量新增、删除或含义变化；
- 私有状态兼容性；
- 破坏性行为和确认规则；
- 摘要和发布来源。

对新版本完整执行审查、校验、安装和验收，不因旧版本已可信而跳过差异审查。

### 14. 回滚

使用 `skill_package rollback` 切换到上一已安装版本。回滚前确认旧版本仍存在，并说明回滚原因。

回滚后验证：

- `active_version` 已切回预期版本；
- `skill://<name>/SKILL.md` 读取的是回滚版本；
- `agentdock_context` 描述与回滚版本一致；
- 新版本私有状态没有被误删；
- `~/.agentdock/env/skill/<skill-name>.env` 没有被覆盖；
- 旧版本的必填环境变量仍完整；
- 有辅助脚本时只读 `status` 通过。

若新旧版本共享状态格式不兼容，先停止并报告，不擅自删除或迁移数据。

### 15. 卸载

使用 `skill_package uninstall` 管理已安装包：

- 不传 `version` 时卸载整个非内置 Skill，包括全部已安装版本和版本选择状态；
- 传 `version` 时只卸载指定版本；当前激活版本不能直接卸载，必须先显式激活其他版本；
- 内置 bundled Skill 不能卸载；
- 卸载不会自动切换激活版本；
- 卸载不会删除 `~/.agentdock/env/skill/<skill-name>.env` 或 `~/.agentdock/skill-data/<skill-name>/`，这些用户配置和运行数据需要独立管理。

卸载后确认目标版本或 Skill 已不再出现在已安装列表中；保留的环境配置和私有运行数据不得被误删。

## 环境变量

本 Skill 自身不需要环境变量。它只负责通过 `skill_package` 管理目标 Skill 的独立环境。

## 完成标准

只有同时满足以下条件才算完成：

- 来源、版本和摘要已记录；
- 安全审查有明确风险等级和证据；
- 没有 `blocked` 项；
- `skill_package validate` 通过；
- 安装或回滚后的当前激活版本正确；
- `agentdock_context` 和 `skill://` 验证通过；
- 必填环境配置完整且未泄露值；
- 有辅助脚本时只读 `status` 通过；
- 环境和私有状态未被安装、更新或回滚错误覆盖。