skill-authoring · diff
v1.2.0 to git:20260922.174237a
125 added, 235 removed. Audit A to A.
---
name: skill-authoring
- description: 创建、设计、修改、升级、重构和验证 AgentDock Skill 时使用；负责可移植核心、文档、引用、辅助脚本、测试、版本和本地安装验证。
- version: 1.2.0
+ description: 创建、设计、修改、重构和验证 AgentDock Skill 时使用；负责 Agent Skills 兼容的 SKILL.md、可移植核心、引用、辅助脚本、测试、安全边界和本地真实验证。
---
# Skill Authoring
- 用于创建或维护 AgentDock 第一方 Skill。Skill 的本体是模型可读取的说明文档；工具负责真实检查、编辑、命令执行、打包、安装和验证。
-
- 目标 Skill 应由两部分构成：
-
- ```text
- 可移植核心契约
- +
- 可选的宿主适配说明
- ```
-
- 移除 AgentDock 专属适配说明后，Skill 的业务流程、包内引用、环境变量契约和辅助脚本仍应完整可用。
-
- ## 何时使用
-
- 使用本 Skill 处理：
-
- - 创建新的第一方 Skill；
- - 修改、重构或升级现有 Skill；
- - 调整触发描述、正文流程、引用资料或辅助脚本；
- - 补充测试、示例、安全约束和可移植性检查；
- - 递增版本并完成源码侧与当前激活版本验证。
+ 用于创建或维护 AgentDock Skill。Skill 的本体是模型可读取的说明文档；真实操作仍由命令、文件、浏览器、MCP 等工具完成。
- 不要使用本 Skill 处理第三方 Skill 的正式安全审查、真实凭据配置或已安装版本回滚。这些属于 `skill-installation`。
+ AgentDock 不为 Skill 建立独立版本生命周期。Skill 的当前内容由来源与内容摘要识别；同名 managed Skill 更新时直接原子替换当前内容，不保留可选历史 revision，不提供 activate 或 rollback。
## 核心原则
1. 先定义模型何时应该选择该 Skill，再写正文。
- 2. Skill 只描述方法、边界和工具选择，不承担统一执行职责。
- 3. Skill 核心契约必须与宿主无关；包内文件使用相对路径，环境由运行宿主注入。
- 4. 简单 Skill 优先只有一份 `SKILL.md`；只有确有需要时才增加引用、脚本或测试。
- 5. 修改正文、引用、脚本或行为后必须递增语义化版本。
- 6. 同名同版本内容必须保持不可变。
- 7. 环境值、设备状态和运行数据不得进入 Skill 包。
- 8. 所有验证都要落到当前已安装并激活的版本，不能只看源码目录。
- 9. 第一方 Skill 必须通过本 Skill 的 `lint`，不能只通过包安装校验。
-
- 完整规范见包内 `references/skill-package-spec.md`。
-
- ## 标准流程
-
- ### 1. 理解需求和触发条件
-
- 先明确：
-
- - 用户真正要解决的问题；
- - 模型在什么请求下应选择该 Skill；
- - 哪些相邻任务不属于该 Skill；
- - 需要调用哪些真实工具；
- - 是否需要辅助脚本、引用资料或测试；
- - 是否涉及网络、写入、删除、凭据或高风险动作。
-
- 不要用“管理某能力全生命周期”这类宽泛描述。`description` 必须让模型能稳定判断何时选中它。
-
- ### 2. 确定职责边界
-
- 正文至少说明：
-
- - 适用场景和不适用场景；
- - 读取或修改的对象；
- - 默认只读行为；
- - 写操作和破坏性操作的确认规则；
- - 失败时需要返回的证据。
-
- 一个 Skill 应围绕一个稳定能力边界组织。需求已经跨越独立职责时，应拆成多个 Skill。
-
- ### 3. 创建源码目录
-
- 普通第一方和社区 Skill 默认放在独立的 `agentdock-skills` 仓库：
-
- ```text
- skills/<skill-name>/
- ```
+ 2. Skill 核心应兼容 Agent Skills 的文档模型，不把 AgentDock 私有运行时当作通用契约。
+ 3. 最小 Skill 只有一个 `SKILL.md`；只有确有需要时才增加 `references/`、脚本或测试。
+ 4. 包内资源使用相对路径，业务环境变量由宿主注入当前进程。
+ 5. 秘密、缓存、会话、数据库、下载结果和设备私有状态不得进入 Skill 包。
+ 6. 修改后必须真实 lint、测试，并在需要时安装到 AgentDock 验证当前内容。
+ 7. 不创建或恢复 Skill 自有版本选择、激活、回滚或历史 revision 机制。
- 只有随 AgentDock 安装包自举、与运行时版本强绑定的核心 Skill 才放在 AgentDock 主仓库：
+ 完整规范见 `references/skill-package-spec.md`。
- ```text
- core-skills/<skill-name>/
- ```
+ ## 目录
- 按需选择结构：
+ 普通第一方和社区 Skill 默认放在独立 Skill 仓库：
```text
skills/<skill-name>/
└── SKILL.md
```
+ 按需扩展：
+
```text
skills/<skill-name>/
├── SKILL.md
├── references/
├── scripts/
+ ├── run.py
└── tests/
```
+ 只有必须随 AgentDock runtime 一起交付的核心 Skill 放在：
+
```text
- skills/<skill-name>/
- ├── SKILL.md
- ├── run.py
- └── tests/
+ core-skills/<skill-name>/
```
- 不要为了形式创建空目录，也不要把普通集成重新放回 AgentDock 主仓库。
+ 不要创建空目录。
- ### 4. 编写 Frontmatter
+ ## SKILL.md Frontmatter
- 当前 AgentDock 正式解析：
+ AgentDock 使用 Agent Skills 风格的字段：
```yaml
---
name: example-skill
description: 清楚说明何时使用、解决什么问题
- version: 1.0.0
+ license: Apache-2.0
+ compatibility: Requires Python 3.11 or later.
+ metadata:
+ owner: example-team
+ allowed-tools:
+ - exec_command
---
+
+ # Example Skill
```
要求：
- - `name` 使用稳定、简短、全小写的连字符名称；
- - `description` 同时覆盖触发场景和能力边界；
- - `version` 使用语义化版本；
- - Frontmatter 后必须有非空 Markdown 正文；
- - 不增加当前解析器未支持的环境变量或执行字段。
+ - `name` 必填，匹配 `^[a-z][a-z0-9-]{1,62}$`；
+ - `description` 必填，并能让模型稳定判断何时使用；
+ - Markdown 正文必须非空；
+ - `license`、`compatibility`、`metadata`、`allowed-tools` 为可选；
+ - `metadata.version` 若作者需要可以作为普通元数据存在，但 AgentDock 不把它当安装身份、升级依据或运行时版本；
+ - 不设计 AgentDock 私有的 `version`、`active_version`、revision 或 rollback 契约。
- ### 5. 编写可移植核心
+ ## 可移植核心
- 目标 Skill 的正文和脚本默认只假设：
+ 目标 Skill 默认只假设：
- - 当前工作目录是 Skill 包根目录；
- - 包内资源可通过相对路径访问；
- - 环境变量来自当前进程环境；
- - 运行宿主负责选择工具、切换目录和注入环境；
- - 不依赖 AgentDock 的安装目录、状态目录或专属变量。
+ - 当前进程能读取 Skill 包内容；
+ - 包内资源使用相对路径；
+ - 环境变量来自当前进程；
+ - 宿主提供命令、文件、浏览器或远端工具能力。
- 有根目录脚本时，通用执行示例应写成：
+ 有根目录脚本时，通用示例写成：
```bash
printf '%s' '{"skill_action":"status"}' | python3 run.py
```
- 不得把以下内容作为核心运行前提：
+ 不要把以下内容作为核心运行前提：
- - `~/.agentdock/skill-store/installed/...`；
- - 固定安装版本号；
- - `AGENTDOCK_DIR`、`AGENTDOCK_HOME` 或 `AGENTDOCK_SKILL_DIR` 用于定位包内脚本或私有数据；
- - `skill_env`、`exec_command` 或 `skill://`；
+ - `~/.agentdock/skills/<name>`；
+ - `AGENTDOCK_HOME`、`AGENTDOCK_SKILL_DIR` 等 AgentDock 私有路径变量；
+ - `skill_ref`、`exec_command` 或 `skill://`；
- 固定用户绝对路径；
- - 主动读取或 `source` AgentDock 私有环境文件。
+ - 主动读取或 source AgentDock 私有环境文件。
- AgentDock 工具调用可以出现在单独的“AgentDock 适配/验证”说明中，但删除该部分后，Skill 仍必须可用。
+ AgentDock 专属说明可以放在独立的“AgentDock 适配/验证”章节；删除该章节后，核心流程仍应成立。
- ### 6. 声明环境变量
+ ## 环境变量
- 每个需要配置的目标 Skill 都必须在正文中明确声明变量：
+ 需要配置时，在正文中明确声明变量名、类型、必填性和用途：
```markdown
## 环境变量
| 变量 | 类型 | 必填 | 说明 |
|---|---|---:|---|
| EXAMPLE_BASE_URL | config | 是 | 服务地址 |
| EXAMPLE_API_KEY | secret | 是 | API Key |
```
- 类型至少区分 `config` 和 `secret`，并说明缺失变量时哪些能力不可用。
+ Skill 只声明变量，不保存真实值。辅助脚本只从当前进程环境读取。
- 目标 Skill 只声明变量名和用途，不声明 AgentDock 私有保存路径，不保存真实值。辅助脚本只从当前进程环境读取变量。
+ AgentDock 本地验证时：
- 在 AgentDock 本地验证时，环境值由 `skill_package env_set/env_unset/env_list` 管理，并由 `exec_command` 的 `skill` 上下文注入本次子进程。环境不会写入 AgentDock 主进程或系统环境。
+ - `skill_manage env_list` 查看变量名称与配置状态；
+ - `skill_manage env_set` 写入用户明确提供的值；
+ - `skill_manage env_unset` 删除指定变量；
+ - `exec_command skill_ref=<host-issued-ref>` 运行时只把 managed Skill 环境注入对应子进程。
- ### 7. 编写引用资料
+ 环境值不写入 AgentDock 主进程或系统全局环境。
- 适合放入 `references/` 的内容包括：
+ 需要持久可变状态时，不要写 Skill 包目录。AgentDock 对 **managed** Skill 的 `exec_command` 会提供运行时保留变量 `SKILL_DATA_DIR`：
- - 稳定协议说明；
- - 较长检查清单；
- - API 字段或错误码表；
- - 不需要每次完整加载的背景资料。
+ - 指向 `~/.agentdock/data/skills/<name>/` 对应的私有持久目录；
+ - 目录只在 managed Skill 真正执行时创建；
+ - Unix 权限收紧为 `0700`，Windows 使用当前用户私有 ACL；
+ - Windows 原生命令收到 Host 路径；WSL 命令收到已转换的 Linux 路径；
+ - `skill_manage env_set`、宿主 env mapping 和 `request.env` 都不能覆盖；
+ - shared/workspace 同名候选不会得到 managed Skill 的 `SKILL_DATA_DIR`。
- 目标 `SKILL.md` 使用包内相对路径，例如：
+ `SKILL_DATA_DIR` 是 AgentDock 可选适配，不是 Agent Skills 通用前提。可移植 Skill 不应把它列为用户必填配置；需要状态目录的辅助脚本可以在检测到它时优先使用，并在其他宿主下采用自己明确声明的可移植策略。
+ ## 引用与辅助脚本
+
+ 正文引用包内文件时使用相对路径，例如：
+
```text
references/api.md
```
- 不要把 `skill://<name>/...` 写成核心引用契约，也不要依赖另一个 Skill 的安装目录。AgentDock 在验证当前激活包时可通过 `read_file skill://<name>/...` 读取资源。
-
- ### 8. 编写辅助脚本
-
- 辅助脚本只是可选资源，不是 Skill 本体。需要脚本时：
+ 辅助脚本应：
- - 输入使用 stdin JSON 对象；
- - 顶层动作字段统一使用 `skill_action`；
- - 密钥只从当前进程环境读取；
- - 不通过命令行参数传递秘密；
+ - 通过 stdin 接收 JSON 对象；
+ - 顶层动作字段使用 `skill_action`；
+ - secret 只从环境读取；
- 输出结构化 JSON；
- 错误返回稳定 `code` 和可读 `message`；
- - 状态检查优先只读；
- - 写操作遵守用户确认规则；
- - 日志和错误不得回显秘密；
- - 包内文件使用相对路径或基于脚本自身目录定位。
-
- 推荐输入：
-
- ```json
- {
- "skill_action": "status"
- }
- ```
-
- 通用执行在 Skill 包根目录运行：
-
- ```bash
- python3 run.py
- ```
-
- AgentDock 验证时使用 `exec_command` 的 `skill: "<skill-name>"` 绑定当前激活目录与独立环境，不手工解析版本目录。
+ - 默认状态检查只读；
+ - 破坏性动作要求明确确认；
+ - 不回显 secret；
+ - 用相对路径或脚本目录定位包内只读资源；
+ - 可变缓存、数据库、会话和下载结果不得写回 Skill 包；在 AgentDock managed 运行时优先写入 `SKILL_DATA_DIR`。
- ### 9. 运行可移植性 lint
+ ## Authoring lint
本 Skill 的 `run.py` 提供：
- - `status`：报告 lint 版本和规则数量；
- - `lint`：检查目标 Skill 的可移植核心和宿主绑定问题。
+ - `status`：返回 `lint_version` 与规则数量；
+ - `lint`：检查可移植性和明显宿主绑定。
- 输入示例：
+ 示例：
```json
{
"skill_action": "lint",
- "source": "/path/to/agentdock-skills/skills/example-skill"
+ "source": "/path/to/skills/example-skill"
}
```
- 结果包含：
-
- - `portable`；
- - `error_count`；
- - `warning_count`；
- - 每条 issue 的 `code`、`severity`、文件、行号、说明和修复建议。
-
- 硬编码已安装版本目录、依赖 AgentDock 专属目录变量、主动读取 AgentDock 环境文件和固定用户绝对路径属于 error。AgentDock 专属工具或 URI 出现在目标 `SKILL.md` 中属于 warning，需要确认它们只存在于可选适配说明。
-
- 对已安装目录运行 lint 时，会忽略包根目录下由 AgentDock 安装器生成的 `.agentdock-install.json`。该文件属于宿主安装回执，不是 Skill 包内容；同名文件出现在包内其他目录时仍会正常扫描。
-
- 在 AgentDock 中，安装新版 `skill-authoring` 后可这样运行：
-
- ```text
- exec_command
- skill: skill-authoring
- cmd: python3 run.py
- stdin: {"skill_action":"lint","source":"/path/to/source"}
- ```
-
- 创建或修改第一方 Skill 时，`portable` 必须为 `true`；warning 必须逐项修复或说明为什么属于可选宿主适配。
-
- ### 10. 编写测试
-
- 测试覆盖真实风险，至少考虑：
-
- - Frontmatter 和正文可解析；
- - 输入不是 JSON 对象时明确失败；
- - 未知 `skill_action` 明确失败；
- - 缺失环境变量时只报告变量名，不泄露值；
- - 只读状态检查不产生写入；
- - 破坏性动作缺少确认时拒绝；
- - 日志和错误不包含秘密；
- - 平台或依赖缺失时返回可诊断信息；
- - 包从根目录使用相对命令运行；
- - 脚本不依赖 AgentDock 私有目录。
-
- ### 11. 安全和质量检查
-
- 提交前检查：
-
- - 包内没有真实密码、Token、Cookie、认证缓存或会话文件；
- - 没有 `.env`、缓存、数据库、截图、下载文件和运行结果；
- - 没有 `__pycache__`、`*.pyc`、`node_modules` 或编译产物；
- - 没有固定用户绝对路径、符号链接或路径逃逸；
- - 没有旧式统一执行协议、旧式环境工具示例或旧清单；
- - 网络目标、文件写入、删除、上传和权限变化均被明确说明；
- - 依赖安装不会被隐藏执行。
+ 硬错误包括：
- 明确禁止生成或恢复：
+ - 硬编码 AgentDock managed Skill 安装目录；
+ - 依赖 AgentDock 私有目录变量；
+ - 主动读取 AgentDock 环境文件；
+ - 固定用户绝对路径。
- - `agentdock.yaml`；
- - `skill_run`；
- - `skill_env_manage`；
- - `AGENTDOCK_OPERATION`；
- - `PLUGIN_*` 旧协议；
- - 旧式 `operation` 或 `entrypoint` 清单；
- - 统一 Skill 执行器或旧 Skill Runtime。
+ AgentDock 专属 `skill_ref`、`exec_command`、`skill://` 出现在目标 `SKILL.md` 中会作为 warning，要求确认它们只存在于可选宿主适配说明。
- 设备私有状态和 AgentDock 环境值只属于宿主，不进入包。
+ ## 安全与质量检查
- ### 12. 递增版本
+ 提交前至少检查：
- - 只修正文错字且不影响行为判断，可递增补丁版本；
- - 新增兼容能力、变量、动作或引用，递增次版本；
- - 改变职责边界、移除既有能力或引入不兼容流程，递增主版本。
+ - 无真实密码、Token、Cookie、私钥和认证缓存；
+ - 无 `.env`、数据库、截图、下载结果、`__pycache__`、`node_modules` 等运行产物；
+ - 无符号链接、路径逃逸、固定用户绝对路径；
+ - 网络、写入、删除、上传、权限变化和依赖安装均有明确说明；
+ - 未恢复 `agentdock.yaml`、`skill_run`、`skill_env_manage`、旧式 operation/entrypoint 清单或统一 Skill Runtime；
+ - 不把安装历史、激活版本或回滚机制重新写回 Skill。
- 安装前比较当前已安装版本和新源码。不得用相同版本覆盖不同内容。
+ ## AgentDock 本地验证
- ### 13. 验证和本地安装
+ AgentDock 的 managed Skill 当前布局是：
- 至少完成：
+ ```text
+ ~/.agentdock/skills/<name>/
+ SKILL.md
+ ...
+ ```
- 1. 检查目录和 Frontmatter；
- 2. 检查版本正确递增；
- 3. 检查禁止文件、符号链接和真实 secret；
- 4. 对辅助脚本执行语法检查和自带测试；
- 5. 运行 `skill-authoring lint`，确认 `portable=true` 并审查 warning；
- 6. 使用 `skill_package validate` 校验包级合法性；
- 7. 使用 `skill_package install` 安装并激活；
- 8. 通过 `agentdock_context` 验证名称和描述进入轻量索引；
- 9. 通过 `read_file skill://<name>/SKILL.md` 验证当前激活正文；
- 10. 有引用时读取至少一份引用；
- 11. 有辅助脚本时，用 `exec_command skill=<name>` 对当前激活版本运行只读 `status`；
- 12. 运行一个代表性低风险动作，无法运行时记录真实原因。
+ 这个目录是宿主实现细节，不应硬编码进目标 Skill。
- `skill_package validate` 负责包能否合法安装；本 Skill 的 `lint` 负责第一方创作质量和可移植性，两者不能互相替代。
+ 建议验证流程：
- ## 环境变量
+ 1. 检查目录、Frontmatter 和正文；
+ 2. 检查禁止文件、符号链接和真实 secret；
+ 3. 对辅助脚本做语法检查和自带测试；
+ 4. 运行 `skill-authoring lint`，确认 `portable=true`；
+ 5. 使用 `skill_manage install` 从本地目录、压缩包或 HTTPS 来源安装；
+ 6. 记录返回的 `content_digest`；相同内容重复安装应为 no-op；
+ 7. 通过 `agentdock_context` 找到该候选，并保存它返回的 `skill_ref` 与 `file`；
+ 8. 用 `read_file` 读取宿主返回的 `file`，不要自己按名称重建 URI；
+ 9. 有辅助脚本时，用同一候选的 `skill_ref` 调用 `exec_command` 做只读检查；
+ 10. 修改内容后再次安装，确认当前内容被原子替换且环境/数据未被清空。
- 本 Skill 自身不需要环境变量。它要求被编写的目标 Skill 声明业务变量，并由运行宿主注入当前子进程。
+ managed、shared、workspace 中同名 Skill 是不同候选。验证时始终使用宿主返回的精确 `skill_ref`，不得靠裸名称重新解析。
## 完成标准
只有同时满足以下条件才算完成：
- - 描述可稳定触发且边界清楚；
+ - description 可稳定触发且职责边界清楚；
+ - Frontmatter 与 Agent Skills 文档模型兼容；
- 可移植核心不依赖 AgentDock 私有目录或工具参数；
- - 包内脚本可从 Skill 根目录使用相对路径运行；
- - `skill-authoring lint` 返回 `portable=true`，warning 已逐项处理；
- - 安全检查、测试和 `skill_package validate` 通过；
- - 新版本已安装并激活；
- - `agentdock_context` 和 `skill://` 读取的是新版本；
- - 当前激活版本的真实只读验证通过；
- - 没有秘密、设备私有状态或旧式架构回流。
+ - 包内脚本可从 Skill 根目录按相对路径运行；
+ - lint、测试和安全检查通过；
+ - managed 安装时有有效 `content_digest`，重复相同内容为 no-op；
+ - `agentdock_context` 返回正确来源、`skill_ref` 与 `file`；
+ - 当前内容和代表性只读行为已真实验证；
+ - 没有 Skill 自有版本选择、激活、回滚或历史 revision 语义。