编写技能
复用现有拥有者
在创建包之前，先检查现有的技能目录。对于仓库工作，搜索目标目录和授权工作空间中的每个相关源目录。对于授权的实时库工作，使用 Rundesk 的目录和技能列表；不要打开实时库以绕过任务的访问边界。在决定之前，阅读可能匹配的摘要，然后阅读它们的主体和相关引用。
当请求的能力与现有拥有者共享用户意图、工作流程和权限时，扩展该拥有者。在其中添加支持性脚本、引用或测试，而不是创建第二个路由表面。仅当该能力需要不同的路由、判断、权限或证明时才创建新技能；记录这种区别，以便不能因为相近的名称而将其本身视为正当理由。
选择工件
- 技能是指令边界：何时行动、应用何种判断、遵循何种程序以及如何证明结果。
- 工作流脚本是重复的本地转换、验证或编排的确定性机制。
- 集成添加外部服务边界：凭证、账户、网络故障、权限或远程影响。
将一次性自动化保留在其项目中，将代理私有的重复命令保留在该代理的脚本区域。仅当未来轮次需要路由或判断才能使用时，才将脚本打包到技能中。不要用代理必须重新解释的散文取代确定性代码。
在发布任何可重用脚本之前，阅读可重用工作流脚本。当它使用凭证、配置文件、OAuth、网络或远程影响时，还要阅读外部服务集成。
安全放置
仅在授权创建或安装时，在 local 中创建私有技能。对于草稿、审查、仓库更改或隔离测试，保持在命名的工作空间或临时目录中；不要检查或更改实时库以发现结果以后可能位于何处。
对于授权的私有技能，向 Rundesk 询问库的位置，而不是从 RUNDESK_HOME 派生或嵌入绝对路径。替换示例名称：
skill_name=release-notes
skill_library=$("$RUNDESK_COMMAND" skills | sed -n '1s/^skills in //p')
test -n "$skill_library" || exit 1
mkdir -p "$skill_library/local/$skill_name"
编写 <library>/local/<name>/SKILL.md，然后将其授予命名的代理：
"$RUNDESK_COMMAND" skills grant "$RUNDESK_AGENT" local/release-notes
该授权在代理的下一个回合中变为可发现，而不是当前回合。在为其他安装创建技能之前，阅读发布技能目录；已发布的技能属于目录仓库，而不是 local。
仅使用所需的形状
<name>/
├── SKILL.md 必需：路由和核心过程
├── rundesk.json 可选：必需的环境值
├── scripts/ 可选：可重复使用的命令
├── tests/ 可选：当没有目录测试区域拥有它们时的脚本契约
├── references/ 可选：有条件加载的细节
└── assets/ 可选：复制或输出的材料
仅在有内容时创建可选路径。省略 README、更改日志、安装指南和创建历史。
首先编写路由
前置元数据仅包含 name 和 description。
- 将
name与目录匹配。最多使用 64 个小写字母、数字和单连字符。 - 按用户意图路由，包括可能不命名技能的间接请求。以
Use when、Apply when或等效的适用性语言开头；提示短语不是触发器。 - 目标是两个短句：适用性，然后提供的专门工作流程或知识。仅对可能接近的误匹配添加
Do not use。仅包含在加载主体之前路由所需的概念。省略步骤、测试、收益声明和实现细节；仅当文件类型、工具或格式决定技能是否应触发时，才命名它们。 - 使用仍然正确路由的最短描述；1,024 个字符是上限，而不是目标。将每个触发器放在那里，因为每个持有者每轮都要为其支付成本，并且在路由成功之前主体不可用。
# 错误：嵌入了无助于路由的实现和验证。
描述：在创建发布说明时使用。它读取 Git 历史，编写 Markdown，分组提交，检查链接，运行验证，并生成精确的内部和公共版本，格式准确。
# 正确：仅说明意图、提供的判断和最接近的边界。
描述：在从已发布的仓库更改准备发布说明时使用。它提供一个基于已验证历史的、面向受众的工作流程。不要用于未发布的计划。
仅保留行为指导
使用执行顺序的祈使步骤。假设读者能够推理、编辑和使用常用工具。仅当句子能改变执行、防止可能的失败或路由所需细节时才保留。
- 在
SKILL.md中保留核心过程、一个强默认值和不太明显的陷阱。 - 对于脆弱操作，使用确切命令；对于几种方法都起作用的情况，使用简洁的判断。
- 解释约束防止的失败，而不是添加未解释的强调。
- 在介绍每个引用时说明何时阅读。保持单一事实来源；链接而不是重述。
- 移除背景、过程历史、过时的声明和已在别处加载的规则。
- 区分观察到的契约和推荐的默认值。引用技术约束，并教授真正的陷阱作为症状、原因、替换和可观察的证明。
保持 SKILL.md 在 500 行以下；将有条件的细节移到一层深度的链接引用中。
预算上下文
| 部分 | Token 成本 | 保留在那里 |
|---|---|---|
description | 每轮 | 最短完整触发器 |
SKILL.md | 路由后 | 核心过程、默认值、陷阱 |
references/ | 读取时 | 有条件细节和较大示例 |
scripts/ | 输出进入上下文 | 输出有界的确定性工作 |
tests/ | 仅验证 | 可执行契约和边界情况 |
assets/ | 使用时 | 模板和输出材料 |
优先使用简短示例。将脚本输出限制为下一个决策所需的内容。
证明整个技能
-
验证目录名称、前置元数据名称、描述语法和限制。
-
当需要授权时，应用它并验证下一个回合：
"$RUNDESK_COMMAND" skills list "$RUNDESK_AGENT" "$RUNDESK_COMMAND" skills doctor "$RUNDESK_AGENT" -
运行每个脚本的引用拥有的边界矩阵和直接可执行入口点。
-
在不同的新鲜回合中，尝试直接请求、间接请求和接近的误匹配。确认主体和必需引用在开展工作之前加载；按类别修复路由，而不是复制的提示短语。
-
对于重要的技能，将相同任务与没有该技能的空白基线进行比较。然后让一个单独的测试代理在没有预期实现的情况下使用它。直接审查工件和命令；代理的摘要不是证明。移除没有带来实质性改进的指导。
-
将生成的文本与可执行正确性分开审查：路由精度、执行顺序、有用判断、简洁性、重复性和引用纪律。绿色脚本测试并不证明文本质量。验证或观察事实承诺；测试可执行声明并缩小部分真理。用保留方便聚合但改变真实关系或结果的对抗性反例挑战语义声明——突变检查无法修复错误的测试预言。审查整个接口，包括空成功、重复证据和每个依赖于数据的输出部分。