Agent Skill 高质量编写规范¶
Ch04.242 Agent Skill 高质量编写规范¶
📊 Level ⭐⭐ | 9.7KB |
entities/agent-skill-writing-practices.md
1. 从真实经验提炼¶
- 和AI协作完成任务后提炼成功步骤/修正/输入输出格式
- 从事故复盘报告、API设计规范、代码审查意见中生成
- 包含项目特有的错误模式
2. 像函数一样设计边界¶
| 问题 | 后果 |
|---|---|
| 范围过小 | 需激活多个Skill，开销增加，指令可能冲突 |
| 范围过大 | 激活条件难以精准，容易误触发，指令臃肿 |
3. 写"方法"而不是"答案"¶
# 糟糕：只适用于这一个场景
将 orders 表与 customers 表在 customer_id 上关联，筛选 region = 'EMEA'，并求和 amount 列。
# 优秀：可复用的方法
1. 从 references/schema.yaml 读取数据库Schema，找到相关表
2. 按照 _id 外键约定关联表
3. 使用 WHERE 子句应用筛选条件
4. 按需聚合数值列，最终以Markdown表格输出
4. 预设"默认值"，不要提供"菜单"¶
# 太多选项 → AI犹豫不决
你可以使用 pypdf, pdfplumber, PyMuPDF 或 pdf2image...
# 明确的默认方案 + 备选
使用 `pdfplumber` 进行文本提取。如果遇到无法提取的扫描件，回退到 pdf2image + pytesseract OCR。
5. "坑点（Gotchas）"章节——最有价值的内容¶
## 坑点（Gotchas）
- `users` 表使用软删除。所有查询必须包含 `WHERE deleted_at IS NULL`，否则会包含已注销账户。
- 用户ID在数据库中是 `user_id`，在认证服务中是 `uid`，在计费API中是 `accountId`。
- `/health` 端点只要Web服务器在运行就返回200，即使数据库已宕机。请使用 `/ready` 检查完整健康状态。
6. 提供输出模板和检查清单¶
## 报告结构
# [分析标题]
## 执行摘要
[关键发现的一段落概述]
## 主要发现
- 发现1，附上数据支撑
## 建议
1. 具体、可执行的建议
## 表单处理工作流
进度跟踪：
- [ ] 步骤1：分析表单
- [ ] 步骤2：创建字段映射
- [ ] 步骤3：验证映射
- [ ] 步骤4：填写表单
- [ ] 步骤5：验证输出
scripts/ 编写规范¶
自包含脚本依赖声明¶
| 运行时 | 方式 |
|---|---|
| Python | PEP 723：# /// script TOML块 |
| Deno | npm:/jsr: 导入说明符 |
| Bun | 自动安装缺失包 |
| Ruby | bundler/inline |
Agentic 脚本设计原则¶
- 避免交互式提示——Agent 在非交互式Shell中运行，阻塞会无限挂起
- 用 --help 记录用法——是Agent学习脚本接口的主要方式
- 有帮助的错误消息——说明哪里错了、期望什么、可尝试什么
- 结构化输出——stdout发数据，stderr发诊断
- 幂等性——"如果不存在则创建" > "重复时失败"
- --dry-run 支持——预览破坏性操作
- 有意义的退出码——不同失败类型用不同退出码
- 可预测的输出大小——限制输出或支持
--output写到文件
深度分析¶
渐进式披露架构的设计意图¶
Skill 采用"发现→激活→执行"三阶段架构，本质是将上下文窗口视为稀缺资源进行分层管理。 发现阶段仅加载 name + description，这是合理的——Agent 在决定是否激活某个 Skill 时不需要了解其内部实现细节。激活阶段才加载完整 SKILL.md，此时上下文注入的信息量与实际任务需求相匹配。这种设计避免了"一激活就塞满上下文"的问题。 问题在于 description 字段的设计质量直接影响 Skill 的激活准确率。90%的坑集中在 description 不准确或缺少关键词，这意味着描述的模糊性会导致该激活的不激活、不该激活的乱激活。
边界设计：函数隐喻的价值与局限¶
"像函数一样设计边界"这个原则将 Skill 视为有明确输入输出的功能单元，具有良好的工程直觉。范围过小导致多次激活带来的协调开销和潜在冲突；范围过大导致指令臃肿和误触发。这个类比有助于编写者在设计阶段就考虑职责边界。 但函数隐喻也有局限：真实世界的 Agent Skill 往往有副作用（side effects），如修改文件、调用 API、执行长期任务等。这些副作用不在函数签名中体现，但在实际执行中会带来风险。"幂等性"和"--dry-run"原则某种程度上是对这一局限的补偿。
Gotchas 章节的核心价值¶
"坑点"章节被明确标记为"最有价值的内容"，这反映了知识编写的核心哲学：失败案例比成功案例更有信息密度。 一个运维新人可以从"不要使用 /health 检查数据库状态，请使用 /ready"这条 Gotcha 中立即理解系统的实际行为，而不需要经历一次真实事故才能学到这个事实。这种知识编码方式将组织内的隐性知识显性化，降低了知识传递的成本。
评估体系的设计缺陷¶
当前评估体系使用 with_skill vs without_skill 的对比，但这个框架有几个问题： 1. 覆盖范围模糊：没有明确区分"Skill 带来的能力提升"和"Skill 弥补的模型缺陷" 2. 断言脆弱性：当 Skill 的目标是在模糊场景下给出合理响应时，可编程验证的断言可能本身就不合理 3. 迭代信号噪声：delta 指标（pass_rate、time_seconds、tokens）只能说明"有差异"，不能说明"差异的方向是否符合预期"
scripts/ 规范的实际执行难点¶
"避免交互式提示"作为硬性要求在实际中并不容易：很多成熟的命令行工具（如 curl、jq、fzf）默认使用 TTY 检测来决定输出格式。Agent 在非交互式 Shell 中运行时，这些工具的行为可能与预期不符。 结构化输出（stdout=data, stderr=diagnostics）的设计很好，但大多数常用工具并不遵守这个约定。这导致 Skill 编写者需要在 references/ 中附带包装脚本或使用说明，而非直接依赖工具默认行为。
实践启示¶
编写前：明确 Skill 的激活边界¶
在动手写 SKILL.md 之前，应该先回答三个问题： 1. 什么时候不该激活这个 Skill——明确排除条件比包含条件更重要 2. 激活后 Agent 应该达到什么效果——可度量的结果而非模糊的能力提升 3. Skill 之间如何交互——当多个 Skill 都可能相关时，谁的优先级更高 description 字段的编写应该围绕"在什么情况下 Agent 应该考虑这个 Skill"展开，而非"这个 Skill 能做什么"。前者是触发条件，后者是功能清单。
编写中：Gotchas 的挖掘方法¶
挖掘有效的 Gotchas 不能靠凭空想象，而应该： 1. 从事故报告中提取：每次 Incident Review 时，将"如果当时有这个 Skill 就不会犯错"的点记录下来 2. 从调试日志中提炼：频繁出现的错误提示背后往往有系统性的坑点 3. 从跨团队沟通中收集：认证服务用 uid、计费系统用 accountId 这种跨系统的命名不一致，是最容易踩的坑 一个有效的 Gotcha 格式应该是：[Condition] → [Expected Behavior] → [Actual Pitfall]。
编写后：验证而非仅自检¶
写完 Skill 后，不要仅靠"读一遍觉得合理"来判断质量。应该： 1. 用随意措辞测试激活：用口语化、碎片化的表述触发 Skill，看是否能正确激活 2. 用边界条件测试执行：给最简单和最复杂的输入，看输出是否在预期范围内 3. 观察未使用 Skill 时的行为：确认 Skill 确实改变了 Agent 行为，而非仅改变了输出格式
迭代中：保持精简的判断标准¶
"少而好的指令 > 详尽规则"这个原则在实践中容易被遗忘。当发现某个场景遗漏时，自然的反应是"加一条规则"。但更可能是原规则表达不精确，而非原规则不足。 每次迭代应该先问：这个遗漏是因为规则本身表述模糊，还是因为规则覆盖范围不够？如果是前者，修改表述；如果是后者，再考虑添加新规则。