如何写出好SKILL.md？从SkillClaw进化指南提炼的8条技能编写原则

如何写出好SKILL.md？从SkillClaw进化指南提炼的8条技能编写原则

【免费下载链接】SkillClawLet Skills Evolve Collectively with Agentic Evolver项目地址: https://gitcode.com/gh_mirrors/sk/SkillClaw

SkillClaw 是一个让 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：命名即定位——短小、动宾式、小写连字符

名字不是标题，而是技能的"身份证"。进化指南要求：优先使用短小、面向动作的名字（lowercase-hyphenated slug），且必须与现有技能不重名（创建前先查manifest.json）。

✅ debug-systematic-errors deploy-to-production ❌ 关于调试的笔记 Debugging

原则2：描述是主要触发机制——写清"何时用"与"NOT for"

frontmatter 里的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问题、环境问题

不是所有失败都是技能的错。进化引擎在动手前先做归因：

⚠️ 指南特别点名的反模式：技能里已经写了正确的 API 信息，Agent 没用上而失败——这是 Agent 问题，绝不能把正确的 API 信息删掉换成"自己去读源码"（execution.py）。

同时有一组"硬性约束"：API 契约、端口、输出路径、payload 格式、必需文件名，除非证据显示它们变了，否则不许改；也不要把一个技能改造成另一个目的的技能。

原则8：先自检，再发布；留下演化历史

SkillClaw 把"自我验证"作为技能的发布门槛：

1. 从当前会话证据中定义 1-3 个小验证场景（优先选能复现原失败的案例）；
2. 跑静态检查：frontmatter 完整、触发条件没有过宽、references/等相对引用真实存在；
3. 有条件就跑最小冒烟测试（如脚本--help、dry-run）；
4. 验证失败就继续改，改不过就回滚或选择skip——不要带着已知的坏改动收尾；
5. 把验证记录写入history/v<N>_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