SKILL.md 编写指南从零到能跑新手 10 分钟写出第一个 AI 技能【免费下载链接】agentskillsSpecification and documentation for Agent Skills项目地址: https://gitcode.com/GitHub_Trending/ag/agentskills你让 AI 干活它却每次都在瞎猜格式和要求问题不在模型而在没人给它一份标准工作手册。GitHub 加速计划开源项目 ag/agentskills 就是为此而生——用一份 SKILL.md 给 AI 代理定规矩本文是这份 SKILL.md 编写指南的入门实战。一句话看懂 SKILL.mdSKILL.md 就是放在技能文件夹里的说明书开头几行是名片name 和 description行话叫元数据你可以理解为身份证信息后面是操作规程。AI 启动时只扫名片碰到匹配的任务才翻开说明书照做。所以它写得准不准直接决定你的技能能不能被用上。AI 读取技能分三步走发现启动时只加载 name 和 description判断这事跟我有没有关系激活任务对上号才把正文读进上下文执行照正文步骤干活需要时才加载附带的脚本和参考文件。这个按需加载机制叫渐进式披露progressive disclosure——名片贴在门口操作手册放屋里AI 只敲门、不推门。从零到一编写流程拆解建技能文件夹先写 name 和 description 两行元数据技能 一个文件夹 里面的 SKILL.md。文件夹名用全小写字母、数字和连字符比如 pdf-to-markdownname 必须和文件夹同名。name 和 description 是两个必填项合起来就是 AI 技能元数据的主体可选字段按需要加name技能的唯一标识64 字符以内description干什么 什么时候用1024 字符以内可选的 license、compatibility环境要求、metadata作者、版本号等。各字段的具体约束对照 SKILL.md 格式规范 检查即可。用何时该用我的句式写 descriptiondescription 是 AI 决定是否加载技能的唯一依据等于技能的触发器。别只说这是什么要说清遇到什么事该找我。两个小技巧列出用户可能的说法处理 PDF 文档、提取正文、用户提到 PDF 时使用覆盖没提关键词的场景即使用户没直接说 CSV 也适用。想系统测试触发效果可以看官方的 优化技能描述那里教你怎么设计该触发/不该触发的测试问句。正文只写 AI 不知道的砍掉它本来就会的技能一旦激活正文会整个进入上下文每多一个字都在抢 AI 的注意力。自检标准只有一条没有这句话AI 会不会做错不会就删。所以不用解释PDF 是什么HTTP 怎么工作直接给结论用哪个库、走哪几步、输出成什么样。多步骤任务用编号清单输出格式直接贴模板——AI 对具体结构的模仿能力远强于对抽象描述的理解。长文档拆进 references 目录写明加载时机规范建议 SKILL.md 正文控制在 500 行以内。真需要更多资料就放进技能目录的 references/、scripts/、assets/ 子文件夹并在正文里写明什么情况下读哪个文件。比如API 返回非 200 时读 references/api-errors.md就比笼统一句详见 references/有效得多——前者 AI 知道何时去翻后者它根本不会主动翻。动手实操让技能真正跑起来 下面用一个PDF 转 Markdown的最小技能走一遍全流程照着抄改就行。第 1 步新建文件夹比如.agents/skills/pdf-to-markdown不少客户端的默认技能目录就在这里具体以你用的工具为准放一个 SKILL.md。前面是元数据后面是 AI 要照做的步骤--- name: pdf-to-markdown description: 把 PDF 文件转成 Markdown 文本。用户要求处理 PDF、提取文档正文时使用。 --- ## 操作步骤 1. 用 pdfplumber 打开 PDF逐页提取文本 2. 清理多余空白输出为同名 .md 文件第 2 步先给技能做个体检。仓库里的 skills-ref 参考实现 自带命令行校验工具下面的命令把工具装好再对你的技能目录跑一次校验——它负责检查元数据是否合法、命名是否合规git clone https://gitcode.com/gh_mirrors/ag/agentskills cd agentskills/skills-ref python -m venv .venv source .venv/bin/activate pip install -e . skills-ref validate path/to/your-skill第 3 步看看技能在提示词里长什么样。skills-ref 的 to-prompt 命令会把技能渲染成 AI 系统提示里的 XML 块location 指路告诉 AI 完整说明在哪个文件available_skills skill namepdf-to-markdown/name description把 PDF 转成 Markdown 文本/description location/path/to/pdf-to-markdown/SKILL.md/location /skill /available_skills接着在支持 Agent Skills 的客户端里输入 /skills确认技能出现在列表中完整过程见 快速上手教程再丢一句把这份 PDF 转成 Markdown看它是否按你写的步骤执行。进阶写好技能的 5 个细节 能跑是及格线跑得稳才是分水岭。对照这 5 条自查description 写何时用不写是什么对比处理 PDF和处理 PDF 文档、提取正文、用户提到 PDF 时使用——后者才是有效的触发器。给默认值不给菜单多个库都能用时写用 pdfplumber扫描件换 pytesseract别列一堆等价选项让 AI 自己挑。把踩过的坑写成 Gotchas 清单环境里反直觉的事——users 表用软删除查询必须带 deleted_at IS NULL——写进正文比一万句注意边界情况都有用。步骤松紧分场合删数据这类脆弱操作写就运行这条命令别加参数代码审查这类开放任务只讲看什么发挥空间留给 AI。交付前先跑真实任务用真任务跑一两遍看执行轨迹而不只是最终结果——AI 在哪一步卡壳往往就是哪一步指令写得含糊。完整方法论在 最佳实践 里有展开想系统评估技能输出质量继续看 评估技能输出。避坑指南 误区 1description 写得越长越保险→ 正解所有技能的名片共享同一块上下文空间写到干什么 何时用 关键词就收手。1024 字符是硬上限但通常越精炼触发越准。误区 2name 起得花哨点更有辨识度→ 正解只允许小写字母、数字和连字符不能以连字符开头或结尾不能有连续连字符还必须和文件夹同名。PDF-Processing 这种直接判违规。误区 3把所有背景知识塞进 SKILL.md显得专业→ 正解正文越厚AI 越难抓重点还可能被无关指令带偏。核心步骤留正文长资料拆到 references/并写明加载时机。误区 4写完就算完没人验证→ 正解交付前先跑 skills-ref 校验格式再用真实任务验证行为。说到底如何编写高效的 SKILL.md写—测—改的循环比一次性堆字数有效得多。现在就可以动手新建一个技能文件夹写下 10 行 SKILL.md用 skills-ref 跑一遍校验。按这份 SKILL.md 编写指南走下来AI 技能元数据怎么写就不再是玄学而是能复制粘贴的操作流程——今晚你就拥有第一个真正属于自己工作流的技能。【免费下载链接】agentskillsSpecification and documentation for Agent Skills项目地址: https://gitcode.com/GitHub_Trending/ag/agentskills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
SKILL.md 编写指南：从零到能跑，新手 10 分钟写出第一个 AI 技能
SKILL.md 编写指南从零到能跑新手 10 分钟写出第一个 AI 技能【免费下载链接】agentskillsSpecification and documentation for Agent Skills项目地址: https://gitcode.com/GitHub_Trending/ag/agentskills你让 AI 干活它却每次都在瞎猜格式和要求问题不在模型而在没人给它一份标准工作手册。GitHub 加速计划开源项目 ag/agentskills 就是为此而生——用一份 SKILL.md 给 AI 代理定规矩本文是这份 SKILL.md 编写指南的入门实战。一句话看懂 SKILL.mdSKILL.md 就是放在技能文件夹里的说明书开头几行是名片name 和 description行话叫元数据你可以理解为身份证信息后面是操作规程。AI 启动时只扫名片碰到匹配的任务才翻开说明书照做。所以它写得准不准直接决定你的技能能不能被用上。AI 读取技能分三步走发现启动时只加载 name 和 description判断这事跟我有没有关系激活任务对上号才把正文读进上下文执行照正文步骤干活需要时才加载附带的脚本和参考文件。这个按需加载机制叫渐进式披露progressive disclosure——名片贴在门口操作手册放屋里AI 只敲门、不推门。从零到一编写流程拆解建技能文件夹先写 name 和 description 两行元数据技能 一个文件夹 里面的 SKILL.md。文件夹名用全小写字母、数字和连字符比如 pdf-to-markdownname 必须和文件夹同名。name 和 description 是两个必填项合起来就是 AI 技能元数据的主体可选字段按需要加name技能的唯一标识64 字符以内description干什么 什么时候用1024 字符以内可选的 license、compatibility环境要求、metadata作者、版本号等。各字段的具体约束对照 SKILL.md 格式规范 检查即可。用何时该用我的句式写 descriptiondescription 是 AI 决定是否加载技能的唯一依据等于技能的触发器。别只说这是什么要说清遇到什么事该找我。两个小技巧列出用户可能的说法处理 PDF 文档、提取正文、用户提到 PDF 时使用覆盖没提关键词的场景即使用户没直接说 CSV 也适用。想系统测试触发效果可以看官方的 优化技能描述那里教你怎么设计该触发/不该触发的测试问句。正文只写 AI 不知道的砍掉它本来就会的技能一旦激活正文会整个进入上下文每多一个字都在抢 AI 的注意力。自检标准只有一条没有这句话AI 会不会做错不会就删。所以不用解释PDF 是什么HTTP 怎么工作直接给结论用哪个库、走哪几步、输出成什么样。多步骤任务用编号清单输出格式直接贴模板——AI 对具体结构的模仿能力远强于对抽象描述的理解。长文档拆进 references 目录写明加载时机规范建议 SKILL.md 正文控制在 500 行以内。真需要更多资料就放进技能目录的 references/、scripts/、assets/ 子文件夹并在正文里写明什么情况下读哪个文件。比如API 返回非 200 时读 references/api-errors.md就比笼统一句详见 references/有效得多——前者 AI 知道何时去翻后者它根本不会主动翻。动手实操让技能真正跑起来 下面用一个PDF 转 Markdown的最小技能走一遍全流程照着抄改就行。第 1 步新建文件夹比如.agents/skills/pdf-to-markdown不少客户端的默认技能目录就在这里具体以你用的工具为准放一个 SKILL.md。前面是元数据后面是 AI 要照做的步骤--- name: pdf-to-markdown description: 把 PDF 文件转成 Markdown 文本。用户要求处理 PDF、提取文档正文时使用。 --- ## 操作步骤 1. 用 pdfplumber 打开 PDF逐页提取文本 2. 清理多余空白输出为同名 .md 文件第 2 步先给技能做个体检。仓库里的 skills-ref 参考实现 自带命令行校验工具下面的命令把工具装好再对你的技能目录跑一次校验——它负责检查元数据是否合法、命名是否合规git clone https://gitcode.com/gh_mirrors/ag/agentskills cd agentskills/skills-ref python -m venv .venv source .venv/bin/activate pip install -e . skills-ref validate path/to/your-skill第 3 步看看技能在提示词里长什么样。skills-ref 的 to-prompt 命令会把技能渲染成 AI 系统提示里的 XML 块location 指路告诉 AI 完整说明在哪个文件available_skills skill namepdf-to-markdown/name description把 PDF 转成 Markdown 文本/description location/path/to/pdf-to-markdown/SKILL.md/location /skill /available_skills接着在支持 Agent Skills 的客户端里输入 /skills确认技能出现在列表中完整过程见 快速上手教程再丢一句把这份 PDF 转成 Markdown看它是否按你写的步骤执行。进阶写好技能的 5 个细节 能跑是及格线跑得稳才是分水岭。对照这 5 条自查description 写何时用不写是什么对比处理 PDF和处理 PDF 文档、提取正文、用户提到 PDF 时使用——后者才是有效的触发器。给默认值不给菜单多个库都能用时写用 pdfplumber扫描件换 pytesseract别列一堆等价选项让 AI 自己挑。把踩过的坑写成 Gotchas 清单环境里反直觉的事——users 表用软删除查询必须带 deleted_at IS NULL——写进正文比一万句注意边界情况都有用。步骤松紧分场合删数据这类脆弱操作写就运行这条命令别加参数代码审查这类开放任务只讲看什么发挥空间留给 AI。交付前先跑真实任务用真任务跑一两遍看执行轨迹而不只是最终结果——AI 在哪一步卡壳往往就是哪一步指令写得含糊。完整方法论在 最佳实践 里有展开想系统评估技能输出质量继续看 评估技能输出。避坑指南 误区 1description 写得越长越保险→ 正解所有技能的名片共享同一块上下文空间写到干什么 何时用 关键词就收手。1024 字符是硬上限但通常越精炼触发越准。误区 2name 起得花哨点更有辨识度→ 正解只允许小写字母、数字和连字符不能以连字符开头或结尾不能有连续连字符还必须和文件夹同名。PDF-Processing 这种直接判违规。误区 3把所有背景知识塞进 SKILL.md显得专业→ 正解正文越厚AI 越难抓重点还可能被无关指令带偏。核心步骤留正文长资料拆到 references/并写明加载时机。误区 4写完就算完没人验证→ 正解交付前先跑 skills-ref 校验格式再用真实任务验证行为。说到底如何编写高效的 SKILL.md写—测—改的循环比一次性堆字数有效得多。现在就可以动手新建一个技能文件夹写下 10 行 SKILL.md用 skills-ref 跑一遍校验。按这份 SKILL.md 编写指南走下来AI 技能元数据怎么写就不再是玄学而是能复制粘贴的操作流程——今晚你就拥有第一个真正属于自己工作流的技能。【免费下载链接】agentskillsSpecification and documentation for Agent Skills项目地址: https://gitcode.com/GitHub_Trending/ag/agentskills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
