企业官网建设流程全解析

如果你想在 AI Agent 技能管理器asm中发布自己的技能，第一步就是写出一份规范的SKILL.md。本文完整拆解 frontmatter 的合法字段、高频踩坑点和校验方法，帮你的技能一次通过规范检查，被 Agent 准确触发。

技能长什么样？SKILL.md 在其中的位置

一个 Agent Skill 本质上是一个目录，其中SKILL.md是唯一必需的文件，其余资源按需加载：

skill-name/ ├── SKILL.md ← 必需：frontmatter + 指令正文 ├── references/ ← 可选：按需加载的参考文档 ├── agents/ ← 可选：子代理提示词 └── scripts/ ← 可选：确定性脚本

这背后是渐进式披露（Progressive Disclosure）的三层加载机制：

1. 元数据层（name + description）—— 始终占用上下文
2. SKILL.md 正文—— 技能触发时加载，控制在 500 行以内
3. 附属资源—— 需要时才读取

也就是说，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. Don't 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 <you@example.com>" ---

字段速查表

目前校验工具只允许以下 8 个顶层字段，写别的会被判为错误：

完整字段规则见 frontmatter-rules.md，目录结构与写作模式见 writing-guide.md。

name：最容易被忽视的硬性约束

name有 4 条校验规则，任何一条不满足都会直接报错：

• 1–64 个字符
• 只允许小写字母、数字、连字符（kebab-case）
• 不能以连字符开头/结尾，不能有连续连字符--
• 必须与父目录名完全一致（skills/my-skill/SKILL.md→name: my-skill）

metadata：版本管理是规范的一部分

• 新建技能：metadata.version: 1.0.0
• 每次修改都要递增版本号：
  • Patch（x.y.Z）：错别字、措辞微调
  • Minor（x.Y.0）：新增能力、扩展触发词
  • Major（X.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"

经验法则：所有多词字符串值默认加双引号，成本为零。

坑 2：description 超过 250 字符，尾部被截断

description 有三档长度限制，按"先咬人"排序：

坑 3：description 缺少负向触发子句

只有正向描述的 description 会导致误触发（比如 Tailwind 技能在 Vue 项目上被调用）。规范的写法是加上"Don't 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. Don't use for Vue, Svelte, or plain HTML projects."

坑 4：顶层字段"越权"

version、creator、tags等不属于合法顶层字段集。它们必须收进metadata:之下（creator统一改为author）。校验工具会把顶层的version、creator直接判为 unexpected key 报错。

description 最佳实践：pushy + 负向触发

写作指南 description-guide.md 总结的三条核心原则：

1. 动词开头——写用户会说的触发短语，而不是实现细节（"Implements the Project entity model" 这种实现腔没人会这么问）
2. 每个触发分支只写一次——同义重复是在浪费每次调用的上下文
3. 删掉 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-dir>

asm eval从描述质量、上下文效率、安全、可测试性等维度打分，并给出 Top suggestions。官方 skill-standard.md 定义的合格线是：总分 > 85 且每个单项 ≥ 8，单一强项无法掩盖短板。

小结：一份可复用的检查清单

把这份清单贴在工作流末尾，你的每一个技能都能做到"发布即可用"。完整的编写规范可继续研读 skill-creator/SKILL.md 与 skill-standard.md。