Skills 设计与实现

Skill 是一份可复用的领域流程：它告诉 Agent 什么时候应该使用这套能力、先读取什么、按什么顺序工作、如何验证结果。Skill 不是“更长的系统提示词”，而应该是边界清晰、可以验收的工作单元。

Skill 的最小结构

不同 Harness 的目录约定可能不同，下面是便于迁移的通用结构：

skills/
└── backend-review/
    ├── SKILL.md
    ├── references/
    │   ├── checklist.md
    │   └── api-guidelines.md
    ├── scripts/
    │   └── collect-diff.mjs
    └── examples/
        └── review-output.md

SKILL.md 只保留触发条件、主流程和输出契约；细节放到 references，脚本放到 scripts，避免每次触发都加载全部内容。

一个可复用的代码审查 Skill

---
name: backend-review
description: 审查 Go/Java 后端变更的正确性、安全性、性能和测试覆盖。
---

# Backend Review

## When to use
- 用户要求 review、CR、检查改动或合入前审查时使用。

## Workflow
1. Read the diff and identify changed execution paths.
2. Read related tests and configuration.
3. Check correctness, security, performance, and compatibility.
4. Report findings by priority with file and line references.

## Rules
- Do not modify files unless explicitly asked.
- Do not report style preferences as bugs.
- Verify every finding against current code.

## Output
- Priority: P0/P1/P2/P3
- Evidence
- Impact
- Suggested fix

这里的输出契约比“请认真审查”更重要：下游可以解析优先级、证据和建议，用户也能快速判断是否合入。

触发描述怎么写

描述应包含“场景 + 关键词 + 边界”：

good: "Review Go/Java backend diffs before merge, including security and tests."
bad: "A useful code skill."

不要用过宽的描述抢占所有任务，也不要让用户必须记住内部目录名。

渐进式加载和参数

一个 Skill 可以根据任务规模选择深度：

/backend-review scope=diff depth=standard
/backend-review scope=pr depth=deep include=security,performance

参数应影响明确的行为，例如检查范围、输出格式或验证深度；不要把一堆互相冲突的开关交给模型自行解释。

调试清单

• 触发了吗？检查描述是否与真实用户表达匹配。
• 加载了吗？检查目录名、入口文件和权限。
• 执行顺序对吗？把依赖的读取步骤写在主流程里。
• 工具可用吗？先确认命令和脚本在目标环境存在。
• 输出可验收吗？要求文件、命令、结果和未决事项。
• 重复触发吗？避免在入口和引用文件中重复相同指令。

评测一个 Skill

准备一组固定任务，至少包含：

• 正常任务；
• 信息不完整任务；
• 需要拒绝的越权任务；
• 工具失败任务；
• 与其他 Skill 可能冲突的任务。

记录触发率、完成率、误报率、平均工具调用次数和人工介入率。一次成功的演示不能替代回归任务集。

Go/Java Skill 的分工

不要为每一种语言复制一份完整 Skill。共享审查主流程，使用引用资料注入语言差异：

backend-review/
├── SKILL.md
└── references/
    ├── go.md
    └── java.md

Go 参考资料可以补充 error wrapping、goroutine、context 和 go test；Java 参考资料可以补充异常边界、线程池、Spring 事务和 Maven/Gradle。

练习

1. 写一个“数据库迁移审查” Skill，规定迁移、回滚和集成测试证据。
2. 为同一个 Skill 设计正常、拒绝和工具失败三条评测样例。
3. 将一个 100 行的 Skill 拆成入口、引用资料和脚本。