【免费下载链接】asmThe universal skill manager for AI coding agents.项目地址https://gitcode.com/gh_mirrors/asm17/asm点击查看免费下载如果你想在 AI Agent 技能管理器asm中发布自己的技能第一步就是写出一份规范的SKILL.md。本文完整拆解 frontmatter 的合法字段、高频踩坑点和校验方法帮你的技能一次通过规范检查被 Agent 准确触发。技能长什么样SKILL.md 在其中的位置一个 Agent Skill 本质上是一个目录其中SKILL.md是唯一必需的文件其余资源按需加载skill-name/ ├── SKILL.md ← 必需frontmatter 指令正文 ├── references/ ← 可选按需加载的参考文档 ├── agents/ ← 可选子代理提示词 └── scripts/ ← 可选确定性脚本这背后是渐进式披露Progressive Disclosure的三层加载机制元数据层name description—— 始终占用上下文SKILL.md 正文—— 技能触发时加载控制在 500 行以内附属资源—— 需要时才读取也就是说frontmatter 里的description是 Agent 决定要不要用这个技能的唯一依据写好它比写好正文更重要。上图中列表的 Description 一列正是每个技能 frontmatter 里的description字段。frontmatter 合法字段全览SKILL.md必须以 YAML frontmatter 开头。以下是完整的合规示例参考仓库中的 find-me-skills/SKILL.md--- name: find-me-skills description: Find Agent Skills for a goal the user cannot name yet. Dont use for installing named skills or authoring skills. license: MIT compatibility: Claude Code with the asm CLI on PATH effort: medium metadata: version: 1.4.0 author: Your Name youexample.com ---字段速查表目前校验工具只允许以下 8 个顶层字段写别的会被判为错误字段必需说明name✅唯一标识符必须与父目录名完全一致description✅单行描述触发机制的核心metadata建议含versionSemver与authorlicense❌SPDX 许可证标识如MITallowed-tools❌技能使用的工具名空格分隔compatibility❌运行环境要求不超过 500 字符effort❌low \| medium \| high \| xhigh \| max五选一dependencies❌依赖的其他技能名列表非空完整字段规则见 frontmatter-rules.md目录结构与写作模式见 writing-guide.md。name最容易被忽视的硬性约束name有 4 条校验规则任何一条不满足都会直接报错1–64 个字符只允许小写字母、数字、连字符kebab-case不能以连字符开头/结尾不能有连续连字符--必须与父目录名完全一致skills/my-skill/SKILL.md→name: my-skillmetadata版本管理是规范的一部分新建技能metadata.version: 1.0.0每次修改都要递增版本号Patchx.y.Z错别字、措辞微调Minorx.Y.0新增能力、扩展触发词MajorX.0.0工作流或输出格式的破坏性变更公开发布时补充metadata.author四个高频踩坑点 ⚠️坑 1忘了给含特殊字符的值加引号YAML 极易写坏。值里出现冒号:时严格解析器会把后面的内容当成新映射# ❌ 错误 —— workflow 后的冒号会破坏解析 description: Follows a 5-step workflow: Analyze - Design - Plan # ✅ 正确 description: Follows a 5-step workflow: Analyze - Design - Plan经验法则所有多词字符串值默认加双引号成本为零。坑 2description 超过 250 字符尾部被截断description 有三档长度限制按先咬人排序限制后果250 字符软目标超出部分从尾部截断——最先被砍掉的是负向触发子句约 2% 上下文窗口超预算的技能对 Agent不可见1024 字符硬上限直接报错坑 3description 缺少负向触发子句只有正向描述的 description 会导致误触发比如 Tailwind 技能在 Vue 项目上被调用。规范的写法是加上Dont use for …子句点名 2–3 个不应触发的相邻领域# ❌ 只写正向 description: Creates React components using Tailwind CSS. # ✅ 正向 负向 description: Creates React components using Tailwind CSS. Use whenever the user asks for a new React component or styled layout. Dont use for Vue, Svelte, or plain HTML projects.坑 4顶层字段越权version、creator、tags等不属于合法顶层字段集。它们必须收进metadata:之下creator统一改为author。校验工具会把顶层的version、creator直接判为 unexpected key 报错。description 最佳实践pushy 负向触发写作指南 description-guide.md 总结的三条核心原则动词开头——写用户会说的触发短语而不是实现细节Implements the Project entity model 这种实现腔没人会这么问每个触发分支只写一次——同义重复是在浪费每次调用的上下文删掉 hedge 词——helps、allows you to 这类词全部砍掉图中 Use structured metadata 一条正是本文主题把 name、description、compatibility 等 frontmatter 字段填好发现和工具链才能正常工作。发布前自检两条命令走起 ✅第 1 步机械校验仓库内置了 quick_validate.py无需 LLM 推理即可捕捉所有机械性问题字段越权、命名规范、长度限制、YAML 解析等python skills/skill-creator/scripts/quick_validate.py your-skill-dir它还会对两类问题输出WARNING非致命但应修复description 超过 250 字符、缺少负向触发子句。第 2 步质量评分asm eval your-skill-dirasm eval从描述质量、上下文效率、安全、可测试性等维度打分并给出 Top suggestions。官方 skill-standard.md 定义的合格线是总分 85 且每个单项 ≥ 8单一强项无法掩盖短板。小结一份可复用的检查清单检查项标准namekebab-case、≤64 字符、与目录名一致description单行、≤250 字符、含 Dont use for … 子句metadata.versionMAJOR.MINOR.PATCH每次修改必递增metadata.author公开发布时必填顶层字段仅允许 8 个合法字段无越权 keyYAML 安全含: # {} []等特殊字符的值全部加双引号正文篇幅 500 行超出内容下沉到references/把这份清单贴在工作流末尾你的每一个技能都能做到发布即可用。完整的编写规范可继续研读 skill-creator/SKILL.md 与 skill-standard.md。赞分享【免费下载链接】asmThe universal skill manager for AI coding agents.项目地址https://gitcode.com/gh_mirrors/asm17/asm点击查看免费下载相关推荐Sequoia高而窄旗形5道筛选漏斗 参数调优避坑实操Sequoia高而窄旗形5道筛选漏斗 参数调优避坑实操 Sequoia高而窄旗形策略有个反直觉的设定一只票40天涨了60%后你最想追的那天往往最追不金融科技数据分析编写 GSAP AI Skillsgsap-skills 仓库的 SKILL.md 规范、Frontmatter 约定与最佳实践编写 GSAP AI Skillsgsap skills 仓库的 SKILL.md 规范、Frontmatter 约定与最佳实践 本指南基于 gsap skiAI 技能前端protobuf.js字段规则详解required、optional与repeated最佳实践protobuf.js字段规则详解required、optional与repeated最佳实践 在使用Protocol Buffers协议缓冲区简称Pro后端开发工具上一篇Mirror.js 开源项目教程下一篇SimCLR终极指南如何用对比学习实现视觉自监督学习创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考