如何写出好SKILL.md从SkillClaw进化指南提炼的8条技能编写原则【免费下载链接】SkillClawLet Skills Evolve Collectively with Agentic Evolver项目地址: https://gitcode.com/gh_mirrors/sk/SkillClawSkillClaw 是一个让 AI Agent 技能集体进化的开源框架你的每次真实对话都会沉淀为可复用的 SKILL.md 技能文件并在多个会话、多个 Agent 甚至多个用户之间共享演化。写对 SKILL.md是这套进化体系生效的前提。这篇文章从 SkillClaw 进化引擎Agentic Evolver内置的《进化指南》中提炼出8 条技能编写原则帮你写出能被正确触发、长期可维护的高质量技能。先认识 SKILL.md技能进化的核心载体在 SkillClaw 中每个技能都是一个独立目录入口文件就是SKILL.md——由 YAML frontmatter元信息 Markdown 正文两部分组成可附带scripts/、references/、assets/等辅助资源最小格式如下完整格式定义见 skill_manager.py--- name: debug-systematically description: Use when diagnosing a bug. Gather evidence before forming hypotheses. NOT for: simple typo fixes. category: coding --- # Debug Systematically ...正文面向任务的实操指导...下面 8 条原则正是 SkillClaw 的进化引擎在读证据 → 改技能循环中执行的判断规则源码见 EVOLVE_AGENTS.md 与 execution.py。8条技能编写原则清单#原则一句话解释1命名即定位短小、动宾式、小写连字符2描述即触发器2-4 句写清何时用和何时不用3压缩环境信息写 Agent 猜不到的事实不写通用常识4祈使句具体示例命令、端点、端口、负载格式都要落地5简洁且有证据写可复用指导不写故障复盘6保守编辑当前版本是事实来源只改有证据的部分7分清三类问题技能问题才改技能别替 Agent 背锅8先自检再发布1-3 个验证场景 保留演化历史原则1命名即定位——短小、动宾式、小写连字符名字不是标题而是技能的身份证。进化指南要求优先使用短小、面向动作的名字lowercase-hyphenated slug且必须与现有技能不重名创建前先查manifest.json。✅ debug-systematic-errors deploy-to-production ❌ 关于调试的笔记 Debugging原则2描述是主要触发机制——写清何时用与NOT forfrontmatter 里的description决定技能在什么任务下被召回所以它必须包含明确的触发场景 排除条件。指南给出的标准句式是2-4 句话说明这个技能做什么、什么时候用并显式写出NOT for: ...边界。 一个典型进化动作就叫optimize_description技能正文没问题、只是被错误任务触发时系统会只重写描述而不动正文execution.py。可见描述与正文是两个独立维度。原则3压缩环境信息而不是复述通用常识这是全篇最核心的一条好技能应该压缩环境信息——API 端点、端口、负载格式、工具怪癖、领域流程——而不是写 Agent 本来就会的通用最佳实践。❌ 调用失败时请考虑重试、注意限流通用常识Agent 自己会✅ 该服务只暴露/v2/ingest端点429 时必须退避 30s 再重试环境特定猜不出来原则4用祈使句带上具体示例正文应使用祈使语气按任务自然组织凡是对任务关键的信息——具体 API 端点、端口、命令模式、payload 示例——必须写进正文让未来的 Agent 可以直接照做EVOLVE_AGENTS.md。原则5简洁、可复用、以证据驱动写可复用的指导而不是某次故障的总结或事后复盘。如果一段内容只对本次事故有意义、下次用不上就不该进入 SKILL.md。原则6保守编辑——当前版本是事实来源不是草稿改进已有技能时improve_skill指南反复强调默认做定向修改而不是整体重写保留原有结构、标题顺序和术语只有失败只是边角案例时补充缺失的检查点不动无关章节被成功会话支持的章节除非有明确反证否则保持原样。原则7分清技能问题、Agent问题、环境问题不是所有失败都是技能的错。进化引擎在动手前先做归因失败类型典型表现正确做法技能问题指导缺失或写错修改技能Agent 问题误用技能、上下文溢出不要往技能里堆运行期建议环境问题API 抖动、网络不稳加一句简短提示别写成重试教程⚠️ 指南特别点名的反模式技能里已经写了正确的 API 信息Agent 没用上而失败——这是 Agent 问题绝不能把正确的 API 信息删掉换成自己去读源码execution.py。同时有一组硬性约束API 契约、端口、输出路径、payload 格式、必需文件名除非证据显示它们变了否则不许改也不要把一个技能改造成另一个目的的技能。原则8先自检再发布留下演化历史SkillClaw 把自我验证作为技能的发布门槛从当前会话证据中定义 1-3 个小验证场景优先选能复现原失败的案例跑静态检查frontmatter 完整、触发条件没有过宽、references/等相对引用真实存在有条件就跑最小冒烟测试如脚本--help、dry-run验证失败就继续改改不过就回滚或选择skip——不要带着已知的坏改动收尾把验证记录写入history/vN_evidence.md形成改了什么、为什么改、证据是什么的演化台账。配套要求每次改进前必须先读完history/下所有v*.md与v*_evidence.md避免把过去的改进又改回去历史文件一律用版本号命名禁用日期。决策速查什么时候改进、什么时候放手进化引擎每轮对每个技能只选一个动作判据可以直接抄进你的工作流improve_skill多个会话指向同一章节缺失/过时/讲不清 → 定向编辑optimize_description正文没问题只是被错误任务触发 → 只重写描述create_skill出现不归属任何现有技能的清晰、可教授的重复模式 → 新建skip技能够用 / 证据太弱 / 失败源于 Agent 而非技能 → 不动指南的底线是拿不准时宁可 skip也不做投机性修改。结语让好技能持续进化 把以上 8 条原则内化后你可以先跑一次本地闭环客户端代理 evolve server参考 README.md 的部署说明与 scripts/install_skillclaw.sh再配合skillclaw dashboard sync/skillclaw dashboard serve检查技能的版本历史与验证进度。核心文件速查技能格式与加载skill_manager.py进化引擎工作流与提示词evolve_server/engines/进化会话证据处理evolve_server/pipeline/写技能不难难的是让技能活得久。SkillClaw 的思路是把编写原则交给进化引擎持续执行你只管和 Agent 好好聊天——技能库会自己越来越干净。【免费下载链接】SkillClawLet Skills Evolve Collectively with Agentic Evolver项目地址: https://gitcode.com/gh_mirrors/sk/SkillClaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考