如何编写一个高质量的AI Skill

在AI Agent与智能体技术快速普及的今天，**Skill（技能）**正成为连接业务需求与AI能力的核心单元。不同于传统API或微服务，一个Skill不仅封装了执行逻辑，还融合了语义理解、工具调用、上下文推理与结果生成等智能行为。

一、什么是Skill？为什么需要它？

核心定义

Skill = 智能 + 行动 + 上下文

• 智能：能理解自然语言指令（如"帮我review一下这个React组件的代码"）
• 行动：能调用外部工具（linter、代码分析工具、测试框架等）完成任务
• 上下文：能结合项目规范、团队编码标准、历史Review意见做出合理判断

典型案例

"Review前端代码"不是一个简单的语法检查，而是一个Skill------它需识别代码类型、应用团队规范、检查安全性（XSS、CSRF）、验证可访问性、评估性能影响，并给出可执行的建议。

技术本质

从技术架构看，Skill采用**渐进式披露（Progressive Disclosure）**设计：

层级	位置	作用	加载时机
第一层	YAML Frontmatter	元数据（名称、触发条件）	总是加载
第二层	SKILL.md正文	具体步骤、检查清单、示例	需要时动态加载
第三层	关联文件	references/、assets/等	仅在需要时查看

这种设计极大节省了Token消耗，提升了效率和稳定性。

二、编写高质量Skill的六大原则

原则1：单一职责，拒绝"大而全"

❌ 错误做法 ：创建名为code-helper的巨大Skill，试图包含前后端Review、文档生成、Bug修复等所有功能。

✅ 最佳实践 ：采用Micro-skills（微技能）。将大任务拆解为小而专的Skills：

• frontend-code-reviewer：前端代码审查器（React/Vue/HTML/CSS）
• accessibility-auditor：可访问性审计
• performance-optimizer：性能优化建议

理由：Claude的上下文窗口虽大但非无限。加载无关Skills的上下文会通过"噪声"降低模型智商。专才比全才更可靠。

原则2：命名即路由

Claude根据Skills的name和description决定是否调用它。拒绝模糊命名：

❌ Bad：

name: code-review
description: Helps with code.

✅ Good：

name: frontend-code-reviewer
description: |
  审查React/Vue组件代码，检查代码质量、安全性、性能和可访问性。
  当用户要求review前端代码、审查组件、检查React/Vue代码时使用。

关键点：描述中必须包含：

• What：它做什么（功能）
• When：在何时使用（触发短语）

原则3：步骤明确可执行

Skill的核心是"步骤"，每一步都必须是可执行的指令。避免"可能"、"大概"等模糊词。

技巧：采用结构化指令，利用大模型的注意力机制：

## Review Categories
### 1. Code Quality (代码质量)
- **必须**检查组件职责单一性
- **必须**验证Props类型定义完整

### 2. Security (安全性)
- **必须**检查XSS风险（用户输入未转义）
- **必须**检查敏感信息泄漏（API Key硬编码）

## Workflow
1. Analysis Phase: 静默分析代码
2. Security Check: 执行安全检查清单
3. Output: 生成结构化报告

原则4：自我纠错能力

在Skills的指令中，明确要求Claude验证自己的输出。

实战技巧：要求Claude在输出最终结果前，先验证修改建议是否真正解决问题：

"Before outputting the final review report, verify each suggestion addresses a concrete issue and provides actionable guidance."

原则5：失败策略完备

明确告诉模型遇到问题该如何处理：

## Error Handling
当遇到以下情况时：
- 代码片段不完整：请求用户提供更多上下文
- 无法识别框架：询问是React还是Vue
- 缺少项目规范：使用通用最佳实践作为标准

原则6：可复用与可组合

一个Skill创建后，可在不同对话中反复调用。多个Skill还可组合构建更复杂的工作流。例如：

• frontend-code-reviewer + accessibility-auditor → 完整的前端质量检查
• frontend-code-reviewer + performance-optimizer → 代码Review + 性能优化

三、从0到1创建Skill的完整流程

Step 1：定义Skill目标与边界

以"前端代码自动审查"为例：

• 名称 ：frontend-code-reviewer
• 触发条件：用户表达"review前端代码""审查组件""检查React/Vue代码"等意图
• 输入：代码片段、技术栈标识（React/Vue）、项目规范（可选）
• 输出：结构化Review报告，包含问题清单、严重程度、修复建议
• 依赖工具：ESLint配置、Prettier配置、浏览器兼容性数据库

Step 2：设计元数据

---
name: frontend-code-reviewer
description: |
  审查React/Vue组件代码，检查代码质量、安全性（XSS/CSRF）、性能和可访问性。
  当用户要求review前端代码、审查组件、检查React/Vue代码时使用。
version: 1.0.0
author: FrontendTeam
---

Step 3：实现Skill逻辑

在SKILL.md中编写详细指令：

# Frontend Code Reviewer Skill

## Input Format
- code: 待审查的代码片段
- framework: 框架类型（react/vue，默认react）
- specs: 项目规范文件（可选，默认使用通用最佳实践）

## Review Categories

### 1. Code Quality (代码质量)
- **必须**检查组件职责单一性，避免巨型组件
- **必须**验证Props类型定义完整（TypeScript接口或PropTypes）
- **必须**检查变量命名语义化
- **必须**验证逻辑复用（useHooks提取公共逻辑）
- **建议**检查代码可读性和注释完整性

### 2. Security (安全性)
- **必须**检查XSS风险：
  - 用户输入直接插入DOM（dangerouslySetInnerHTML、innerHTML）
  - 未转义的用户内容渲染
- **必须**检查CSRF风险：
  - 表单提交是否携带token
  - API调用是否有认证机制
- **必须**检查敏感信息泄漏：
  - API Key、Secret硬编码
  - 调试console.log未清理

### 3. Performance (性能)
- **必须**检查不必要的重新渲染：
  - 缺少React.memo、useMemo、useCallback
  - 组件挂载时重复执行昂贵操作
- **必须**检查资源加载：
  - 大图片未压缩
  - 未使用懒加载（lazy loading）
- **建议**检查Bundle大小影响（避免引入巨型库）

### 4. Accessibility (可访问性)
- **必须**检查语义化HTML使用
- **必须**检查键盘导航支持
- **必须**检查ARIA标签完整性
- **建议**检查颜色对比度

### 5. Best Practices (最佳实践)
- **必须**检查错误边界（Error Boundary）
- **必须**检查状态管理规范（避免props drilling）
- **建议**检查CSS-in-JS或CSS Modules使用
- **建议**检查响应式设计

## Workflow

请严格按照以下步骤执行：

1. **Framework Detection**
   - 自动识别代码框架（React/Vue）
   - 如果无法识别，询问用户

2. **Static Analysis**
   - 静默阅读代码，在思维链中标记所有不符合Review Categories的问题
   - 记录每个问题的行号和上下文

3. **Self-Correction**
   - 再次检查是否遗漏安全问题（特别是XSS和敏感信息泄漏）
   - 确认每个建议都是可执行的

4. **Output Generation**
   - 按照Output Format生成结构化报告
   - 确保每个问题都有明确的修复建议

## Output Format

使用以下Markdown表格格式输出：

| 类别 | 严重程度 | 行号 | 问题描述 | 修复建议 |
|------|----------|------|----------|----------|
| Security | 🔴 高 | 23 | 使用dangerouslySetInnerHTML渲染用户输入，存在XSS风险 | 使用DOMPurify库清理内容，或避免直接渲染HTML |
| Performance | 🟡 中 | 45 | 在每次渲染时执行昂贵计算 | 使用useMemo缓存计算结果 |
| Code Quality | 🟢 低 | 12 | 变量命名不清晰 | 重命名为`userProfile` |

## Error Handling
- 代码片段不完整：请求用户提供更多上下文
- 无法识别框架：询问"这是React还是Vue组件？"
- 缺少项目规范：使用通用最佳实践作为标准

Step 4：创建可复用资源

将反复使用的检查清单、模板、规范封装：

# 前端安全检查清单

## XSS防护
- [ ] 避免使用innerHTML、dangerouslySetInnerHTML
- [ ] 用户输入必须转义或使用DOMPurify清理
- [ ] URL参数渲染时验证合法性

## CSRF防护
- [ ] 表单提交携带CSRF token
- [ ] 重要API调用使用认证机制
- [ ] SameSite Cookie属性正确设置

## 敏感信息
- [ ] 无API Key硬编码
- [ ] 无密码、token明文传输
- [ ] 调试console.log已清理

import React, { useState, useCallback, useMemo } from 'react';
import { UserProfile } from '@/types';

interface Props {
  userId: string;
  onUpdate: (user: UserProfile) => void;
}

/**
 * 用户信息卡片组件
 * 职责单一：展示和编辑用户信息
 */
export const UserProfileCard: React.FC<Props> = React.memo(({ userId, onUpdate }) => {
  const [user, setUser] = useState<UserProfile | null>(null);

  // 使用useCallback缓存函数
  const handleSave = useCallback(() => {
    if (user) onUpdate(user);
  }, [user, onUpdate]);

  // 使用useMemo缓存计算结果
  const displayName = useMemo(() => {
    return user ? `${user.firstName} ${user.lastName}` : '';
  }, [user]);

  return (
    <div className="user-card">
      <h2>{displayName}</h2>
      {/* 表单组件 */}
    </div>
  );
});

# 可访问性指南

## 语义化HTML
- 使用<header>、<nav>、<main>、<footer>
- 按钮使用<button>而非<div>
- 表单关联<label>

## 键盘导航
- 所有交互元素支持Tab键
- 提供焦点可见性（focus-visible）
- 陷阱焦点（modal场景）

## ARIA标签
- 必要时添加aria-label
- 动态内容使用aria-live
- 图标按钮添加aria-label

Step 5：测试与验证

必做三类测试：

1. 触发测试：确保Skill在需要时加载，不需要时不加载

   • 测试"明显请求"："帮我review这个React组件"
   • 测试"变形请求"："检查一下这段前端代码"
   • 测试"无关请求"："今天天气如何"（不应触发）

2. 功能测试：验证输出是否正确

测试用例	预期行为
XSS风险代码（dangerouslySetInnerHTML）	🔴高严重度，建议使用DOMPurify
缺少类型定义	🟡中严重度，建议添加TypeScript接口
巨型组件（>300行）	🟡中严重度，建议拆分组件
缺少错误边界	🟡中严重度，建议添加ErrorBoundary
无键盘导航支持	🟢低严重度，建议添加Tab支持

3. 对比测试：证明Skill的优势

指标	无Skill	使用Skill	提升
Token消耗（单次Review）	1500	800	-47%
对话轮数	5-8轮	1-2轮	-70%
安全问题检出率	65%	92%	+42%
输出一致性	低	高	显著提升

Step 6：部署与迭代

• 部署：将Skill上传到团队技能库，集成到Code Review流程
• 监控：记录Review次数、问题检出率、开发者采纳率
• 迭代 ：基于团队反馈持续优化
  • 新增Vue框架支持
  • 添加团队特定规范
  • 优化输出格式以适配Jira/GitHub

四、Skills与MCP的黄金搭档

核心区别：

维度	MCP（Model Context Protocol）	Skill
本质	手和眼	大脑中的流程图
作用	连接外部世界，执行操作	定义业务流程和执行逻辑
示例	linter-mcp-server（能执行ESLint）	frontend-code-reviewer（SOP：安全检查→性能分析→可访问性审计）

实战组合：

Powerful Frontend Agent = MCP Tools (能力) + Skill (SOP)

例如：

• linter-mcp-server（能力：能执行ESLint检查）
• security-scanner-mcp（能力：能扫描XSS漏洞）
• frontend-code-reviewer（SOP：第一步代码质量检查→第二步安全扫描→第三步性能分析→第四步生成报告）

五、可能会遇到的问题

问题	后果	解决方案
Skill职责过重	上下文膨胀，执行不稳定	拆分为frontend-reviewer、accessibility-auditor等子Skill
忽略安全检查	漏检XSS/CSRF漏洞	将安全检查设为"必须"项，优先级最高
缺少框架识别	React和Vue规范混用	增加Framework Detection步骤
输出格式不统一	难以自动化处理	固定Markdown表格格式，便于解析
无团队规范适配	建议不符合团队实际	支持传入specs参数，加载团队规范