Next.js 仓库 Agent Skills 编写指南：SKILL.md 规范、描述匹配与 AGENTS.md 的分工

本文以 Next.js 仓库内的 authoring-skills 技能文档 为主体，系统讲解在 .agents/skills/ 目录下创建和维护 Agent 技能（Skill）的完整规范：何时该建 Skill、SKILL.md 的目录结构、受支持的 frontmatter 字段清单、让技能可靠自动触发的 description 写法，以及技能与常驻加载的 AGENTS.md 之间的分工与 $name 交叉引用机制。读完后你可以直接在任意遵循该约定的仓库中独立编写、评审和扩充一个规范的 Agent 技能。

1. 何时创建 Skill：与 AGENTS.md 的边界

authoring-skills/SKILL.md 给出的核心判断准则是：内容是否“值得按需加载”。当内容满足以下任一条件时才应创建 Skill：

• 对 AGENTS.md 来说太详细——代码模板、多步骤工作流、诊断过程；
• 只在特定任务中相关——不是每个会话都需要；
• 自包含到可以独立加载——不依赖会话上下文即可读懂。

反之，以下情况应留在 AGENTS.md 中：

• 每会话都需要的一句话规则或护栏（one-liner rule / guardrail）；
• 任何 Agent 都可能踩到的通用坑（general-purpose gotcha）。

文档进一步用一张对照表（SKILL.md 第 91–99 行）刻画了两者关系：

AGENTS.md（常驻加载）	Skill（按需加载）
一句话护栏（One-liner guardrails）	分步工作流（Step-by-step workflows）
例如「Keep require() behind if/else for DCE」	完整的 DCE 模式：代码示例、验证命令、边缘情况
通过 $name 引用指向技能	对 AGENTS.md 中规则的展开与深化

这个分工在 Next.js 仓库中是真实落地的。AGENTS.md 的 “Specialized Skills” 小节只保留一行式摘要，例如 $flags - feature-flag wiring across config/schema/define-env/runtime env、$authoring-skills - how to create and maintain skills in .agents/skills/，而真正的多步骤流程（如 feature flag 的完整接线清单）放在 .agents/skills/flags/SKILL.md 中。文档同时约定：新增 Skill 时，必须在对应 AGENTS.md 小节补一条带 $skill-name 引用的一行摘要，形成“常驻索引 + 按需详情”的双层结构。

2. 目录与文件结构

每个技能是 .agents/skills/ 下的一个子目录，最小结构如下（SKILL.md 第 33–39 行）：

.agents/skills/
└── my-skill/
    ├── SKILL.md          # 必需：frontmatter + 正文
    ├── workflow.md       # 可选：补充细节
    └── examples.md       # 可选：从 SKILL.md 中引用

SKILL.md 是唯一必需的文件，其余文件作为细节补充，从 SKILL.md 中用相对链接引用。当前仓库 .agents/skills/ 下已有 20 余个技能目录（flags、dce-edge、pr-status-triage、react-vendoring、sandbox-bench、gh-stack 等），其中 .agents/skills/README.md 是面向人的总览文档，与本文引用的 authoring-skills 技能互为印证。

Hub + Detail：复杂技能的拆分模式

对内容较多的技能，文档推荐“枢纽 + 细节”模式（SKILL.md 第 107–116 行），并给出了仓库内真实案例 pr-status-triage：

pr-status-triage/
├── SKILL.md         # 概述、快速命令、指向细节的链接
├── workflow.md      # 优先级判定与常见故障模式
└── local-repro.md   # CI 环境匹配的本地复现指南

实际查看 pr-status-triage/SKILL.md 可以看到该模式的完整落地：正文先给 “Use this skill when...” 触发语句，再给 7 步工作流、Quick Commands 代码块，最后以 References 小节相对链接 ./workflow.md 和 ./local-repro.md。要点是：保持 SKILL.md 作为可快速扫读（scannable）的入口，把深度内容外置。

3. Frontmatter 字段规范：只允许使用清单内字段

文档给出的权威字段模板（SKILL.md 第 43–56 行）如下：

---
name: my-skill # 必需。用于 $name 引用与 /name 斜杠命令
description: > # 必需。Claude 据此决定何时自动加载该技能
  说明覆盖什么、何时使用。包含文件名与关键词。
argument-hint: '<pr-number>' # 可选。提示预期参数
user-invocable: false # 可选。设为 false 从 / 菜单隐藏
disable-model-invocation: true # 可选。设为 true 禁止自动触发
allowed-tools: [Bash, Read] # 可选。无需额外授权即可使用的工具
model: opus # 可选。模型覆盖
context: fork # 可选。隔离的子代理执行
agent: Explore # 可选. 子代理类型（配合 context: fork）
---

逐字段说明：

字段	必填	作用
name	是	技能名，用于 $name 交叉引用和 /name 斜杠命令
description	是	自动激活的主要匹配面（primary matching surface）
argument-hint	否	自动补全时提示用户应提供的参数
user-invocable	否	false 时从 / 斜杠命令菜单中隐藏
disable-model-invocation	否	true 时阻止模型自动触发该技能
allowed-tools	否	技能激活期间可免授权使用的工具列表
model	否	该技能生效时的模型覆盖
context	否	fork 表示在隔离子代理中执行
agent	否	配合 context: fork 指定子代理类型

关键约束：只使用上表列出的字段，未知字段会被静默忽略（原文：“Only use fields from this list. Unknown fields are silently ignored.”）。.agents/skills/README.md 中的字段表与之基本一致，并额外列出了 hooks（技能生命周期钩子）字段，可作为补充参考。

仓库中的真实用法示例：

• flags/SKILL.md 只使用 name 与 description 两个必需字段，代表最常见的“最小 frontmatter”写法；
• gate-tests/SKILL.md 设置了 user-invocable: false，表示该技能只供模型自动触发、不出现在 / 菜单中；
• 本文的 authoring-skills/SKILL.md 自身同样是 user-invocable: false——一个“教 Agent 写技能”的内部技能，对人类用户不可直接调用是合理的。

4. 编写 Description：自动激活的匹配面

文档强调 description 是自动激活的首要匹配面（primary matching surface），应包含四个要素（SKILL.md 第 62–68 行）：

1. 技能覆盖的主题（What the skill covers）；
2. 使用场景（When to use it，触发情境）；
3. 技能引用的关键文件名（如 config-shared.ts）；
4. 用户或 Agent 可能提到的关键词（如 “feature flag”“DCE”）。

文档自带的正反对照（SKILL.md 第 69–77 行）：

# 反例：太模糊，无法可靠自动触发
description: Helps with flags.

# 正例：给出具体文件与概念，可匹配
description: >
  How to add or modify Next.js experimental feature flags end-to-end.
  Use when editing config-shared.ts, config-schema.ts, define-env-plugin.ts.

对照仓库里的实际技能可以验证该写法确实被严格执行。flags/SKILL.md 第 3–8 行 的 description 列出了 config-shared.ts、config-schema.ts、define-env.ts、next-server.ts、export/worker.ts、module.compiled.js 六个文件名，并点出 “runtime env-var branching vs separate bundle variants” 这一决策点；gate-tests/SKILL.md 的 description 则把 @gate / @force-gate 指令、it.skip 反模式、test/lib/gate/conditions.ts 文件与 __NEXT_TEST_AXIS 关键词全部纳入，使“转换 skip 逻辑”这类意图也能命中。可以推断：文件名是最强的匹配锚点——用户描述任务时大概率会提到要改的文件，description 中预置这些名字可显著提高自动加载命中率。

5. 正文写法：为“行动”而非“知识”而结构

SKILL.md 第 81–89 行 的 “Structure for Action” 五原则：

• 以 “Use this skill when...” 开头（SKILL.md 第 16 行 自身即遵循此例）；
• 包含分步骤程序（step-by-step procedures）；
• 提供可直接改用的代码模板（ready-to-adapt code templates）；
• 以验证命令收尾（verification commands）；
• 设 “Related Skills” 小节交叉引用相关技能。

以 flags/SKILL.md 为例，正文严格按“动作”组织：先给 “Required Wiring”（所有 flag 都要过 config-shared.ts 类型 → config-schema.ts zod schema 的接线清单），再按“flag 被消费的位置”给出两条分支决策（客户端打包走 define-env.ts；预编译运行时 bundle 走运行时 env var 或独立 bundle 变体），末尾的 Related Skills 用 $dce-edge、$react-vendoring、$runtime-debug 三个引用衔接相邻技能。再看 pr-status-triage/SKILL.md：7 步工作流全部是命令级动作（node scripts/pr-status.js --wait、gh run rerun <run-id> --failed 等），并给出可直接复制的 Quick Commands 块——这正是“让 Agent 知道该做什么”的典型形态。

6. 命名约定

命名规则（SKILL.md 第 101–105 行）：

• 短、有描述性、主题限定：如 flags、dce-edge、react-vendoring；
• 不加仓库名前缀——技能已经由 .agents/skills/ 目录限定作用域，next-flags 这类名字是冗余的；
• 多词用连字符连接（kebab-case）。

目录名同时就是 name 字段值与 $skill-name、/skill-name 命令中的名字，因此三者必须一致。仓库中的 pr-status-triage、sandbox-bench、deploy-release-test、backport-pr 均符合该约定。

7. 技能在仓库中的索引与引用链路

理解一个技能如何被整体系统发现和调度，需要把三处串起来：

1. AGENTS.md 常驻索引：AGENTS.md 第 427–442 行 的 “Specialized Skills” 小节逐行列出 $pr-status-triage、$create-pr、$flags 等技能的一行摘要；第 499–504 行在 “Development Anti-Patterns” 小节再次给出 $flags（.agents/skills/flags/SKILL.md）等运行时内部技能的路径指引。新增技能后，按规范应在这些位置补一行带 $name 的摘要。
2. 技能目录自发现：.agents/skills/<name>/SKILL.md 的 frontmatter name 与目录名一致，description 供模型匹配；仓库根目录的 CLAUDE.md 是指向 AGENTS.md 的符号链接，保证了不同 Agent 运行时读到同一份常驻约定。
3. 锁定文件：根目录 skills-lock.json 记录了通过外部来源安装的技能（当前为 gh-stack），包含 source、skillPath 与 computedHash 字段；从文件结构看，它用于校验已安装第三方技能内容的完整性，与本地手写的技能目录相区分。

另外注意区分：仓库根目录另有一个 skills/ 目录（含 next-dev-loop、next-cache-components-adoption 等），存放的是文档采纳类技能集合；本文讨论的规范明确限定于 .agents/skills/ 作用域，两者不要混淆。

8. 落地检查清单

按本文规范新建一个技能时，可对照以下清单自查（全部依据 authoring-skills/SKILL.md 原文约束）：

1. 目录：.agents/skills/<kebab-case-name>/SKILL.md，名称与 name 字段一致，无仓库前缀；
2. frontmatter：只含 name、description 等清单字段；description 覆盖“主题 + 触发场景 + 文件名 + 关键词”四要素，避免 “Helps with flags.” 式模糊描述；
3. 正文：以 “Use this skill when...” 开头；步骤化流程 + 可适配的代码模板 + 结尾验证命令；复杂内容拆到 workflow.md / examples.md 等细节文件并用相对链接引用；
4. 交叉引用：设 “Related Skills” 小节；同时在 AGENTS.md 相应小节补一行 $name 摘要；
5. 边界复核：确认该内容不是“每会话都需要的一句话护栏”——是的话放回 AGENTS.md，不建技能。

对照 flags、pr-status-triage、gate-tests 三个不同复杂度级别的现成实现，可以快速校准自己写的技能是否达到了同样的结构与信息密度。