前端如何编写高质量的 AI Agent Skills

目录中各文件夹的定位如下：

SKILL.md 文件详解

目录结构搞清楚了，接下来重点讲 SKILL.md 文件怎么写。它由两部分组成：YAML 头信息 + Markdown 正文。

YAML 头信息（Frontmatter）

---
name: react-component-creator
description: Create React components following team conventions with TypeScript, hooks patterns, and proper file structure. Use when the user asks to create, generate, or scaffold a new React component.
---

两个必填字段：

description 是整个 Skill 的灵魂，写好它需要遵循几个原则：

原则一：同时写清'做什么'和'什么时候用'

# ✅ 好的写法 —— 既有能力描述，又有触发场景
description: Create React components with TypeScript, hooks, and proper file structure. Use when the user asks to create, generate, or scaffold a new React component.

# ❌ 差的写法 —— 太模糊，Agent 不知道什么时候该触发
description: Helps with React stuff.

原则二：用第三人称描述

# ✅ 好 description: Generates unit tests for React components using Vitest.
# ❌ 不好 description: I can help you write tests for React.

原则三：包含关键触发词

把用户可能提到的关键词写进去，比如 "component" "scaffold" "generate" "创建组件" 等，这样 Agent 匹配时更精准。

Markdown 正文

正文是给 Agent 看的'操作指南'。来看一个精简但完整的例子：

--- name: react-component-creator description: Create React components with TypeScript and hooks. Use when the user asks to create, generate, or scaffold a React component. ---

# React Component Creator

## Instructions
1. Create component file at `src/components/[ComponentName]/index.tsx`
2. Use function component with TypeScript interface for props
3. Export as named export (not default export)

## Component Template
```tsx
interface [Name]Props {
  // props here
}
export function [Name]({ ...props }: [Name]Props) {
  return <section>...</section>
}

Conventions

• File naming: PascalCase for components, camelCase for hooks
• One component per file
• Co-locate styles: [ComponentName].module.css
• Co-locate tests: [ComponentName].test.tsx

# 写好 Skill 的 10 个核心原则

知道了怎么写一个 SKILL.md 之后，怎么把它**写好**才是关键。我研究了大量优秀的 Skills 案例，也在自己项目里反复试错，最后总结出这 10 个核心原则。它们各自解决的问题完全不同，缺哪个都会踩坑。

![10 个核心原则](https://qiniu.meowparty.cn/coder.2023/2026-03-24/874086bce69deef026f30ccef76095f4.jpeg)

## 原则一：只写 Agent 不知道的事

Agent 已经是一个训练有素的'高级开发'了——它知道 React 怎么写、TypeScript 怎么用、怎么发起 HTTP 请求。你不需要教它这些。

你真正需要写的，是那些**只存在于你团队脑子里**的知识：我们的状态管理用 zustand 不用 redux、接口请求统一走 `src/api/request.ts` 里封装的方法、日期用 dayjs 不用 moment...这些'潜规则'Agent 没法从公开知识里推断出来。

举个例子，下面两种写法对比：

```typescript
// ❌ 浪费：Agent 自己就知道怎么用 fetch
When making HTTP requests, you can use the fetch API. The fetch function takes a URL and an options object containing method, headers, and body...

// ✅ 有价值：这是你们团队的私有约定
All API calls MUST use the project's request wrapper:
```ts
import { request } from '@/api/request'
// GET
const users = await request.get<User[]>('/api/users')
// POST
await request.post('/api/users', { name: 'Winty' })

Do NOT use raw fetch or axios directly.

判断标准很简单：这段话如果对一个刚入职的资深前端也需要交代，那就值得写；如果是前端基础知识，就删掉。

## 原则二：按风险等级调'管控力度'

写 Skill 指令就像设计道路——在高速公路上你需要严格的车道线和护栏，在公园小路上随意走走就好。不同任务的风险不同，给 Agent 的'自由空间'也应该不同。

我把它分成三档：

| 管控力度 | 什么时候用 | 实际场景 |
| --- | --- | --- |
| **松** — 只给方向 | 方案灵活、不会出大问题 | '帮我 Review 这段代码' |
| **中** — 给模板 | 有推荐做法、但允许调整 | '按团队规范写一个组件' |
| **严** — 给精确步骤 | 操作敏感、一步都不能错 | '执行数据库迁移' |

比如在我的项目里，写一个新的 React 组件我会给'中'——提供模板和规范，但具体 JSX 怎么写 Agent 自己判断就好。但如果是修改 Nginx 配置、执行数据库迁移这种，我会给'严'——精确到每一条命令，不留任何发挥空间。

记住：越危险的操作越要'收紧'，越创造性的任务越要'放手'。

## 原则三：内容分层加载，别一股脑全塞

Agent 的上下文窗口就像你的电脑内存——容量有限。如果你把所有规范、文档、示例一股脑全写进 SKILL.md，就像同时开了 200 个浏览器标签页，系统肯定卡死。

更聪明的做法是**分层**：

- **第一层**（始终加载）：SKILL.md 里只放最核心的指令和规则，控制在 500 行以内
- **第二层**（按需加载）：详细的规范文档、API 参考拆到 `references/` 目录

```markdown
# React Component Skill
## Core Rules
1. Named exports only
2. CSS Modules for styling
3. Co-locate tests

## Need More Detail?
- Naming conventions → see [naming.md](references/naming.md)
- State management patterns → see [state.md](references/state.md)
- Accessibility checklist → see [a11y.md](references/a11y.md)

当用户只是让 Agent 写个简单组件时，它看 Core Rules 就够了。只有涉及无障碍适配时，Agent 才会去读 a11y.md。这样每次执行任务时，上下文窗口里只有'用得着'的内容。

注意一个坑：引用文件只支持一层深度。不要让 naming.md 里面再引用 naming-detail.md，Agent 大概率不会读到那么深。

原则四：用代码说话，少用文字解释

这是我自己写 Skill 最深的一个体会：当你发现自己在写第三段'解释'的时候，停下来，换一个代码示例就够了。

Agent 理解代码的能力远强于理解自然语言描述。你用文字写'组件的 Props 要用 interface 定义，命名为组件名 + Props 后缀，放在组件函数的上面'——Agent 可能理解出好几种写法。但你直接贴一个代码示例，它就 100% 照着来：

## Custom Hook 规范
```ts
// ✅ 标准写法 — 直接照这个格式来
export function useUserList(params: UseUserListParams) {
  const [users, setUsers] = useState<User[]>([])
  const [loading, setLoading] = useState(false)
  const fetch = useCallback(async () => {
    setLoading(true)
    try {
      const data = await request.get<User[]>('/api/users', { params })
      setUsers(data)
    } finally {
      setLoading(false)
    }
  }, [params])
  useEffect(() => { fetch() }, [fetch])
  return { users, loading, refresh: fetch }
}

Naming: use + resource name, e.g. useOrderDetail, useCartItems Return: always return an object (not array), include a refresh method

一个真实的例子，比三段文字描述更精确、更省空间、也更不容易被误解。

## 原则五：画好三条线——能做、要问、别碰

Agent 没有'职场常识'。你不告诉它什么不能动，它真可能顺手帮你重构了 `webpack.config.js`，或者把 `.env` 里的密钥提交到仓库里。

所以每个 Skill 都**必须**画三条线：

```markdown
## 操作边界
✅ **放手做：**
- 在 `src/components/` 下新建文件
- 在 `src/hooks/` 下新建 custom hook
- 修改当前任务相关的组件和样式

⚠️ **先问我：**
- 要改 `src/shared/` 或 `src/utils/` 里的公共代码
- 要新加一个 npm 依赖
- 要改路由配置或全局状态

🚫 **绝对不要：**
- 动任何 config 文件（webpack/vite/tsconfig/eslint）
- 删除或修改已有的测试用例
- 在代码里硬编码环境变量或密钥

实际用下来，这三条线对 Agent 的约束力非常强。我有一次没写 🚫 列表，结果 Agent 帮我'优化'了 ESLint 配置，直接把 no-console 规则关了...加了边界之后就再没出过这种事。

原则六：多步任务用编号清单'锁死'顺序

让 Agent 写一段代码、一个函数，它很擅长。但让它按特定顺序做一连串操作，就容易出乱子——跳步、漏步、颠倒顺序都有可能。

编号清单是最简单有效的解药：

## 新页面开发流程
按照以下顺序执行，不要跳步：
1. 在 `src/pages/` 下创建页面目录和 `index.tsx`
2. 在 `src/router/config.ts` 中注册路由
3. 编写页面基础结构和布局
4. 接入 API 数据，完成主要交互逻辑
5. 编写单元测试 `__tests__/index.test.tsx`
6. 运行 `npm run test` 确认通过
7. 运行 `npm run build` 确认构建无报错

为什么编号清单管用？因为它给了 Agent 两样东西：明确的先后顺序和可追踪的进度。Agent 做完第 3 步，它知道下一步该做什么，不需要自己判断。

这个特别适合发布流程、环境部署、大功能开发这类'步骤不能乱来'的场景。

原则七：确定性操作封装成脚本

有一类操作是'不管谁来做，结果都应该一模一样'的——建目录结构、生成模板文件、注册路由、格式化代码。这种操作你用文字描述 10 行，不如包成一个脚本一行搞定。

## 创建新组件
不要手动创建文件。运行脚手架脚本：
```bash
node scripts/create-component.js UserCard

脚本会自动完成：

• 创建 src/components/UserCard/ 目录
• 生成 index.tsx（含 Props interface 模板）
• 生成 UserCard.module.css（含基础类名）
• 生成 UserCard.test.tsx（含 render 基础用例）
• 在 src/components/index.ts 中追加 export

查看所有选项：node scripts/create-component.js --help

为什么要这么做？两个原因：

1. **省上下文空间**。脚本细节不需要出现在 Skill 里，Agent 只要知道'调哪个命令'就行
2. **结果 100% 一致**。Agent 手写可能漏掉 export 注册或者文件名大小写写错，但脚本不会

简单说：**能用脚本跑的，就别让 Agent 手写。**

## 原则八：交付前设一道'质检门'

你一定遇到过这种场景：Agent 信心满满地说'搞定了'，你一看——TypeScript 编译报错、测试没跑、甚至 `console.log` 还留着三四处。

问题不是 Agent 能力不行，而是你没告诉它**交活之前该检查什么**。加一个 Pre-Delivery Checklist，效果立竿见影：

```markdown
## 交付检查（每次完成任务后必须执行）
确认以下每一项都通过后，再告诉用户'已完成'：
- [ ] 运行 `npx tsc --noEmit` 无报错
- [ ] 运行 `npm run test` 全部通过
- [ ] 代码中没有 console.log / debugger / TODO 注释
- [ ] 新增的 Props 都有 JSDoc 注释
- [ ] 可交互元素有 aria-label 或 role 属性
- [ ] 组件在不传任何 props 时不会崩溃（有合理默认值）
- [ ] 新增文件已在 barrel file 中 export

你可以把它理解成代码的'出厂质检单'。我在自己项目里加了这道关之后，Agent 交付的代码返工率降了很多。关键是要写得具体——'代码质量要好'没有用，'运行 npx tsc --noEmit 无报错'才有用。

原则九：用参数让 Skill '一鱼多吃'

你不太可能为 UserCard、ProductCard、OrderCard 各写一个 Skill 吧？用参数化设计，一个 Skill 就能通吃所有组件的生成。

核心思路是：把可变的部分抽成参数，固定的部分写成规则。

## 输入参数
| 参数 | 必填 | 默认值 | 说明 |
|-----|------|-------|------|
| 组件名称 | 是 | - | PascalCase，如 UserCard |
| 样式方案 | 否 | css-modules | 可选 css-modules / tailwind |
| 是否生成测试 | 否 | 是 | 设为'否'可跳过测试文件 |
| 是否生成 Story | 否 | 否 | Storybook 文件 |

## 输出文件
根据参数生成以下文件：
- `src/components/{组件名称}/index.tsx` ← 始终生成
- `src/components/{组件名称}/{组件名称}.module.css` ← 样式方案为 css-modules 时
- `src/components/{组件名称}/{组件名称}.test.tsx` ← 开启测试时
- `src/components/{组件名称}/{组件名称}.stories.tsx` ← 开启 Story 时

这样一来，用户说'帮我创建一个 OrderCard 组件，用 Tailwind 样式，不需要 Storybook'，Agent 就能自动匹配参数执行。一个 Skill 覆盖 N 种场景，维护成本也低很多。

原则十：告诉 Agent 你的项目有哪些'趁手工具'

大多数成熟项目都有一堆好用的 npm scripts 和 CLI 工具，但 Agent 完全不知道它们的存在。你不说，它就会自己'手搓'一个本该一行命令搞定的操作。

在 Skill 里列出项目已有的工具清单，相当于给 Agent 发了一套'装备'：

## 项目工具箱
本项目提供了以下开发工具，请优先使用：
| 命令 | 用途 | 什么时候用 |
|-----|------|-----------|
| `npx plop component` | 创建组件脚手架 | 新建任何 React 组件时 |
| `npm run codegen` | 从 OpenAPI 生成 API 类型 | 后端接口有更新时 |
| `npm run analyze` | 分析打包体积 | 添加新依赖或大改动后 |
| `npm run lint:fix` | 自动修复 lint 问题 | 代码写完后 |
| `npm run test:visual` | 跑视觉回归测试 | 改了 UI 样式后 |

## 什么时候用工具 vs 手写
-**用工具**：脚手架搭建、代码生成、构建部署、格式化
-**手写**：业务逻辑、自定义 Hook、复杂交互组件

创建新组件时，**始终**优先用 `npx plop component` 而不是手动建文件。

这个和上面'原则七'的区别在于：原则七是说'把重复操作封装成脚本'，这里是说'把已有的工具告诉 Agent'。一个是造工具，一个是介绍工具。两者配合起来，Agent 就能像一个熟悉项目的老员工一样干活——知道该用什么工具、知道工具在哪。

GitHub 优秀案例拆解

说了这么多写法要点，光说不练假把式。我们来看看 GitHub 上几个高质量的 Skills 案例，学学别人是怎么写的。

案例一：anthropics/skills —— 官方示范仓库

仓库地址：https://github.com/anthropics/skills （⭐ 71k+）

这是 Anthropic 官方开源的 Skills 集合，涵盖了创意设计、技术开发、企业沟通、文档处理等多个方向。

其中 frontend-design 这个 Skill 非常值得前端同学学习。来看它的核心写法：

---
name: frontend-design
description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, or applications.
---

它的正文最精彩的部分是设计决策框架：

## Design Thinking
Before coding, understand the context and commit to a BOLD aesthetic direction:
- **Purpose**: What problem does this interface solve? Who uses it?
- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, luxury/refined, playful/toy-like...
- **Constraints**: Technical requirements (framework, performance, accessibility)
- **Differentiation**: What makes this UNFORGETTABLE?

这个案例好在哪里？

1. description 写得精准：既描述了能力（create frontend interfaces），又明确了触发时机（when the user asks to build web components, pages...）
2. 给出思考框架：不是直接告诉 Agent '用什么颜色'，而是教它'怎么做设计决策'
3. 设定审美边界：明确禁止了