别再堆万字 Prompt：用 Agent Skills 给团队写一个「前端 Review」Skill

别再堆万字 Prompt：用 Agent Skills 给团队写一个「前端 Review」Skill

团队里要是有人用 AI 帮着看 PR，你会很快撞上同一件事：每个人对话框里都塞着一份「前端审查规范」。今天加三条，明天删两条，有人复制的还是上个月那版。规范本身没错，错在它住错了地方------住在聊天记录里，而不是仓库里。

Agent Skills 干的事很朴素：把「怎么干某类活」收成一个文件夹，核心是一份 SKILL.md。助手需要时自己去读，不用每次把万字手册粘进 Prompt。2026 年 10 月 22 日，Anthropic 把这套开放标准捐给了 Linux 基金会旗下的 Agentic AI Foundation（AAIF）；规范继续开放，名字、logo、GitHub 组织和 agentskills.io 一并交出去，方便跨产品共用。

这篇不讲概念巡礼。目标就一个：你读完能把一份前端 Review Skill 拷进仓库，当天就能用。 文末有完整模板，配套 demo/ 目录也能直接跑校验脚本。

---

先分清：Prompt、AGENTS.md、Skill 各管啥

口头上大家爱混着说，落地时最好分开：

东西	更像什么	适合放什么
一次性 Prompt	当面交代	「这次帮我看这个 diff」
项目级说明（如 AGENTS.md 一类）	入职手册封面	仓库约定、目录结构、默认语气
Agent Skill（SKILL.md）	墙上某一张作业卡	某一类任务的固定工序（例如前端 Review）

Skill 的价值不在「写得更长」，而在可发现、可复用、按需加载 。规范里把它叫 progressive disclosure（渐进式披露）：启动时只看每个 skill 的 name + description；真匹配到任务，才读完整 SKILL.md；脚本和参考文档再往后按需打开。这样你可以在仓库里挂很多 skill，也不用一上来把上下文塞爆。

一手说明见：Agent Skills 规范、Anthropic 捐赠公告（2026-10-22）。

---

一个 Skill 目录到底长什么样

最少只要一份文件：

frontend-review/
└── SKILL.md

完整一点可以长这样（后面三个目录都是可选）：

frontend-review/
├── SKILL.md          # 必需：YAML 头 + Markdown 正文
├── scripts/          # 可选：可执行脚本
├── references/       # 可选：按需阅读的补充说明
└── assets/           # 可选：模板、静态资源

SKILL.md 必须以 YAML frontmatter 开头。规范要求至少两个字段：

• name ：小写字母 / 数字 / 连字符，必须和目录名一致 ，不能 --，不能首尾是 -
• description ：说清楚做什么、什么时候用；这是助手决定「要不要启用你」的主依据

可选字段还有 license、compatibility、metadata、allowed-tools（实验性）等。正文怎么写没有强制模板，但官方建议主体别太膨胀：详细资料拆到 references/，能脚本化的放进 scripts/。

最小骨架长这样：

---
name: frontend-review
description: Review frontend code changes in this repo. Use when the user asks for code review, PR review, 前端 review, 检查改动, or before merging UI changes.
---

# 前端 Review

按顺序执行：看清改动范围 → 类型检查 → Lint → 危险改动禁区。
输出固定结构的结论，少写空话。

就这几行，已经比「把审查规范粘进每一个新对话」强------因为它进了版本库，改一处，全队下次会话都能吃到。

---

为什么前端 Review 适合当第一个 Skill

不是所有流程都值得做成 skill。前端 Review 刚好踩中几个点：

1. 步骤稳定：先看范围，再 typecheck，再 lint，再盯敏感面。人审也是这个顺序。
2. 命令能跑 ：tsc --noEmit、eslint、biome 比「感觉这段写得优雅」可靠。
3. 禁区明确 ：.env、鉴权、dangerouslySetInnerHTML、未校验 origin 的 postMessage......列得出清单。
4. 团队口径要统一：最怕每个人 Prompt 里各写各的「必须改 / 建议改」。

一句话：把「我们组约定怎么审前端」从聊天记录搬进仓库。

---

动手：写一份能用的「前端 Review」Skill

下面这份和文末 demo/frontend-review/SKILL.md 同源，可以直接复制。按你们仓库脚本名改两处即可。

---
name: frontend-review
description: Review frontend code changes in this repo. Use when the user asks for code review, PR review, 前端 review, 检查改动, 帮我看看这段代码, or before merging UI/React/Vue/Next changes. Runs typecheck then lint, then checks a deny-list of risky paths. Do not invent security exploits; only report defensive findings.
license: MIT
metadata:
  author: team-frontend
  version: "1.0"
  audience: frontend
---

# 前端 Review Skill

你在帮这个仓库做**前端改动审查**。目标不是写长篇作文，而是按固定顺序把关，并给出可执行结论。

## 何时启用

用户提到 code review / PR review / 检查改动 / 帮我看看这段前端代码 / merge 前自查时启用本 skill。

## 硬规矩（按顺序，不要跳）

1. **看清改动范围**
   - 先列出本次相关文件（`git status` / `git diff --stat`，或用户粘贴的片段）。
   - 超出需求的顺手重构：标成「建议另开 PR」，默认不要帮用户直接改。

2. **类型检查**
   - 仓库有 TypeScript 时优先跑项目脚本，例如：
     - `pnpm typecheck` / `npm run typecheck` / `npx tsc --noEmit`
   - 有报错：先把错误路径和信息贴出来，再谈风格。

3. **Lint**
   - 有 ESLint / Biome / Oxlint 就跑对应脚本，例如 `pnpm lint`。
   - 只修与本次改动相关的告警；全仓历史债另记，不借机大扫除。

4. **危险改动禁区（防御清单）**
   若 diff 触及下列路径或模式，必须**显式标红**，并要求人工确认后再继续：
   - `**/.env*`、密钥、Token、私钥、内网地址硬编码
   - `**/auth/**`、登录态、Cookie / LocalStorage 写敏感字段
   - `dangerouslySetInnerHTML`、未消毒的 HTML 拼接
   - `postMessage` / `iframe` 未校验 `origin`
   - 依赖锁文件被无关改动大面积重写
   - 删除或弱化 CSP、CORS、CSRF、权限校验相关代码
   - 把用户输入直接拼进 `eval`、动态 `Function`、未校验的路由跳转

   只做**防御向说明**：指出风险点与建议改法。不要给出可复现的攻击步骤、PoC、payload。

## 输出格式（照抄结构）

（输出模板开始）

## Review 结论
- 结论：通过 / 有条件通过 / 不通过
- 一句话原因：...

## 已执行检查
- [ ] 改动范围已核对
- [ ] 类型检查：通过 / 失败 / 仓库无脚本（说明）
- [ ] Lint：通过 / 失败 / 仓库无脚本（说明）
- [ ] 禁区：未命中 / 命中（列出文件）

## 必须改
1. ...

## 建议改
1. ...

## 可以以后再说
1. ...

（输出模板结束）

## 写作语气

- 像同事在评审：短句、点名文件、少形容词。
- 不确定就说不确定，并写出要用户确认的点。

禁区细则可以另放 references/denylist.md，正文里链过去------这正好吃到 progressive disclosure：平常不占上下文，真碰到敏感改动再展开。

---

拷进仓库：怎么放、怎么验、怎么叫它

1）目录放哪

官方 Quickstart（以 VS Code 为例）默认找项目下的：

mkdir -p .agents/skills
cp -R frontend-review .agents/skills/

不同产品扫描路径可能略有差异，但文件格式是同一套 。以你正在用的 Agent 文档为准；关键是：name 字段和文件夹名都叫 frontend-review。

2）先校验 skill 自己写得对不对

配套脚本不连网，只检查 frontmatter、命名、行数：

bash demo/frontend-review/scripts/check-skill.sh

你应该看到类似输出：

OK:   frontmatter 分隔符
OK:   name=frontend-review
OK:   description 长度 ...
OK:   SKILL.md 行数 ...
全部通过。把本目录拷到仓库的 .agents/skills/frontend-review/ 即可试用。

规范也提到可用官方参考实现里的 skills-ref validate ./my-skill 做更完整校验；上面这个 bash 脚本是给「零依赖、当场能跑」准备的。

3）对话里怎么触发

新开一轮 Agent 对话，直接说人话即可，例如：

按前端 review skill，审查当前改动。先 typecheck 再 lint。

或：

这是一段 React PR，做 code review。

助手应先靠 description 命中 frontend-review，再加载正文，按四道关卡输出。若它空口夸代码、不跑检查，把 skill 里的「硬规矩」再写狠一点，或换到更听话的 Agent 模式 / 模型------工具服从度因产品而异，这点官方 Quickstart 也老实写了。

4）和 CI 的分工

Skill 是会话里的工序卡 ；CI 是合入门槛。前者提高日常自查效率，后者不该被取代。typecheck / lint 该红还是红。

---

一段「像样」的 Review 输出长什么样

假设同事改了登录页附近的组件，还顺手动了 postMessage 监听。Skill 跑完后，理想输出接近下面这样（示意，不是让你背模板）：

## Review 结论
- 结论：有条件通过
- 一句话原因：类型检查和 Lint 过了，但 `src/features/auth/sessionBridge.ts` 的 postMessage 未校验 origin，需人工确认。

## 已执行检查
- [x] 改动范围已核对（5 files）
- [x] 类型检查：通过（pnpm typecheck）
- [x] Lint：通过（pnpm lint）
- [x] 禁区：命中 sessionBridge.ts（postMessage）

## 必须改
1. `sessionBridge.ts`：处理消息前校验 `event.origin`，只接受白名单域名；来源不明时直接 return。
2. 不要把 access token 写入 `localStorage` 的调试字段；改用现有 session 封装。

## 建议改
1. 登录按钮 loading 态与错误文案拆开，避免失败时按钮一直转圈。

## 可以以后再说
1. 顺手重排的无关 import，建议另开 PR，别和鉴权改动绑在一起。

注意两点：

• 「有条件通过」是常态，不是和稀泥。禁区命中就该停一下。
• 必须改 / 建议改 / 以后再说 分桶，比一篇小作文好合并。人审也省时间：你只要核对「必须改」有没有漏。

如果你发现助手仍在输出「整体不错，建议注意性能」这种空话，回去改 skill 正文：把输出格式写成强制结构，并明确禁止无文件路径的夸赞。

---

团队落地：别一次发明十二张作业卡

建议按这个顺序扩：

1. 先上 Review（本文）：收益立刻体现在每天的 PR 对话里。
2. 再补「新建页面 / 新建组件」：规定目录、命名、是否要 story / 测试。
3. 最后才做窄域 skill（例如「改图表」「改表单校验」），避免一上来技能列表比组件库还长。

协作上有三条很实用：

• Skill 的修改走 PR，reviewer 看的是「工序有没有变严/变松」，不是文采。
• description 变更要回归：用团队高频口头禅试三轮触发。
• 在 README 或贡献指南里写一句：「前端自查可先喊 frontend-review skill」------比口头安利持久。

和「把规范写进系统 Prompt」比，Skill 多了两样东西：版本 和按需加载。系统 Prompt 一改影响所有对话；Skill 只在相关任务被点亮，改起来也更敢改。

description 怎么写，才叫得出来

很多人把 description 写成「帮助审查代码」------太虚，助手不知道何时启用。

更好的写法同时回答两件事：会做什么 ，以及用户可能怎么喊你：

description: Review frontend code changes in this repo. Use when the user asks for code review, PR review, 前端 review, 检查改动, 帮我看看这段代码, or before merging UI/React/Vue/Next changes.

中英文关键词都可以放一点，贴合你们团队真实口头禅。改完 description 后，用三五句真实会说的话试触发；该出手时不出手，多半是描述太窄或太飘，而不是正文写得不够长。

---

常见坑（我们踩过或看别人踩过）

1. name 和目录名不一致

   规范写明必须一致。目录叫 frontend-review，name 却写成 FrontendReview，属于直接不合格。

2. 把整本设计文档塞进 SKILL.md

   规范建议主体控制体量，细节外置。Review skill 尤其别把三年前的组件规范全文贴进来；链到 references/ 或仓库文档路径即可。

3. 禁区写成「攻击教程」

   防御清单只写「碰了什么要标红、建议怎么收紧」。不写 PoC，不写 payload。第三方 skill 更要先通读 scripts/ 再装------官方研究文也强调只信任审过的来源。

4. 期望 skill 替代人审

   它擅长固定工序和漏项提醒；产品语义、交互是否合理，还是人说了算。结论里留「有条件通过」比硬给「通过」更诚实。

5. 每人本地一份互不同步

   Skill 进 Git 才有意义。Review 规则的改动走正常 PR，别再私发给同事一份 .docx。

---

你读完最少能带走什么

1. Agent Skills = 文件夹 + SKILL.md；跨产品的开放格式，现由 AAIF 托管。
2. 渐进式披露：先 name/description，用到再加载正文和附件。
3. 前端 Review 很适合做成团队第一个 skill：顺序固定、命令可跑、禁区可列。
4. 文内模板 + demo/frontend-review/ 可直接拷贝；先跑 scripts/check-skill.sh，再放进 .agents/skills/。

下次想加「改组件必须补单测」「改样式先搜 design token」之类的规矩，不要新开一份万字 Prompt------在同一份 SKILL.md 里加一条硬规矩，或者再挂一个更窄的 skill。作业卡越贴越全，聊天框反而能变短。

参考

• Donating Agent Skills to the Agentic AI Foundation（Anthropic，2026-10-22）
• Agent Skills Specification
• Agent Skills Quickstart
• agentskills/agentskills（GitHub）
• Equipping agents for the real world with Agent Skills（Anthropic，背景）