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

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

SKILL.md 文件详解

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

1. 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 匹配时更精准。

2. 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 之后，怎么把它写好才是关键。基于大量优秀案例和实践试错，总结出这 10 个核心原则。它们各自解决的问题完全不同，缺哪个都会踩坑。

### 原则一：只写 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. 设定审美边界：明确禁止了 AI 味的设计（如 Inter 字体、紫色渐变等）

案例二：webapp-testing —— 脚本集成模式

同样来自 anthropics/skills，这个 Skill 展示了如何用决策树 + 脚本来处理复杂工作流：

## Decision Tree: Choosing Your Approach
User task → Is it static HTML?
  ├─ Yes → Read HTML file directly to identify selectors
  │         └─ Write Playwright script using selectors
  │     └─ No (dynamic webapp) → Is the server already running?
  │         ├─ No → Run: python scripts/with_server.py --help
  │         └─ Yes → Reconnaissance-then-action:
  │             1. Navigate and wait for networkidle
  │             2. Take screenshot or inspect DOM
  │             3. Identify selectors from rendered state
  │             4. Execute actions with discovered selectors

这个写法的亮点在于：

1. 决策树清晰：Agent 能快速判断走哪条路径
2. 脚本当黑盒用：不需要把脚本内容加载到上下文，用 --help 了解用法后直接调用
3. 有明确的反模式提示：用 ❌ 和 ✅ 标记常见陷阱

案例三：GitHub Copilot docs-agent —— 角色定位模式

来自 GitHub 官方博客对 2500+ 个 agents.md 的最佳实践总结：

---
name: docs_agent
description: Expert technical writer for this project
---
You are an expert technical writer for this project.

## Your role
- You are fluent in Markdown and can read TypeScript code
- You write for a developer audience
- Your task: read code from `src/` and generate documentation in `docs/`

## Commands you can use
Build docs: `npm run docs:build`
Lint markdown: `npx markdownlint docs/`

## Boundaries
- ✅ Always do: Write new files to `docs/`, follow style examples
- ⚠️ Ask first: Before modifying existing documents in a major way
- 🚫 Never do: Modify code in `src/`, edit config files, commit secrets

这个案例展示了角色定位法的威力：

• 明确角色：不是 helpful assistant，而是 expert technical writer
• 明确能力边界：read from src/ 但 write to docs/
• 给可执行命令：Agent 可以自己跑 npm run docs:build 来验证结果

前端实战：写一个组件生成 Skill

学了这么多理论和案例，是时候动手了！假设你的团队有一套 React 组件开发规范，你想让 Agent 自动按规范生成组件，那我们一步步来写一个。

目录结构

.cursor/
└── skills/
    └── react-component/
        ├── SKILL.md
        └── references/
            └── conventions.md

SKILL.md 完整内容

---
name: react-component
description: Scaffold React components with TypeScript following team conventions. Use when the user asks to create, generate, or scaffold a React component, or mentions creating a new UI element.
---

# React Component Generator

## File Structure
For a component named `UserCard`:

src/components/UserCard/ ├── index.tsx # Component implementation ├── UserCard.module.css # Scoped styles ├── UserCard.test.tsx # Unit tests └── types.ts # Type definitions (if complex)

## Implementation Template

```tsx
import styles from './UserCard.module.css'

interface UserCardProps {
  name: string
  avatar?: string
  onClick?: () => void
}

export function UserCard({ name, avatar, onClick }: UserCardProps) {
  return (
    <section className={styles.container} onClick={onClick}>
      {avatar && <img src={avatar} alt={name} className={styles.avatar} />}
      <span className={styles.name}>{name}</span>
    </section>
  )
}

Rules

1. Named exports only, no default exports
2. Props interface in same file (unless 10+ props → extract to types.ts)
3. Use CSS Modules for styling, BEM-like class naming
4. Hooks extract to useXxx.ts when logic exceeds 15 lines
5. Every component must have at least one test covering render + key interaction

Test Template

import { render, screen } from '@testing-library/react'
import { UserCard } from '.'

describe('UserCard', () => {
  it('renders user name', () => {
    render(<UserCard name="Winty" />)
    expect(screen.getByText('Winty')).toBeInTheDocument()
  })
})

Boundaries

• ✅ Create files in src/components/
• ⚠️ Ask before modifying existing shared components
• 🚫 Never modify src/utils/ or config files

Detailed Conventions

For complete coding standards, see conventions.md

这个 Skill 只有约 60 行正文，但信息密度很高：有文件结构、代码模板、规则清单、测试模板和明确边界。Agent 拿到后能直接执行，不需要额外猜测。

## 避坑指南

有了实战经验，再来看看常见的坑。这些都是我踩过或者看别人踩过的，帮大家提前避开：

### 1. description 写得太模糊

```markdown
# ❌ Agent 完全不知道什么时候该用你
description: Helps with frontend stuff.

# ✅ 明确能力 + 触发场景
description: Create and style React components with TypeScript and CSS Modules. Use when building UI components, pages, or layouts.

2. 正文太啰嗦

AI Agent 已经很聪明了，不需要解释什么是 React、什么是 TypeScript。只写它不知道的信息：你们团队的规范、项目的特殊约定、偏好的技术方案。

3. 给太多选择

# ❌ Agent 会困惑到底该用哪个
You can use styled-components, or CSS Modules, or Tailwind, or Emotion...

# ✅ 给一个默认方案，必要时提供备选
Use CSS Modules for component styling. For utility-based layouts, use Tailwind CSS classes instead.

4. 忘记设边界

没有边界的 Skill，就像没有护栏的高速公路。Agent 可能会：

• 改了不该改的配置文件
• 删了别人的代码
• 往仓库里提交了密钥

一定要写 Boundaries 部分！

5. 名称太泛

# ❌ 毫无辨识度
name: helper
name: utils
name: tools

# ✅ 一看就知道干什么
name: react-component
name: api-test-generator
name: commit-message

总结

最后总结一下，写好一个 AI Agent Skill 的核心要点：

1. 只写 Agent 不知道的事：团队私有约定才值得写，前端基础知识不用教
2. 按风险调管控力度：危险操作严格管控，创造性任务放手让 Agent 发挥
3. 内容分层加载：核心规则放 SKILL.md，详细文档拆到 references/
4. 用代码说话：一个真实的代码示例，顶三段文字解释
5. 画好三条线：能做 / 要问 / 别碰，防止 Agent 越界
6. 多步任务锁顺序：编号清单保证步骤不乱、不漏
7. 确定性操作封装脚本：能用脚本跑的，就别让 Agent 手写
8. 交付前设质检门：Pre-Delivery Checklist 让交付质量翻倍
9. 参数化设计：一个 Skill 搞定 N 种场景，一鱼多吃
10. 亮出项目工具箱：告诉 Agent 有哪些趁手工具可以用

Agent Skills 已经被 Cursor、Claude、GitHub Copilot 等主流工具采纳，是一个开放标准。现在花时间学好它的写法，相当于给你的 AI 协作能力做一次基建升级。

看完别光收藏，建议先从你们团队最痛的那个点开始——比如组件规范、代码风格、提交格式——写你的第一个 Skill 试试。

如果你想快速上手，这几个资源值得收藏：

• 官方规范：https://agentskills.io
• 官方示例仓库：https://github.com/anthropics/skills
• Cursor 官方文档：https://cursor.com/docs/context/skills
• GitHub 最佳实践：How to write a great agents.md