Skill 设计原则

先确定 Skill 要帮助完成的判断或行动，再设计发现入口、方法与资源。description 帮助 Agent 发现能力，入口引导选读，方法与资源支持执行，验证检查实际任务结果。内容与约束按任务需要取舍。

本文处理 Skill 特有的设计判断。文档体系、单篇结构及段落句子的通用要求由 document-writing 的“文档写作原则”统一维护。

创建或修改任何 Skill 前，必须先读本文，包括局部修改、结构调整与整体重写。 再按编写依据读取本次修改涉及的规范与模板。

能力定位

先明确 Skill 帮助使用者解决什么问题、支持什么判断或行动，再选择知识、指令、工具与资源。不以文档产出或流程走完代替任务完成。例如，“判断是否需要缓存”允许得出“不需要”，而不是默认交付缓存方案。

说明与相邻能力的边界及需要组合的情形。能力可以按任务组合，不把所有 Skill 排成必经流水线。

发现与调用

Agent 先依据目录中的 description 判断是否读取 Skill，再依据入口选择当前任务需要的材料。设计时分别检查这两步：description 能否使相关任务找到这项能力，入口能否使当前问题对应到正确的方法。

Description 用能力和有代表性的场景概括用途，不堆触发词或失败请求原句。具体字段与填写方式见Skill 入口模板。

按任务需要加载方法与资源，避免每次调用都读取全部分支。必须遵守的前提应在依赖它的动作之前可见，不能藏在 Agent 不会进入的可选分支。入口的内容组织遵循文档写作原则。

指令、工具与资源

开放判断提供目标、依据和边界；顺序影响正确性时明确前提与步骤。指令约束的选择见指令与工具设计，不把所有任务约束成固定操作流程。

稳定、重复且确定性的操作可交给程序；已有工具可用时优先复用，不为形式完整而增加脚本。脚本的调用与结果设计遵循工具设计，命令行入口提供 --help 和最小调用示例。

Skill 应携带执行所需资源，或声明已确认可用的依赖。不要假设其他 Skill、工具或运行环境必然存在。发布清单应包含入口实际指向的资源及脚本依赖的文件。

脚本的内置资源按脚本或 Skill 所在位置定位，避免依赖作者机器路径和启动目录。在发布后的目录结构下验证调用；源目录中能运行，不代表安装后可用。

编写依据

按修改对象读取，通用写作要求只在 document-writing 维护：

修改对象	编写依据
Skill 文档体系、入口正文、方法或经验条目	先读 document-writing 的 references/文档写作原则.md；通过该 Skill 的入口定位
Skill 入口字段与结构	再读Skill 入口模板
指导性参考文档	再读 document-writing 的 templates/参考文档模板.md
脚本	读工具设计，交付要求见上文“指令、工具与资源”

验证设计

文档的组织与表达按文档写作原则检查；资源与发布清单核对可用性。Skill 行为验证关注 Agent 能否从真实请求发现能力、选对方法、遵守关键前提，并得到任务要求的结果。

涉及行为效果的改动，按测试与迭代取得任务证据。出现触发、路由或执行偏差时，使用Skill 问题诊断。格式通过和文档走读不能证明执行行为已改善；仅做文档编辑时，不自动运行模型测试或发布。