SKILL.md 快速上手5 步让 AI 代理学会你的工作流【免费下载链接】agentskillsSpecification and documentation for Agent Skills项目地址: https://gitcode.com/GitHub_Trending/ag/agentskills当你得反复向 AI 代理解释同一套项目约定时ag/agentskills 仓库里的 Agent Skills 规范能帮你把这套经验打包成可安装的技能。核心就一个文件给代理指定目录丢一份SKILL.md它就能按你的流程干活还能跨多个客户端复用。下面带你从零跑通第一个技能。 ## SKILL.md 最小可用示例从建目录到验证通过克隆规范仓库里面有格式文档和验证工具git clone https://gitcode.com/gh_mirrors/ag/agentskills在你的项目里建技能目录写入一个最小SKILL.mdVS Code 默认从.agents/skills/找技能mkdir -p .agents/skills/roll-dice--- name: roll-dice description: Roll dice using a random number generator. Use when asked to roll a die (d6, d20, etc.). --- Run: echo $((RANDOM % sides 1))装验证工具skills-ref它负责检查你的SKILL.md是否符合规范cd agentskills/skills-ref uv sync source .venv/bin/activate跑一条命令验证没有报错就说明格式合规skills-ref validate path/to/.agents/skills/roll-dice整个文件不到 20 行但结构已经是完整的技能了。⚙️ ## SKILL.md 加载机制渐进式披露如何省上下文很多人以为技能会被整包塞进代理的上下文其实不是。规范设计了一套三阶段加载启动时代理只扫每个技能的 name 和 description相当于只发了一张名片当你的任务跟某个描述对上了代理才把完整的SKILL.md正文读进来正文里提到的scripts/、references/、assets/等捆绑文件则是指到哪、读到哪。这样代理手里可以挂几十个技能平时只花一点点上下文。前两个字段的约束也很硬name 最多 64 字符只允许小写字母、数字和单个连字符且必须和父目录同名description 最多 1024 字符要同时说清做什么和什么时候用。加载阶段加载内容触发时机Token 预算建议发现name description代理启动时扫描全部技能约 100 tokens激活SKILL.md 完整正文任务匹配到描述5000 tokens 以内执行scripts/、references/ 等捆绑文件正文指令要求读取按需越小越好所以写技能时主文件只放每次都要用的核心指令细节往外挪这是规范反复强调的原则。 ## 写好 SKILL.md 的 5 条实用技巧1. description 要写得主动出击。description 是代理决定激不激活技能的唯一依据。用祈使句告诉它什么时候用并列出用户可能不会直接说出口的关键词比如even if the user doesnt explicitly mention PDFs。对比一下写Helps with PDFs基本等于没写写清提取文本、填表单、合并文件用户提到 PDF 或表单时使用才靠谱。2. 主文件瘦身细节外移。规范建议SKILL.md控制在 500 行、5000 tokens 以内。长参考文档拆到references/REFERENCE.md并在正文里写明加载条件例如如果 API 返回非 200再读 references/api-errors.md比一句详见 references/有效得多。3. 只写代理不知道的。别解释 PDF 是什么、HTTP 怎么工作这些模型本来就会。把篇幅留给项目约定、特定 API 的坑、非显而易见的边界情况。判断标准很简单没有这条指令代理会做错吗不会就删。4. 先真做一遍再沉淀成技能。直接让大模型凭空生成技能产出的多是妥善处理错误这类空话。正确做法是带着代理完成一次真实任务把走通了的步骤、你中途的纠正、输入输出格式提炼出来质量会高一个档次。5. 技能粒度对齐一个完整单元。太窄会导致一个任务要同时激活多个技能互相打架太宽则无法被精确触发。查数据库 格式化结果是一个合理单元再往里塞数据库运维就开始越界了。 ## 进阶玩法触发率测试与自建代理集成用触发率给 description 做 A/B 测试。技能写得再好不触发就是零。方法是准备约 20 条真实感的评测提问8-10 条应该触发变换措辞、明暗程度、详细度8-10 条不该触发重点放近失样本——共享关键词但实际是别的任务比如让 CSV 分析技能遇到用 Python 把 CSV 传到 Postgres。每条跑 3 次看代理是否加载了你的SKILL.md正样本触发率高于 0.5、负样本低于 0.5 才算合格。这套流程适合在描述频繁调整时上收益是把凭感觉改文案变成数据驱动。把技能注入你自己的代理。如果你在做自定义 agentskills-ref/ 里的to-prompt子命令可以把若干技能目录渲染成available_skillsXML 块其中location指向SKILL.md路径整段贴进系统提示即可代理就知道去哪读完整指令。这个格式不绑定任何单一工具Goose、Qodo 等众多客户端都已原生支持下面两张就是它们两个客户端的标识。也就是说你写的技能一次通过验证就能在多端直接使用。⚠️ ## SKILL.md 避坑指南4 个高频问题排查现象验证报错 name 与目录不匹配。原因规范要求 name 必须与父目录同名。解法目录叫roll-dicename 字段就写roll-dice别自作主张起别名。现象name 校验失败提示非法字符。原因name 只允许小写字母、数字和单个连字符最长 64 字符不能以连字符开头或结尾也不允许连续连字符。解法PDF-Processing改写成pdf-processing。现象问了相关问题代理却绕过技能自己答。原因description 太笼统导致匹配不上或者任务过于简单代理用基础工具就能搞定、懒得激活技能。解法往 description 里加触发词和场景描述并把技能用在需要领域知识的任务上而不是读一下这个 PDF这类一步操作。现象技能激活后代理动作拖沓、输出冗长。原因正文塞了太多与当前任务无关的指令和通用知识和对话历史一起争夺上下文注意力。解法按前面的技巧 2、3 瘦身主文件把边缘情况和长文档挪去references/。一份写好的SKILL.md就是一套可安装、可复用、跨工具生效的 AI 代理工作说明书。字段完整约束和评测方法可以继续看 docs/specification.mdx 和 docs/skill-creation/ 目录下的教程。【免费下载链接】agentskillsSpecification and documentation for Agent Skills项目地址: https://gitcode.com/GitHub_Trending/ag/agentskills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考