# Skill Authoring

创建、设计、修改、重构和验证 AgentDock Skill 时使用；负责 Agent Skills 兼容的...

- Repository: https://github.com/uvwt/agentdock (1293 stars)
- Category: AI and agents
- License: Apache-2.0
- Last updated: 2026-10-27
- Runs scripts: yes, review before use

## Install

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

## Description

创建、设计、修改、重构和验证 AgentDock Skill 时使用；负责 Agent Skills 兼容的 SKILL.md、可移植核心、引用、辅助脚本、测试、安全边界和本地真实验证。

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

# 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 仓库：

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

按需扩展：

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

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

```text
core-skills/<skill-name>/
```

不要创建空目录。

## SKILL.md Frontmatter

AgentDock 使用 Agent Skills 风格的字段：

```yaml
---
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。

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