skill-authoring

1# Skill Authoring
2 
3用于创建或维护 AgentDock Skill。Skill 的本体是模型可读取的说明文档；真实操作仍由命令、文件、浏览器、MCP 等工具完成。
4 
5AgentDock 不为 Skill 建立独立版本生命周期。Skill 的当前内容由来源与内容摘要识别；同名 managed Skill 更新时直接原子替换当前内容，不保留可选历史 revision，不提供 activate 或 rollback。
6 
7## 核心原则
8 
91. 先定义模型何时应该选择该 Skill，再写正文。
102. Skill 核心应兼容 Agent Skills 的文档模型，不把 AgentDock 私有运行时当作通用契约。
113. 最小 Skill 只有一个 `SKILL.md`；只有确有需要时才增加 `references/`、脚本或测试。
124. 包内资源使用相对路径，业务环境变量由宿主注入当前进程。
135. 秘密、缓存、会话、数据库、下载结果和设备私有状态不得进入 Skill 包。
146. 修改后必须真实 lint、测试，并在需要时安装到 AgentDock 验证当前内容。
157. 不创建或恢复 Skill 自有版本选择、激活、回滚或历史 revision 机制。
16 
17完整规范见 `references/skill-package-spec.md`。
18 
19## 目录
20 
21普通第一方和社区 Skill 默认放在独立 Skill 仓库：
22 
23```text
24skills/<skill-name>/
25└── SKILL.md
26```
27 
28按需扩展：
29 
30```text
31skills/<skill-name>/
32├── SKILL.md
33├── references/
34├── scripts/
35├── run.py
36└── tests/
37```
38 
39只有必须随 AgentDock runtime 一起交付的核心 Skill 放在：
40 
41```text
42core-skills/<skill-name>/
43```
44 
45不要创建空目录。
46 
47## SKILL.md Frontmatter
48 
49AgentDock 使用 Agent Skills 风格的字段：
50 
51```yaml
52---
53name: example-skill
54description: 清楚说明何时使用、解决什么问题
55license: Apache-2.0
56compatibility: Requires Python 3.11 or later.
57metadata:
58  owner: example-team
59allowed-tools: exec_command
60---
61 
62# Example Skill
63```
64 
65AgentDock 真正依赖并严格校验的只有：
66 
67- `name` 必填，长度 1–64，只允许小写 ASCII 字母、数字和 `-`，不能以 `-` 开头/结尾，也不能包含连续 `--`；
68- `description` 必填，最长 1024 个 Unicode 字符，并能让模型稳定判断何时使用；重要的 Use when、Do not use 和相邻 Skill 边界条件不要依赖正文补充，因为模型会先用 description 做候选路由；
69- Markdown 正文必须非空；
70…