一个熟练工程师排查问题时，会自然地区分日志事实和猜测，先查对象再执行危险命令，修改后做回归。这些习惯平时藏在脑子里。把它们交给 Agent，如果只写“你是一名资深专家，请谨慎处理”，真正的边界一个都没留下。
Skill 的价值不是增加人设，而是把某一类任务的触发条件、操作顺序、证据标准、危险边界和验收方式写成可复用协议。它应该比大段系统提示更窄，也更容易评审和测试。
先写清楚什么时候该用、什么时候不该用
好的 description 本质上是一份路由契约，不能写成功能列表。它包含用户会说的任务、关键对象和明确边界。例如“任务实例失败诊断、日志查看、重跑与停止”与“修改作业 SQL”看似都围绕任务，实际权限和证据完全不同，应由不同 Skill 处理。
触发过宽会抢走不相关任务，触发过窄又需要用户记住内部术语。我会用真实问法建一组正例、近邻负例和歧义例：哪些必须命中，哪些应路由给另一个 Skill，哪些必须先澄清对象。
边界还要写不支持项和移交目标。工具当前不能修改调度周期，就明确只能查询并引导页面操作，不让 Agent 猜接口。诊断 Skill 不应因为发现 SQL 问题就自动修改生产代码，除非用户授权的任务本来包含修复。
优先级冲突要显式解决。运行态问题优先运维 Skill，源码解释走开发 Skill，表字段走元数据 Skill。靠模型从两份重叠描述里临场选择，回归结果会随上下文漂移。
把专家判断拆成证据门槛
“先诊断再修改”仍然太抽象。需要写出诊断最少读取哪些事实、如何建立因果：对象 ID、版本、配置、日志窗口、调用链、业务结果；若怀疑参数，则固定其他条件做 A/B；没有真实运行证据时，结论必须标为推断。
对于源码问题，Skill 可以要求给文件、方法、行号和调用链；对于 SQL 等价改写，要求 schema、约束、NULL/重复语义与 EXPLAIN；对于流式故障，要求原始 SSE、转换事件、持久化和客户端结果。不同领域的“证据”不是同一个模板。
停止条件也属于专业判断。连续三次相同失败且没有新信息，应停止相同重试；目标对象不唯一，不做有副作用操作；权限不足，不绕过审批；现场证据可能被覆盖，先保全再改配置。
Skill 不应把所有分支写成机械脚本。明确哪些事实必须有、哪些动作需要审批、什么结果算完成，把剩余判断留给模型。过度细化会在接口稍变时整体失效，过度抽象又无法约束行为。
工具说明要包含风险和验证
只列工具名称和参数，Agent 不知道哪个调用是只读、哪个会写数据。Skill 应标注工具副作用、幂等性、对象范围、前置权限、结果语义和失败恢复。HTTP 200 若只表示接受任务，就不能当成执行成功。
危险操作采用 resolve-preview-approve-execute-verify：先把用户自然语言解析成稳定对象，展示规范化参数和影响，获得绑定版本的批准，再执行并从业务系统核验。这里的审批是一条可审计 decision，远比弹出一句“确定吗”严格。
凭证不写入 Skill。它只说明应使用哪类连接和权限；运行环境通过 secret/identity provider 注入短期凭证。把 token 复制进示例既容易泄漏，也会让 Skill 无法共享。
工具不可用时写降级路线：优先只读 API，其次受控浏览器，最后给用户可复制步骤；不能声称已经操作。降级后的验证能力若下降，也要在结果中说明。
指令正文应短，资料与脚本按需加载
入口文件只保留每次都需要的规则和资源路由。大段 API 文档、领域字典和示例移到 references，根据任务读取；确定性强的检查、格式转换和批处理放 scripts。这样上下文里留下的是本次真正相关的约束。
引用资料要标适用版本。Kubernetes、MCP、云 API 的参数会变，Skill 如果永远指向 current 文档，半年后的历史任务可能被新语义误导。对生产工具最好绑定版本化 schema，并在不兼容时明确失败。
脚本不是免审的捷径。检查参数、固定工作目录、避免输出 secret，破坏性动作默认 dry-run 或要求明确目标。脚本输出结构化结果，让 Agent 能判断成功、部分成功与未知，而不是只看退出码。
示例应覆盖正常路径和边界失败，不要只放一个完美案例。最有价值的示例往往是同名对象、多租户权限不足、工具超时后状态不明、已有用户改动不能覆盖。
用任务回放而不是主观感觉评 Skill
我会保存真实任务的脱敏集合，包括正例、近邻任务、危险操作和故障注入。每次修改 Skill 后，对固定模型、工具 fixture 和环境回放，检查路由、证据读取、动作范围、停止条件和最终验证。
评测不能只看答案文风。Skill 的核心指标是：是否选对对象、是否调用允许的工具、是否在证据不足时停下、是否避免越权、是否完成真实结果核验。可以写得很好看却改错生产对象，这种结果应直接失败。
失败样本要回到具体规则。若反复把页面状态当执行结果，补结果语义与验证步骤；若触发范围抢了别的任务，改 description 和路由样本；若上下文过长导致关键约束被忽略，做分层加载。不要每次都加一句更强烈的“必须”。
Skill 有 owner、版本、变更说明和兼容范围。上线先 canary，观察工具拒绝、人工纠正和任务成功；发现回归可回退到旧版本。它是运行资产，不是个人提示词收藏。
把隐性经验写成 Skill，真正难的是承认边界：知道什么证据足够，什么动作不能替用户决定，什么结果还没有验证。边界越清楚，Agent 才越像一个可靠的工程协作者，而不是一个口吻自信的万能助手。