SKILL.md 快速上手：5 步让 AI 代理学会你的工作流

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 最小可用示例：从建目录到验证通过

1. 克隆规范仓库，里面有格式文档和验证工具：

git clone https://gitcode.com/gh_mirrors/ag/agentskills

2. 在你的项目里建技能目录，写入一个最小SKILL.md（VS 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))

3. 装验证工具skills-ref，它负责检查你的SKILL.md是否符合规范：

cd agentskills/skills-ref uv sync && source .venv/bin/activate

4. 跑一条命令验证，没有报错就说明格式合规：

skills-ref validate path/to/.agents/skills/roll-dice

整个文件不到 20 行，但结构已经是完整的技能了。

⚙️ ## SKILL.md 加载机制：渐进式披露如何省上下文

很多人以为技能会被整包塞进代理的上下文，其实不是。规范设计了一套三阶段加载：启动时代理只扫每个技能的 name 和 description，相当于只发了一张名片；当你的任务跟某个描述对上了，代理才把完整的SKILL.md正文读进来；正文里提到的scripts/、references/、assets/等捆绑文件，则是指到哪、读到哪。这样代理手里可以挂几十个技能，平时只花一点点上下文。

前两个字段的约束也很硬：name 最多 64 字符，只允许小写字母、数字和单个连字符，且必须和父目录同名；description 最多 1024 字符，要同时说清"做什么"和"什么时候用"。

所以写技能时，主文件只放"每次都要用的核心指令"，细节往外挪，这是规范反复强调的原则。

💡 ## 写好 SKILL.md 的 5 条实用技巧

1. description 要写得"主动出击"。description 是代理决定激不激活技能的唯一依据。用祈使句告诉它"什么时候用"，并列出用户可能不会直接说出口的关键词，比如"even if the user doesn't 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 才算合格。这套流程适合在描述频繁调整时上，收益是把"凭感觉改文案"变成数据驱动。

把技能注入你自己的代理。如果你在做自定义 agent，skills-ref/ 里的to-prompt子命令可以把若干技能目录渲染成<available_skills>XML 块，其中<location>指向SKILL.md路径，整段贴进系统提示即可，代理就知道去哪读完整指令。

这个格式不绑定任何单一工具，Goose、Qodo 等众多客户端都已原生支持，下面两张就是它们两个客户端的标识。也就是说，你写的技能一次通过验证，就能在多端直接使用。

⚠️ ## SKILL.md 避坑指南：4 个高频问题排查

现象：验证报错 name 与目录不匹配。原因：规范要求 name 必须与父目录同名。解法：目录叫roll-dice，name 字段就写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