root
5eb390e3ed
- 复制 reader-digest-flow skill 到 skills/ 目录（含 SKILL.md + references/） - README 新增 Agent Skill 章节说明供 Agent 使用的工作流
39 lines
4.7 KiB
Markdown
39 lines
4.7 KiB
Markdown
# AI Agent 的 Skill 系统设计
|
|
|
|
Source: https://mp.weixin.qq.com/s?__biz=MzAxNDEwNjk5OQ==&mid=2650544717&idx=1&sn=b578abf5a81034670900a3b8eb874296
|
|
Category: 方法论
|
|
|
|
## 核心结论
|
|
好的 Skill 应是一个小而准的行为系统，通过触发、加载、执行、约束、验证和迭代的组织，将通用 Agent 转化为在特定任务上稳定可靠的专用 Agent。核心原则是上下文窗口是公共资源，必须采用渐进披露、按任务风险设置自由度，并通过真实任务前向测试来证明行为改变。
|
|
|
|
## 主要论点
|
|
Skill 设计的本质是行为编程而非文档编写，需要将期望行为转化为 Agent 能稳定执行的结构化工作流。为此，必须同时解决发现（正确场景触发）、加载（最小上下文）、执行（合适自由度）和验证（真实任务测试）四件事，并通过门控、脚本外化、测试防合理化等机制确保 Agent 在复杂压力下不走捷径。
|
|
|
|
## 关键方法 / 机制
|
|
- 渐进披露的三层内容加载：元数据（frontmatter 的 name/description）用于发现，正文（SKILL.md）用于执行，资源（scripts/references/assets）按需读取。description 只做路由器，不包含完整流程，防止 Agent 凭印象执行。
|
|
- 门控机制（HARD-GATE）：在低自由度任务中，使用明确的 <HARD-GATE> 标签禁止 Agent 在条件满足前执行后续动作，减少解释空间，让关键路径更像程序而非建议。
|
|
- 脚本外化降低上下文消耗和行为漂移：将需要确定性的操作（如 PDF 旋转）封装为 scripts/ 中的可执行脚本，避免 Agent 每次临时生成代码，提升可靠性和节省 token。
|
|
- 基于 TDD 的前向测试方法：用子代理模拟真实用户任务，只给原始任务和最少上下文，不泄露预期结论；观察行为轨迹、输出文件等原始证据，发现并封堵 Agent 的违规行为。
|
|
- 反模式自查表与检查表：交付前检查触发条件、自由度设置、资源引用、验证流程等关键项，确保 Skill 不是一份草稿而是一个可用的能力包。
|
|
- 跨平台适配与优雅降级：Skill 应写行为规则（如 TodoWrite），再通过平台层映射到具体工具名（如 todowrite）；平台能力不足时优雅降级，保持 Skill 的可迁移性。
|
|
|
|
## 重要细节
|
|
- SKILL.md 的 frontmatter 和正文职责分离：name/description 用于发现（Agent 触发前可见），正文用于执行（触发后加载）。如果触发条件写在正文里，Agent 在决定是否触发时根本读不到。
|
|
- 命名规范：短、可触发、动词优先，例如 create-skill 比 skill-creation 更好，这本质上是路由质量——Agent 在技能库里找能力时，name/description 是第一层索引。
|
|
- 资源组织原则——“信息只放一个地方”：不要在 SKILL.md 和 references/ 中重复同一段规则，重复会带来漂移，导致 Agent 在两个版本间自行解释，增加维护成本。
|
|
- 门控类型示例：先决条件门控（先理解例子再编辑）、并发冲突门控、未保存内容门控、敏感操作门控（已创建 Skill 需处理影响再修改）。
|
|
- 流程图用 GraphViz DOT 嵌入 Markdown：对于包含非线性判断、循环、回退的步骤，流程图比纯文本更稳定，能防止 Agent 遗漏关键分支。
|
|
- 验证时防“合理化”问题：AI Agent 在压力下会为跳过规则编造理由，Skill 需要提前写出这些借口并给出反驳；审查循环应围绕真实失败风险而非措辞偏好。
|
|
|
|
## 可复用启发
|
|
- “上下文窗口是公共资源”原则：设计任何 Agent 指令时，每段内容都要质疑“Agent 真的需要这段解释吗？”和“值得占用的 token 成本吗？”，这适用于提示词、系统消息等所有 Agent 输入设计。
|
|
- 先收集具体例子再抽象 Skill：不要从抽象能力开始写，而是先收集用户会怎么触发、哪些请求应该触发/不应该触发、成功输出是什么等具体场景，避免写出宽泛不可执行的指令。
|
|
- 用脚本固化确定性任务、用门控防止关键路径走捷径：对于高脆弱、低变化空间的任务（如文件格式转换），应使用脚本而非描述性建议；对于必须按顺序执行的步骤，用门控打断 Agent 的“合理化”冲动。
|
|
- 设计防合理化的测试流程：用子代理模拟真实用户，只给原始任务，不泄露预期答案；观察是否存在只有看到结论才能成功的情况——如果这样，说明 Skill 不够清楚或测试设置泄露答案。
|
|
|
|
## 关键词
|
|
SKILL.md、YAML、Markdown、DOT、GraphViz、TDD、HARD-GATE、quick_validate.py
|
|
|
|
## 主题
|
|
AI Agent、行为编程、Token 经济、系统设计、约束机制
|