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

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

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

核心定义

Skill = 智能 + 行动 + 上下文

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

典型案例

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

技术本质

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

这种设计极大节省了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. 功能测试：验证输出是否正确

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

Step 6：部署与迭代

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

四、Skills与MCP的黄金搭档

核心区别：

实战组合：

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

例如：

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

五、可能会遇到的问题