跳到主要内容

SKILL.md工程规范

核对日期：2026-08-26。

1. 定义与边界​

SKILL.md 是 Agent Skill 的入口文件：YAML frontmatter + Markdown 正文。Anthropic 与 Cursor 都采用「目录 + SKILL.md」形态。

官方必填目前是：

字段约束用途
name小写、数字、连字符；Cursor 文档要求最长 64稳定 ID
description非空；Cursor 文档要求最长 1024触发与发现

其余字段（version、allowed-tools、disable-model-invocation）是各 Host 或团队的工程扩展，不要写成 MCP / Anthropic 规范必填。Cursor 默认 disable-model-invocation: true 表示必须被点名才加载；只有明确需要自动触发时才省略。

不适用：

  • 把整本设计系统贴进一个 Skill。
  • 用 Skill 代替工具 schema。
  • 在 frontmatter 里放密钥。

2. 为什么重要​

description 会被注入到「有哪些 Skill」的短清单里。写得像营销口号，就会误触发；写得像内部代号，就永远不触发。

Anthropic 的加载模型分三层：元数据常驻；命中后读正文（建议控制篇幅，官方 skill-creator 以约 500 行为宜）；scripts/ / references/ / assets/ 按需。参考文件超过约 300 行应带目录。脚本应执行后只回传输出，避免把脚本源码塞进窗口。

3. 核心机制​

skill-name/
├── SKILL.md                 # 必填
├── references/              # 可选，按需读取
├── scripts/                 # 可选，确定性步骤
└── assets/                  # 可选，模板与静态资源

触发匹配只看 frontmatter。正文里的「何时不要用」模型未必看得到，除非已经加载。因此 WHEN / WHEN NOT 必须出现在 description，正文再展开步骤。

4. 架构模式​

4.1 description 写法​

用第三人称，同时写 WHAT 和 WHEN：

description: >
  Compares a running page to Lanhu design context via frontend-workspace MCP
  (get_design_context, compare_page_to_design, run_design_gate).
  Use when the user asks for design fidelity, visual QA, or whether a page
  matches the mock. Do not use for OpenAPI-only contract checks or when
  no design link or cached design context exists.

避免：

  • 「我可以帮你做设计走查」
  • 「前端相关都可以」

4.2 正文最小结构​

---
name: review-design-fidelity
description: >
  对照设计稿做页面还原度检查。在用户提到走查、还原度、设计稿对比时使用。
  不要在用户只要组件 API 说明时使用。
---

# 设计稿还原度走查

## 何时使用

用户要判断实现是否贴近设计稿，且已有设计链接或 `.mcp-cache/frontend/design/` 缓存。

## 何时不用

- 只有 OpenAPI、没有设计稿。
- 用户明确只要文字规范，不要截图对比。

## 步骤

1. 确认 MCP `frontend-workspace` 可用。
2. 有链接则 `resolve_design_link`，再 `get_design_context`。
3. `compare_page_to_design`；需要门禁则 `run_design_gate`。
4. 输出错误 / 警告 / imageDiff，不把 mismatch 说成「看起来差不多」。

## 完成定义

- 有 `run_id` 或报告路径。
- 未跑对比不得声称通过。

4.3 工程扩展 frontmatter​

团队内部可以加，但 Host 必须认识并强制：

version: "1.2.0"
owner: frontend-platform
allowed-tools:
  - resolve_design_link
  - get_design_context
  - compare_page_to_design
  - run_design_gate
required-mcp:
  - frontend-workspace
risk-level: low

没有网关实现就不要写 allowed-tools 假装有沙箱。

5. 工程实现​

校验入口：

interface SkillFrontmatter {
  name: string;
  description: string;
}

function parseSkillFrontmatter(raw: unknown): SkillFrontmatter {
  const record = raw && typeof raw === "object" ? (raw as Record<string, unknown>) : {};
  const name = record.name;
  const description = record.description;
  if (typeof name !== "string" || !/^[a-z0-9-]+$/.test(name) || name.length > 64) {
    throw new Error("invalid_skill_name");
  }
  if (typeof description !== "string" || description.trim().length === 0 || description.length > 1024) {
    throw new Error("invalid_skill_description");
  }
  return { name, description };
}

正文加载后仍要：

6. 生产实践​

实践说明
触发词放 description用户口语（走查、还原度、OpenAPI）比内部工具名重要
步骤可执行「注意质量」无效；要写调用哪个工具、失败如何停
完成定义可测有报告路径 / 有门禁结果
参考文件拆开组件库清单放 references/，不要堆进 SKILL.md
脚本做确定性格式化、校验用 scripts/，不要让模型手算 JSON Schema
中英空格与术语与 ../99-权威资料索引/术语表.md 一致

7. 常见反模式​

反模式表现后果修正
description 过宽「处理所有前端问题」误触发、互抢WHAT + WHEN + WHEN NOT
正文当百科2000 行规范加载即爆上下文渐进披露
无完成定义「尽量做好」无法评测门禁 / 报告
伪造官方字段把自造 YAML 写成 Anthropic 必填换 Host 失效区分规范与扩展
Skill 内嵌密钥token 写进 Markdown泄露环境变量，Skill 只写变量名

8. 评测方法​

指标说明
Description Trigger Precision不该加载的任务中加载了的比例
Description Trigger Recall该加载却没加载
Body Size触发后正文 token，设上限
Instruction Follow-through加载后是否按步骤调用声明的工具
Hallucinated Completion未跑门禁却报告通过

每条 Skill 至少准备正例 5、反例 5。评测方法总览见 Skill触发与评测.md。

9. 安全与治理​

  • 把 Skill 当代码评审：谁能改 SKILL.md 谁就能改 Agent 行为。
  • 来自外部仓库的 Skill 默认不自动触发。
  • scripts/ 与 MCP 一样走最小权限，禁止 Skill 要求 all tools。
  • 变更走 PR，发布记版本；线上 trace 必须能指回版本。

10. 权威资料​