5分钟看懂 SKILL.md一份AI技能文件的写作指南【免费下载链接】agentskillsSpecification and documentation for Agent Skills项目地址: https://gitcode.com/GitHub_Trending/ag/agentskills一个文件夹加一份 SKILL.mdVS Code、Claude Code 这些 AI 工具就能复用同一套工作流程。读完这篇你能写出 AI 一次就懂的 SKILL.md。先看看一个能跑的最简技能先建立具象感最小的技能就长这样全文不到 20 行。--- name: roll-dice description: Roll dice with a random number generator. Use when asked to roll a d6, d20, or any other die. --- Roll a die by running (replace sides with the side count): echo $((RANDOM % sides 1))放在项目里的.agents/skills/roll-dice/SKILL.md就能被客户端发现。三段结构对应三步加载启动时 AI 只读name和description判断这事我接不接任务匹配后才把正文读进上下文执行时再按需跑脚本、读参考文件。这个渐进披露机制是后面所有写法原则的源头。Goose 这类客户端也认同一格式技能写一次多个工具通用。元数据AI 靠这两行决定加载不加载你name是门牌description是广告牌。AI 在启动阶段只看这两样完整字段约束见官方规范。名字别起花跟文件夹保持一致小写字母、数字、连字符64 个字符以内必须和父文件夹同名连字符不能开头结尾、不能连用。为什么卡这么死验证工具是机器检查名字对不上目录直接判不合格。description 超过三行就该砍1024 字符是硬上限但你用不满。关键不是写满是写准说清它做什么、什么时候该用它并带上用户常说的词。# 太含糊AI 不知道何时该激活 description: Helps with PDFs. # 说清做什么 何时用 description: Extract text from PDFs and fill in forms. Use when the user mentions PDFs, forms, or document extraction.为什么描述太宽无关任务也误触发太窄该触发时反而沉默。指令正文只写 AI 猜不到的技能一激活正文整体进上下文窗口每个字都在跟对话历史抢注意力。它已知的一个字都别写别解释 PDF 是什么、HTTP 怎么工作。只写项目约定、非显而易见的坑、该用哪个库。判断标准只有一条删掉这句话AI 会不会做错不会就删。任务越脆指令越死多种做法都行时说目标、给自由解释为什么比下命令更有效步骤容错率低时比如数据库迁移直接钉死命令、禁止改参数。同时给默认值而不是菜单用 pdfplumber扫描件改走 OCR好过罗列四个库让 AI 自己挑。AI 面对选项列表会逐个试探浪费轮次还可能挑错。长内容拆走并写明何时加载正文建议 500 行以内细节材料放references/、scripts/。引用文件时要写触发条件接口返回非 200 时读references/api-errors.md而不是笼统的详见 references/。前者让 AI 按需加载后者等于没说。✅ 写完先问自己三个问题别急着丢给 AI 试跑先过一遍自检。三十秒内你能向同事说清这个技能做什么、什么时候用吗说不清description 就是糊的。正文里有没有 AI 本来就懂的内容逐行过能删就删。有没有万一发生 X的分支却没告诉 AI 该做什么漏一个执行时就要靠它瞎猜。仓库里带了 skills-ref 验证工具格式和命名是否合规跑一行skills-ref validate ./my-skill就有结果。 三个最容易翻车的场景都是高频错误对照改一遍。description 写成帮助处理 PDF。后果任务来了匹配不上技能形同虚设。正确做法一两句话写清能力与触发时机带上用户会说的关键词。把整本参考文档塞进 SKILL.md。后果激活时全文进上下文AI 被长文带偏、漏掉关键步骤。正确做法正文只留核心指令细节拆进references/并注明加载时机。列出多个等价工具让 AI 选。后果它逐个试探、浪费轮次还可能挑错。正确做法指定默认工具用一句话备注替代方案及适用条件。现在就能动手打开你的 SKILL.md把 description 压到两句话以内删掉所有 AI 本来就懂的内容。【免费下载链接】agentskillsSpecification and documentation for Agent Skills项目地址: https://gitcode.com/GitHub_Trending/ag/agentskills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考