前端如何编写优秀的 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 的灵魂，写好需遵循原则：

1. 同时写清'做什么'和'什么时候用'
   • ✅ 好的写法：Create React components with TypeScript, hooks, and proper file structure. Use when the user asks to create, generate, or scaffold a new React component.
   • ❌ 差的写法：Helps with React stuff.
2. 用第三人称描述
   • ✅ 好：Generates unit tests for React components using Vitest.
   • ❌ 不好：I can help you write tests for React.
3. 包含关键触发词 把用户可能提到的关键词写进去，比如 "component" "scaffold" "generate" "创建组件" 等。

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 个核心原则

## 原则一：只写 Agent 不知道的事
Agent 知道 React 怎么写、TypeScript 怎么用。你需要写的是**只存在于团队脑子里的知识**：状态管理用 zustand 不用 redux、接口请求统一走 `src/api/request.ts`、日期用 dayjs 不用 moment。

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

## 原则二：按风险等级调'管控力度'
不同任务的风险不同，给 Agent 的'自由空间'也应该不同。

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

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

## 原则三：内容分层加载，别一股脑全塞
Agent 的上下文窗口有限。更聪明的做法是**分层**：
- **第一层**（始终加载）：SKILL.md 里只放最核心的指令和规则，控制在 500 行以内。
- **第二层**（按需加载）：详细的规范文档、API 参考拆到 `references/` 目录。

注意：引用文件只支持一层深度。

## 原则四：用代码说话，少用文字解释
Agent 理解代码的能力远强于理解自然语言描述。直接贴一个代码示例，它就 100% 照着来。

## 原则五：画好三条线——能做、要问、别碰
每个 Skill 都**必须**画三条线，防止 Agent 越界。

操作边界

✅ 放手做：

• 在 src/components/ 下新建文件 ⚠️ 先问我：
• 要改 src/shared/ 或 src/utils/ 里的公共代码 🚫 绝对不要：
• 动任何 config 文件

## 原则六：多步任务用编号清单'锁死'顺序
编号清单给了 Agent 两样东西：**明确的先后顺序**和**可追踪的进度**。特别适合发布流程、环境部署、大功能开发。

## 原则七：确定性操作封装成脚本
能用脚本跑的，就别让 Agent 手写。原因：省上下文空间、结果 100% 一致。

## 原则八：交付前设一道'质检门'
加一个 Pre-Delivery Checklist，效果立竿见影。

交付检查（每次完成任务后必须执行）

确认以下每一项都通过后，再告诉用户'已完成'：

• 运行 npx tsc --noEmit 无报错
• 运行 npm run test 全部通过
• 代码中没有 console.log / debugger / TODO 注释

## 原则九：用参数让 Skill'一鱼多吃'
把可变的部分抽成参数，固定的部分写成规则。一个 Skill 覆盖 N 种场景，维护成本低。

## 原则十：告诉 Agent 你的项目有哪些'趁手工具'
列出项目已有的 npm scripts 和 CLI 工具，相当于给 Agent 发了一套'装备'。

# GitHub 优秀案例拆解

## 案例一：anthropics/skills —— 官方示范仓库
仓库地址：https://github.com/anthropics/skills
其中 `frontend-design` 这个 Skill 非常值得学习。它的正文给出了**设计决策框架**，教 Agent 怎么做设计决策，而非直接告诉用什么颜色。

## 案例二：webapp-testing —— 脚本集成模式
展示了如何用**决策树 + 脚本**来处理复杂工作流。亮点在于决策树清晰、脚本当黑盒用、有明确的反模式提示。

## 案例三：GitHub Copilot docs-agent —— 角色定位模式
展示了'角色定位法'的威力：明确角色、明确能力边界、给可执行命令。

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

假设团队有一套 React 组件开发规范，你想让 Agent 自动按规范生成组件。

**目录结构：**

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

**SKILL.md 完整内容：**

```markdown
--- 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

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

# 避坑指南

1. **description 写得太模糊**：明确能力 + 触发场景。
2. **正文太啰嗦**：只写它不知道的信息：团队规范、项目特殊约定。
3. **给太多选择**：给一个默认方案，必要时提供备选。
4. **忘记设边界**：一定要写 Boundaries 部分。
5. **名称太泛**：一看就知道干什么，如 `react-component`。

# 总结

写好一个 AI Agent Skill 的核心要点：
1. 只写 Agent 不知道的事：团队私有约定才值得写。
2. 按风险调管控力度：危险操作严格管控，创造性任务放手。
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 协作能力做一次基建升级。