第21篇-Skill编写质量标准-触发条件-步骤描述-陷阱列表

【Skills 系统从入门到精通】第 21 篇Skill 编写质量标准——触发条件、步骤描述、陷阱列表本篇你将学到触发条件的写作规范和Use when…公式的变体步骤描述的可执行性标准每一步都能对应到具体工具调用陷阱列表的真正价值失败经验比成功流程更重要代码块的规范要求和 CSDN 质量分注意事项12 项质量自检清单读完本篇你将能够判断一个技能的质量水平并写出符合专业标准的技能。一、触发条件写作规范1.1 “Use when…” 公式好的触发条件必须告诉 Agent “什么情况下用我”公式适用场景Use when [doing X]. [Features].标准格式Use when [condition]. [Capabilities].条件触发Use when [task type]. [Coverage].任务覆盖Use when 开头触发场景什么时候用我能力列表具体覆盖范围Agent 语义匹配场景命中即加载1.2 好的 vs 差的触发条件✅ Use when reviewing code. Security scan, quality gates, auto-fix. → 明确场景代码审查 具体能力安全扫描、质量门禁、自动修复 ❌ A useful tool for developers. → 无触发场景无具体能力1.3 反触发条件When to Use 中也可以写什么时候不该用## When to Use - Need to format code according to team conventions - Want to enforce consistent style across a project Dont use for: - Language syntax learning (use documentation instead) - Code minification (use build tools)反触发条件帮助 Agent 在边界场景做出更准确的判断。二、步骤描述的可执行性2.1 可执行性测试每个步骤都应该通过可执行性测试——Agent 读完后知道用什么工具、执行什么命令、期望什么结果。高可执行性### Step 2: Extract error lines bash grep -E (ERROR|FATAL) /var/log/app.log /tmp/errors.txtThis extracts all ERROR and FATAL level entries to a temp file.Verify:wc -l /tmp/errors.txtshould show a reasonable count.分析有具体命令、有输出文件、有验证方法。 **低可执行性** markdown ### Step 2: Find the errors Look at the log file and find where the errors are.分析没有具体命令Agent 不知道怎么找。通过不通过一个步骤可执行性测试知道用什么工具执行什么命令期望什么结果只有意图描述Agent 靠猜执行高可执行性grep 命令 输出文件 验证方法低可执行性看看日志找到错误2.2 步骤之间的依赖关系复杂流程中步骤之间有依赖。应该明确标注### Step 3: Statistical analysis **Requires**: Step 2 completed (errors extracted to /tmp/errors.txt) bash sort /tmp/errors.txt | uniq -c | sort -rn | head -20--- ## 三、陷阱列表的价值 ### 3.1 为什么 Pitfalls 最有价值 一份操作流程可以搜索到但失败经验只有踩过坑的人知道。 Pitfalls 的价值在于**减少试错成本**。没有 Pitfalls 的技能Agent 需要自己踩坑才能学到教训——每次踩坑都消耗时间和 Token。有了 PitfallsAgent 直接避开已知陷阱。 ### 3.2 Pitfalls 的写作结构 每个 Pitfall 应该包含三要素**问题 原因 解决方案** mermaid graph LR A[问题br/app.log 只有 1KB] -- B[原因br/日志已轮转br/历史在压缩文件中] B -- C[解决br/检查所有轮转文件br/zcat 读取压缩] C -- D[Agent 直接避坑br/减少试错成本] style D fill:#c8e6c91. **Log rotation problem** - 问题: app.log 只有 1KB看起来日志很少 - 原因: 日志已经轮转大量历史日志在 app.log.1.gz 中 - 解决: ls -lh app.log* 检查所有轮转文件zcat 读取压缩文件3.3 Pitfalls 的来源来源示例可靠度自己踩过的坑端口冲突导致启动失败最高亲身经历团队积累的经验数据库迁移时锁表高多人验证官方文档的警告某命令在特定版本有 bug中需验证版本社区讨论某配置在 macOS 上不生效中需验证环境四、12 项质量自检清单编写完技能后逐项检查#检查项通过标准1name 规范小写连字符动词对象全拼不缩写2description 触发性以 “Use when…” 开头核心关键词在前 57 字符3version 存在有语义化版本号4Overview 精炼100-200 字不重复 description5When to Use 具体列出具体触发条件不泛泛而谈6Procedure 可执行每步有具体命令无占位伪代码7代码块有语言标签bash/python/yaml 等标签8Pitfalls 有价值来自实际经验含问题原因解决9Verification 可量化有具体检查命令或验证逻辑10文件大小适中8,000-15,000 字符超了拆分到 references11无重复技能已检查现有技能库无同类12已在新会话验证技能可被发现、可被触发、可正确执行12 项质量自检元数据类name 规范description 触发性version 存在正文类Overview 精炼When to Use 具体Procedure 可执行代码块语言标签价值类Pitfalls 有价值Verification 可量化工程类文件大小适中无重复技能新会话验证本篇小结维度质量标准触发条件“Use when…” 具体场景 可选反触发步骤可执行性有命令、有输出、有验证、有依赖标注Pitfalls 价值问题原因解决方案来自实际踩坑代码块标注语言、可运行、无占位符文件大小8K-15K 字符超出则拆分自检12 项清单全部通过下篇预告下一篇讲解技能与脚本的集成——如何在技能中引用和调用 Python/Bash 脚本让技能拥有更强的数据处理能力。如果本篇内容对你有帮助欢迎点赞收藏有任何疑问欢迎在评论区交流。