Search K
Appearance
Skills 完整指南 - 第二部分：最佳实践与实战
什么是好的 Skills
写 Skills 和写代码一样，有好坏之分。
一个好的 Skills，能让 Agent 稳定、高效地完成任务； 一个坏的 Skills，可能比不用还糟糕。
那么，什么样的 Skills 才算好？
Good Skills vs Bad Skills
让我们通过对比来理解：
案例 1：代码审查 Skills
❌ Bad Skills
yaml
---
name: "代码审查"
description: "审查代码"
---
请帮我审查代码，找出问题。问题：
- Description 太模糊，Agent 不知道什么时候该用
- 没有具体流程，Agent 不知道怎么审查
- 没有标准，审查结果不稳定
- 没有示例，Agent 不知道输出什么格式
✅ Good Skills
yaml
---
name: "代码审查专家"
description: "对 JavaScript/TypeScript 代码进行全面审查，检查代码规范、安全漏洞、性能问题和最佳实践"
---
## 角色定义
你是一位资深的前端代码审查专家，拥有 10 年以上的 JavaScript/TypeScript 开发经验。
## 审查流程
### 1. 代码规范检查
- 命名规范（驼峰命名、常量大写等）
- 代码格式（缩进、空格、换行）
- 注释完整性
### 2. 安全漏洞扫描
- XSS 风险点
- SQL 注入可能性
- 敏感信息泄露
### 3. 性能问题分析
- 不必要的重复计算
- 内存泄漏风险
- 可优化的循环
### 4. 最佳实践检查
- 是否遵循 SOLID 原则
- 是否有适当的错误处理
- 是否有单元测试
## 输出格式
请按照以下格式输出审查结果：
\`\`\`markdown
# 代码审查报告
## 总体评分
- 代码规范：⭐⭐⭐⭐⭐ (5/5)
- 安全性：⭐⭐⭐⭐ (4/5)
- 性能：⭐⭐⭐ (3/5)
- 最佳实践：⭐⭐⭐⭐ (4/5)
## 发现的问题
### 🔴 严重问题（必须修复）
1. [文件名:行号] 问题描述
- 影响：xxx
- 建议：xxx
### 🟡 警告（建议修复）
1. [文件名:行号] 问题描述
- 建议：xxx
### 🟢 优化建议
1. [文件名:行号] 优化点
- 收益：xxx
\`\`\`
## 示例
**输入代码**：
\`\`\`javascript
function getData(id) {
return fetch('/api/user/' + id).then(res => res.json())
}
\`\`\`
**审查输出**：
\`\`\`markdown
# 代码审查报告
## 总体评分
- 代码规范：⭐⭐⭐ (3/5)
- 安全性：⭐⭐ (2/5)
- 性能：⭐⭐⭐⭐ (4/5)
- 最佳实践：⭐⭐ (2/5)
## 发现的问题
### 🔴 严重问题
1. [getData:2] 缺少错误处理
- 影响：网络请求失败时会导致未捕获的 Promise rejection
- 建议：添加 .catch() 或使用 try-catch
2. [getData:2] 潜在的 XSS 风险
- 影响：id 参数未经验证直接拼接到 URL
- 建议：使用参数化查询或对 id 进行验证
### 🟡 警告
1. [getData:1] 函数命名不够语义化
- 建议：改名为 `fetchUserById` 更清晰
### 🟢 优化建议
1. [getData:2] 使用模板字符串
- 收益：代码更现代化、可读性更好
- 建议：\`/api/user/${id}\`
\`\`\`
## 注意事项
- 不要过度吹毛求疵，关注真正重要的问题
- 提供具体的修改建议，而不是只指出问题
- 考虑项目的实际情况，不要教条主义改进点：
- ✅ Description 清晰具体
- ✅ 定义了专家角色
- ✅ 明确的审查流程
- ✅ 标准化的输出格式
- ✅ 提供了完整示例
- ✅ 包含注意事项
案例 2：前端开发 Skills
❌ Bad Skills
yaml
---
name: "前端"
description: "做前端"
---
帮我写前端代码，要好看。✅ Good Skills
yaml
---
name: "现代前端开发专家"
description: "使用 React + Tailwind CSS 创建现代化、响应式、高性能的前端页面"
---
## 角色定义
你是一位精通现代前端技术栈的资深开发者，擅长创建用户体验优秀的 Web 应用。
## 技术栈
- React 18+
- Tailwind CSS 3+
- TypeScript
- Vite
## 开发流程
### 1. 需求分析
- 明确页面功能
- 确定用户交互流程
- 识别关键组件
### 2. 组件设计
- 优先使用 shadcn/ui 组件
- 遵循原子设计原则
- 确保组件可复用
### 3. 样式实现
- 移动优先（Mobile First）
- 使用 Tailwind 工具类
- 遵循设计系统
### 4. 交互优化
- 添加适当的动画效果
- 确保可访问性（WCAG 2.1）
- 优化性能
## 设计原则
### 视觉层次
- 使用合理的字体大小（text-sm, text-base, text-lg）
- 保持一致的间距（4px 倍数）
- 适当的颜色对比度
### 交互反馈
- Hover 状态：`hover:bg-gray-100`
- Active 状态：`active:scale-95`
- Disabled 状态：`disabled:opacity-50`
### 响应式设计
- 断点：sm (640px), md (768px), lg (1024px), xl (1280px)
- 布局：flex, grid
- 隐藏/显示：`hidden md:block`
## 代码规范
### 组件结构
\`\`\`tsx
// 1. 导入
import { useState } from 'react'
import { Button } from '@/components/ui/button'
// 2. 类型定义
interface Props {
title: string
onSubmit: () => void
}
// 3. 组件
export function MyComponent({ title, onSubmit }: Props) {
// 3.1 状态
const [isLoading, setIsLoading] = useState(false)
// 3.2 事件处理
const handleClick = () => {
setIsLoading(true)
onSubmit()
}
// 3.3 渲染
return (
<div className="p-4">
<h1 className="text-2xl font-bold">{title}</h1>
<Button onClick={handleClick} disabled={isLoading}>
{isLoading ? '加载中...' : '提交'}
</Button>
</div>
)
}
\`\`\`
## 示例
**需求**：创建一个登录表单
**输出**：
\`\`\`tsx
import { useState } from 'react'
import { Button } from '@/components/ui/button'
import { Input } from '@/components/ui/input'
import { Label } from '@/components/ui/label'
export function LoginForm() {
const [email, setEmail] = useState('')
const [password, setPassword] = useState('')
const [isLoading, setIsLoading] = useState(false)
const handleSubmit = async (e: React.FormEvent) => {
e.preventDefault()
setIsLoading(true)
try {
// API 调用
await login({ email, password })
} catch (error) {
console.error('登录失败:', error)
} finally {
setIsLoading(false)
}
}
return (
<div className="flex min-h-screen items-center justify-center bg-gradient-to-br from-blue-50 to-indigo-100">
<form
onSubmit={handleSubmit}
className="w-full max-w-md space-y-6 rounded-2xl bg-white p-8 shadow-xl"
>
<div className="text-center">
<h1 className="text-3xl font-bold text-gray-900">欢迎回来</h1>
<p className="mt-2 text-sm text-gray-600">登录以继续</p>
</div>
<div className="space-y-4">
<div>
<Label htmlFor="email">邮箱</Label>
<Input
id="email"
type="email"
value={email}
onChange={(e) => setEmail(e.target.value)}
placeholder="your@email.com"
required
/>
</div>
<div>
<Label htmlFor="password">密码</Label>
<Input
id="password"
type="password"
value={password}
onChange={(e) => setPassword(e.target.value)}
placeholder="••••••••"
required
/>
</div>
</div>
<Button
type="submit"
className="w-full"
disabled={isLoading}
>
{isLoading ? '登录中...' : '登录'}
</Button>
</form>
</div>
)
}
\`\`\`
## 注意事项
- 不要使用内联样式，统一使用 Tailwind
- 确保所有交互元素都有适当的 aria 标签
- 图片必须有 alt 属性
- 表单必须有验证和错误提示好 Skills 的五大特征
通过上面的对比，我们可以总结出好 Skills 的五大特征：
1. 原子性（Atomicity）
定义：一个 Skills 只做一件事，但把这件事做到极致。
为什么重要：
- 职责清晰，易于理解
- 便于复用和组合
- 降低维护成本
反例：
yaml
name: "全栈开发"
description: "做前端、后端、数据库、部署等所有事情"正例：
yaml
name: "React 组件开发"
description: "创建可复用的 React 组件，遵循最佳实践"2. 给例子（Few-Shot Prompting）
定义：提供具体的输入输出示例，让 Agent 一看就懂。
为什么重要：
- 榜样的力量是无穷的
- 比千言万语的解释更有效
- 确保输出格式一致
示例数量建议：
- 简单任务：1-2 个示例
- 中等复杂度：2-3 个示例
- 复杂任务：3-5 个示例
示例质量要求：
- 覆盖典型场景
- 包含边界情况
- 展示期望的输出格式
3. 立规矩（Structured Instructions）
定义：通过结构化的指令，明确告诉 Agent 该做什么、不该做什么。
三个关键要素：
a) 定角色
markdown
## 角色定义
你是一位资深的 Python 后端开发专家，拥有 10 年以上的 Django/FastAPI 开发经验。
你熟悉 RESTful API 设计、数据库优化、安全最佳实践。b) 拆步骤
markdown
## 工作流程
1. 分析 API 需求，确定端点和参数
2. 设计数据模型和数据库结构
3. 实现业务逻辑，确保数据验证
4. 编写单元测试，覆盖率 > 80%
5. 添加 API 文档（OpenAPI/Swagger）c) 画红线
markdown
## 禁止事项
- ❌ 不要在代码中硬编码敏感信息（密码、API 密钥）
- ❌ 不要忽略错误处理
- ❌ 不要使用已废弃的 API
- ❌ 不要跳过输入验证4. 造接口（Interface Design）
定义：像设计软件 API 一样，明确定义 Skills 的输入和输出。
输入定义：
markdown
## 输入参数
- `task_description`: string - 任务描述
- `target_framework`: "react" | "vue" | "angular" - 目标框架
- `style_preference`: "minimal" | "modern" | "glassmorphism" - 样式偏好输出定义：
markdown
## 输出格式
返回 JSON 对象：
\`\`\`json
{
"code": "组件代码",
"styles": "样式代码",
"dependencies": ["依赖列表"],
"usage": "使用说明"
}
\`\`\`好处：
- 可以被其他程序稳定调用
- 便于集成到工作流
- 输出格式可预测
5. 勤复盘（Iterative Refinement）
定义：把 Skills 当作产品来迭代，持续优化。
迭代流程：
Bad Case 收集：
- 记录每次执行不符合预期的情况
- 分析是哪个环节出了问题
- 是 description 不够清晰？
- 是流程有遗漏？
- 是示例不够典型？
优化策略：
- 补充边界情况的处理
- 增加反例说明
- 优化 description 的措辞
- 添加更多示例
版本管理：
markdown
## 更新日志
### v1.2.0 (2024-01-20)
- 增加了错误处理的示例
- 优化了 description，提高匹配准确率
- 添加了性能优化的检查项
### v1.1.0 (2024-01-15)
- 补充了 TypeScript 支持
- 增加了单元测试的要求
### v1.0.0 (2024-01-10)
- 初始版本如何写好 Skills：实战指南
理论说完了，让我们动手实践。
我会带你一步步创建一个真实可用的 Skills。
实战案例：创建一个"Git Commit 规范" Skills
需求背景： 团队使用 Conventional Commits 规范，但新人经常写出不规范的 commit message。我们需要一个 Skills 来帮助生成规范的 commit。
步骤 1：明确职责（原子性）
问自己：
这个 Skills 要解决什么问题？ → 生成符合 Conventional Commits 规范的 commit message
它的边界在哪里？ → 只负责生成 commit message，不负责执行 git commit
它和其他 Skills 的关系？ → 可以被"代码提交" Skills 调用
步骤 2：编写元数据
yaml
---
name: "Git Commit 规范专家"
description: "根据代码变更生成符合 Conventional Commits 规范的 commit message，支持 feat/fix/docs/style/refactor/test/chore 等类型"
---注意：
- name 要语义化，一看就知道是干什么的
- description 要包含关键词（Conventional Commits、feat/fix 等），方便匹配
步骤 3：定义角色和流程
markdown
## 角色定义
你是一位经验丰富的 Git 工作流专家，深谙 Conventional Commits 规范，能够根据代码变更准确判断 commit 类型和范围。
## Conventional Commits 规范
### 格式
\`\`\`
<type>(<scope>): <subject>
<body>
<footer>
\`\`\`
### Type 类型
- `feat`: 新功能
- `fix`: Bug 修复
- `docs`: 文档变更
- `style`: 代码格式（不影响代码运行）
- `refactor`: 重构（既不是新功能也不是 Bug 修复）
- `perf`: 性能优化
- `test`: 测试相关
- `chore`: 构建过程或辅助工具的变动
### Scope 范围（可选）
- 模块名、文件名或功能名
- 例如：`auth`, `user`, `api`, `ui`
### Subject 主题
- 简短描述（50 字符以内）
- 使用祈使句，现在时
- 首字母小写
- 结尾不加句号
### Body 正文（可选）
- 详细描述变更的动机和实现细节
- 每行不超过 72 字符
### Footer 页脚（可选）
- Breaking Changes: `BREAKING CHANGE: 描述`
- 关闭 Issue: `Closes #123`
## 工作流程
1. 分析代码变更内容
2. 判断 commit 类型（feat/fix/docs 等）
3. 确定影响范围（scope）
4. 编写简洁的主题（subject）
5. 如有必要，添加详细说明（body）
6. 如有必要，添加页脚信息（footer）步骤 4：提供示例（Few-Shot）
markdown
## 示例
### 示例 1：新功能
**代码变更**：添加了用户登录功能
**输出**：
\`\`\`
feat(auth): add user login functionality
Implement JWT-based authentication with email and password.
Includes login form validation and error handling.
Closes #45
\`\`\`
### 示例 2：Bug 修复
**代码变更**：修复了分页组件的显示问题
**输出**：
\`\`\`
fix(ui): correct pagination display on mobile devices
The pagination buttons were overlapping on small screens.
Fixed by adjusting the responsive breakpoints.
\`\`\`
### 示例 3：文档更新
**代码变更**：更新了 README 文件
**输出**：
\`\`\`
docs: update installation instructions in README
Add steps for setting up environment variables.
\`\`\`
### 示例 4：重构
**代码变更**：重构了数据获取逻辑
**输出**：
\`\`\`
refactor(api): simplify data fetching logic
Replace multiple API calls with a single batch request.
Improves performance and reduces code complexity.
\`\`\`
### 示例 5：Breaking Change
**代码变更**：修改了 API 响应格式
**输出**：
\`\`\`
feat(api): change response format to include metadata
BREAKING CHANGE: API responses now include a `meta` field.
Clients need to update their response parsing logic.
Before:
{ "data": [...] }
After:
{ "data": [...], "meta": { "total": 100, "page": 1 } }
\`\`\`步骤 5：添加注意事项
markdown
## 注意事项
### ✅ 应该做的
- 使用现在时、祈使句（"add" 而不是 "added" 或 "adds"）
- 主题简洁明了，50 字符以内
- 如果变更复杂，添加 body 详细说明
- Breaking Changes 必须在 footer 中明确标注
### ❌ 不应该做的
- 不要使用模糊的描述（如 "update code", "fix bug"）
- 不要在主题中使用句号
- 不要在一个 commit 中混合多种类型的变更
- 不要忽略 Breaking Changes 的标注
## 判断技巧
### 如何区分 feat 和 fix？
- feat: 用户可以感知到的新功能
- fix: 修复了用户可以感知到的问题
### 如何区分 refactor 和 perf？
- refactor: 重构代码结构，功能和性能不变
- perf: 专门为了提升性能而做的优化
### 什么时候需要 Breaking Change？
- 修改了公共 API 的签名
- 删除了已有功能
- 改变了默认行为
- 需要用户修改配置或代码才能升级步骤 6：测试和迭代
测试用例：
| 场景 | 输入 | 期望输出 |
|---|---|---|
| 添加新页面 | 创建了用户个人资料页面 | feat(user): add profile page |
| 修复样式问题 | 修复了按钮的对齐问题 | fix(ui): correct button alignment |
| 更新依赖 | 升级了 React 版本 | chore(deps): upgrade React to v18 |
| 性能优化 | 优化了图片加载速度 | perf(image): optimize loading performance |
实际测试：
- 用这个 Skills 生成 10 个不同场景的 commit
- 检查是否符合规范
- 收集不符合预期的情况
- 分析原因并优化 Skills
常见问题和优化：
| 问题 | 原因 | 优化方案 |
|---|---|---|
| type 判断不准确 | 示例不够典型 | 增加边界情况的示例 |
| scope 太宽泛 | 没有明确 scope 的粒度 | 补充 scope 的选择标准 |
| subject 太长 | 没有强调字符限制 | 在注意事项中加粗提醒 |