前端如何编写优秀的 AI Agent Skills。首先解释了 Agent Skills 的概念及其作为开放标准的背景，涵盖了其在 Cursor、Claude 和 GitHub Copilot 中的存储位置和目录结构。文章重点解析了 SKILL.md 文件的编写方法，包括 YAML 元数据和 Markdown 正文。随后总结了写好 Skill 的十大核心原则，如只写团队私有知识、按风险分级管控、内容分层加载、用代码示例代替文字解释、设定操作边界等。最后通过 GitHub 官方案例和前端实战示例，演示了如何构建高效的组件生成 Skill，并提供了避坑指南，帮助开发者提升与 AI 协作的效率和质量。
用 Cursor 写代码时，团队有组件规范但 AI 生成风格对不上，需要手动修改。这不是 AI 不够聪明，而是没有'教'过它。
从 Cursor、Claude Code 到 GitHub Copilot，AI 编码工具正在进化成能自主执行任务的 Agent。在此趋势下，Agent Skills 成为标配——它是写给 AI 的'操作手册'，教会它一项技能，它就能在合适场景自动调用。
本文介绍 Skills 是什么、怎么写好以及参考案例，适用于 Cursor、Claude 或 GitHub Copilot。
Agent Skills 是一个开放标准（Open Standard），由 Anthropic 发起，已被 Cursor、GitHub Copilot、Claude Code 等主流 AI 编码工具采纳。官方规范地址：https://agentskills.io
一个 Skill 本质上是一个文件夹，核心是 SKILL.md 文件，包含：
工作机制遵循渐进式加载（Progressive Disclosure）：
这样做的好处是节省上下文窗口（context window），让 Agent 把有限的'记忆容量'用在刀刃上。
不同工具的 Skills 存放位置略有差异，但基本遵循相同的约定：
| 存放位置 | 作用范围 | 说明 |
|---|---|---|
.cursor/skills/ | 项目级别 | 跟随仓库，团队共享 |
.claude/skills/ | 项目级别 | Claude 兼容目录 |
.github/skills/ | 项目级别 | GitHub Copilot 目录 |
~/.cursor/skills/ | 用户级别 | 个人全局，所有项目可用 |
~/.claude/skills/ | 用户级别 | Claude 个人全局 |
一个典型的项目级 Skill 目录结构如下：
.cursor/
└── skills/
└── react-component-creator/
├── SKILL.md # 必需：核心指令文件
├── scripts/ # 可选：可执行脚本
│ └── generate.sh
├── references/ # 可选：参考文档（按需加载）
│ └── coding-standards.md
└── assets/ # 可选：模板、图片等静态资源
└── component-template.tsx
各文件夹定位：
| 目录 | 用途 | 加载时机 |
|---|---|---|
scripts/ | 可执行代码（Python/Bash/JS） | Agent 需要执行时调用 |
references/ | 参考文档、API 文档、规范等 | Agent 需要查阅时读取 |
assets/ | 模板文件、图片、配置等 | Agent 产出结果时使用 |
SKILL.md 由两部分组成：YAML 头信息 + Markdown 正文。
---
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.
---
两个必填字段：
| 字段 | 要求 | 作用 |
|---|---|---|
name | 最长 64 字符，仅限小写字母、数字、连字符 | Skill 唯一标识 |
description | 最长 1024 字符 | 最关键：Agent 根据它决定是否触发该 Skill |
description 是整个 Skill 的灵魂，写好需遵循原则：
正文是给 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>
}
[ComponentName].module.css[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/ 里的公共代码
🚫 绝对不要：
## 原则六：多步任务用编号清单'锁死'顺序
编号清单给了 Agent 两样东西：**明确的先后顺序**和**可追踪的进度**。特别适合发布流程、环境部署、大功能开发。
## 原则七：确定性操作封装成脚本
能用脚本跑的，就别让 Agent 手写。原因：省上下文空间、结果 100% 一致。
## 原则八：交付前设一道'质检门'
加一个 Pre-Delivery Checklist，效果立竿见影。
确认以下每一项都通过后，再告诉用户'已完成'：
npx tsc --noEmit 无报错npm run test 全部通过
## 原则九：用参数让 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>
)
}
useXxx.ts when logic exceeds 15 linessrc/components/src/utils/ or config filesFor 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 协作能力做一次基建升级。
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML 转 Markdown 互为补充。 在线工具，Markdown 转 HTML在线工具，online
将 HTML 片段转为 GitHub Flavored Markdown，支持标题、列表、链接、代码块与表格等；浏览器内处理，可链接预填。 在线工具，HTML 转 Markdown在线工具，online