Skill Authoring

Skill Authoring

用于创建或维护 AgentDock Skill。Skill 的本体是模型可读取的说明文档；真实操作仍由命令、文件、浏览器、MCP 等工具完成。

AgentDock 不为 Skill 建立独立版本生命周期。Skill 的当前内容由来源与内容摘要识别；同名 managed Skill 更新时直接原子替换当前内容，不保留可选历史 revision，不提供 activate 或 rollback。

核心原则

1. 先定义模型何时应该选择该 Skill，再写正文。
2. Skill 核心应兼容 Agent Skills 的文档模型，不把 AgentDock 私有运行时当作通用契约。
3. 最小 Skill 只有一个 SKILL.md；只有确有需要时才增加 references/、脚本或测试。
4. 包内资源使用相对路径，业务环境变量由宿主注入当前进程。
5. 秘密、缓存、会话、数据库、下载结果和设备私有状态不得进入 Skill 包。
6. 修改后必须真实 lint、测试，并在需要时安装到 AgentDock 验证当前内容。
7. 不创建或恢复 Skill 自有版本选择、激活、回滚或历史 revision 机制。

完整规范见 references/skill-package-spec.md。

目录

普通第一方和社区 Skill 默认放在独立 Skill 仓库：

skills/<skill-name>/
└── SKILL.md

按需扩展：

skills/<skill-name>/
├── SKILL.md
├── references/
├── scripts/
├── run.py
└── tests/

只有必须随 AgentDock runtime 一起交付的核心 Skill 放在：

core-skills/<skill-name>/

不要创建空目录。

SKILL.md Frontmatter

AgentDock 使用 Agent Skills 风格的字段：

---
name: example-skill
description: 清楚说明何时使用、解决什么问题
license: Apache-2.0
compatibility: Requires Python 3.11 or later.
metadata:
  owner: example-team
allowed-tools: exec_command
---

# Example Skill

AgentDock 真正依赖并严格校验的只有：

• name 必填，长度 1–64，只允许小写 ASCII 字母、数字和 -，不能以 - 开头/结尾，也不能包含连续 --；
• description 必填，最长 1024 个 Unicode 字符，并能让模型稳定判断何时使用；重要的 Use when、Do not use 和相邻 Skill 边界条件不要依赖正文补充，因为模型会先用 description 做候选路由；
• Markdown 正文必须非空；
• 其他 frontmatter（包括 license、compatibility、metadata、allowed-tools、version 以及第三方扩展字段）由作者生态定义，AgentDock 原样保留但不作为安装/运行前提；
• 不设计 AgentDock 私有的 version、active_version、revision 或 rollback 契约。

AgentDock 路由索引

AgentDock 会先暴露轻量 description 索引，再按需读取完整 SKILL.md。不同来源的索引预算不同：

• standalone managed 与 Plugin-owned Skill：agentdock_context.skills 返回 trim 后的完整 description；
• workspace Skill：workspace_context.workspace_skills 返回 trim 后的完整 description，但最多列出 50 项；
• shared/common Skill：agentdock_context.common_skills 面向数量不可控的 ~/.agents/skills，最多列出 50 项，并把每项 description 限制在 120 bytes。

因此 authoring 时应把 description 视为路由契约，而不是正文摘要的随意前缀。AgentDock 不提供可配置的 description 截断上限；如果未来 Skill 总量显著增长，应通过索引总预算或检索式路由解决，而不是静默裁掉每个已管理 Skill 的 description 后半段。

可移植核心

目标 Skill 默认只假设：

• 当前进程能读取 Skill 包内容；
• 包内资源使用相对路径；
• 环境变量来自当前进程；
• 宿主提供命令、文件、浏览器或远端工具能力。

有根目录脚本时，通用示例写成：

printf '%s' '{"skill_action":"status"}' | python3 run.py

不要把以下内容作为核心运行前提：

• ~/.agentdock/skills/<name>；
• AGENTDOCK_HOME、AGENTDOCK_SKILL_DIR 等 AgentDock 私有路径变量；
• skill_ref、exec_command 或 skill://；
• 固定用户绝对路径；
• 主动读取或 source AgentDock 私有环境文件。

AgentDock 专属说明可以放在独立的“AgentDock 适配/验证”章节；删除该章节后，核心流程仍应成立。

环境变量

需要配置时，在正文中明确声明变量名、类型、必填性和用途：

## 环境变量

| 变量 | 类型 | 必填 | 说明 |
|---|---|---:|---|
| EXAMPLE_BASE_URL | config | 是 | 服务地址 |
| EXAMPLE_API_KEY | secret | 是 | API Key |

Skill 只声明变量，不保存真实值。辅助脚本只从当前进程环境读取。

AgentDock 本地验证时：

• skill_manage env_list 查看变量名称与配置状态；
• skill_manage env_set 写入用户明确提供的值；
• skill_manage env_unset 删除指定变量；
• exec_command skill_ref=<host-issued-ref> 运行时只把 managed Skill 环境注入对应子进程。

环境值不写入 AgentDock 主进程或系统全局环境。

需要持久可变状态时，不要写 Skill 包目录。AgentDock 对 standalone managed 与 Plugin-owned Skill 的 exec_command 都会提供独立运行时保留变量 SKILL_DATA_DIR：

• standalone managed 指向 ~/.agentdock/data/skills/<name>/；
• Plugin-owned 指向 ~/.agentdock/data/skills/.plugin/<plugin>/<skill>/，并额外获得 Plugin 共享兼容目录 PLUGIN_DATA_DIR=~/.agentdock/data/plugins/<plugin>/；
• 数据目录只在对应 Skill / Plugin 运行时真正需要时创建；
• Unix 权限收紧为 0700，Windows 使用当前用户私有 ACL；
• Windows 原生命令收到 Host 路径；WSL 命令收到已转换的 Linux 路径；
• skill_manage env_set、宿主 env mapping 和 request.env 都不能覆盖运行时保留变量；
• Plugin-owned Skill 的用户环境隔离在 ~/.agentdock/env/skill/plugin/<plugin>/<skill>.env；standalone 仍使用 ~/.agentdock/env/skill/<name>.env；
• shared/workspace 候选不会得到 SKILL_DATA_DIR 或 PLUGIN_DATA_DIR。

SKILL_DATA_DIR / PLUGIN_DATA_DIR 是 AgentDock 可选适配，不是 Agent Skills 通用前提。可移植 Skill 不应把它们列为用户必填配置；需要状态目录的辅助脚本可以在检测到它们时优先使用，并在其他宿主下采用自己明确声明的可移植策略。