1. 引言：为什么需要 AI Skill？

在日常开发中，我们常常重复执行相似的工作流：代码审查、单元测试编写、API 文档生成、代码重构、技术方案评审……这些工作虽然重要，但每次手动执行既耗时又容易遗漏细节。

AI Skill 是一种将特定工作流封装成可复用的 AI 指令模板的方法。通过定义清晰的输入输出、约束条件和执行步骤，你可以让 AI 助手像执行函数一样执行你的工作流，从而大幅提升开发效率。

本文将带你从零开始，构建一套完整的 AI Skill 体系，覆盖代码规范检查、自动化测试、文档生成、代码审查、技术方案设计等核心场景。

2. AI Skill 基础架构

2.1 核心组成

一个完整的 AI Skill 包含以下要素：

• Skill 名称：唯一标识，如code-review-skill
• 输入参数：定义需要用户提供的信息，如代码片段、项目上下文、技术栈等
• 执行指令：具体的 AI 提示词模板，包含角色设定、任务描述、约束条件
• 输出格式：定义返回结果的格式，如 Markdown 报告、JSON 结构、代码 diff
• 质量门禁：内置的检查规则，确保输出符合预期

2.2 通用模板结构

# Skill: [名称] # 版本: 1.0 # 适用场景: [描述] ## 输入参数 - `{code}`：待处理的代码片段 - `{language}`：编程语言 - `{context}`：项目上下文（可选） ## 角色设定 你是一位资深的 [角色] 工程师，专注于 [领域]。 ## 任务描述 请根据以下要求执行 [具体任务]： ## 约束条件 1. 遵循 [规范名称] 编码规范 2. 输出格式为 [格式要求] 3. 必须包含 [必要元素] ## 输出模板 ```markdown # [报告标题] ## 检查结果 - 通过项：... - 警告项：... - 错误项：... ## 详细说明 ...

## 3. 实战 Skill 一：代码规范检查 ### 3.1 Skill 定义 ```markdown # Skill: code-style-check # 版本: 1.0 # 适用场景: 检查代码是否符合团队编码规范 ## 输入参数 - `{code}`：待检查的代码 - `{language}`：编程语言（Java/Python/Go/JavaScript 等） - `{style_guide}`：规范文档链接或关键规则（可选） ## 角色设定 你是一位严格的代码规范审查员，精通主流编程语言的编码规范。 ## 任务描述 请对以下代码进行全面的规范检查，包括但不限于： 1. 命名规范（类名、方法名、变量名、常量名） 2. 代码格式（缩进、空格、换行、括号位置） 3. 注释规范（必要注释、注释格式、TODO 标记） 4. 代码结构（方法长度、类职责、模块划分） 5. 异常处理（异常类型、日志记录、资源释放） 6. 安全规范（SQL 注入、XSS、敏感信息泄露） ## 约束条件 1. 按严重程度分级：Error > Warning > Info 2. 每个问题必须给出具体行号和修改建议 3. 优先检查安全相关和逻辑错误 4. 格式问题合并归类，避免逐行重复 ## 输出模板 ```markdown # 代码规范检查报告 ## 概览 - 检查文件：`{filename}` - 语言：{language} - 总问题数：{count} - Error：{error_count} | Warning：{warning_count} | Info：{info_count} ## 问题详情 ### Error（必须修复） | 行号 | 类型 | 描述 | 建议 | |------|------|------|------| | 42 | 安全 | SQL 拼接存在注入风险 | 使用参数化查询 | | 78 | 异常 | 捕获 Exception 过于宽泛 | 捕获具体异常类型 | ### Warning（建议修复） ... ### Info（仅供参考） ... ## 合规评分 - 总体评分：{score}/100 - 通过标准：≥80 分

### 3.2 使用示例 假设你有一段 Java 代码需要检查： ```java public class userService { public List getUsers(String name) { String sql = "SELECT * FROM users WHERE name = '" + name + "'"; return jdbcTemplate.query(sql, new UserRowMapper()); } }

调用 Skill 后，AI 会输出：

# 代码规范检查报告 ## 概览 - 检查文件：UserService.java - 语言：Java - 总问题数：3 - Error：1 | Warning：1 | Info：1 ## 问题详情 ### Error（必须修复） | 行号 | 类型 | 描述 | 建议 | |------|------|------|------| | 3 | 安全 | SQL 拼接存在注入风险 | 使用 `?` 占位符 + 参数绑定 | ### Warning（建议修复） | 行号 | 类型 | 描述 | 建议 | |------|------|------|------| | 1 | 命名 | 类名 `userService` 应为大驼峰 | 改为 `UserService` | ### Info（仅供参考） | 行号 | 类型 | 描述 | 建议 | |------|------|------|------| | 2 | 泛型 | `List` 缺少泛型参数 | 改为 `List<User>` |

4. 实战 Skill 二：自动化单元测试生成

4.1 Skill 定义

# Skill: unit-test-generator # 版本: 1.0 # 适用场景: 为指定方法/类自动生成单元测试 ## 输入参数 - `{code}`：待测试的源代码 - `{framework}`：测试框架（JUnit 5 / pytest / Jest 等） - `{coverage_target}`：覆盖率目标（如 90%） - `{mock_strategy}`：Mock 策略（Mockito / unittest.mock 等） ## 角色设定 你是一位测试驱动开发（TDD）专家，擅长编写高质量的单元测试。 ## 任务描述 请为以下代码生成完整的单元测试，要求： 1. 覆盖所有公开方法 2. 覆盖正常路径、边界条件、异常路径 3. 使用参数化测试减少重复代码 4. 合理使用 Mock 隔离外部依赖 5. 测试方法命名遵循 `methodName_scenario_expectedResult` 模式 ## 约束条件 1. 每个测试方法只测试一个行为 2. 测试数据使用常量或工厂方法，避免硬编码 3. 包含 Arrange-Act-Assert 三段式结构 4. 覆盖率不低于 {coverage_target} 5. 测试代码本身也要符合编码规范 ## 输出模板 ```markdown # 单元测试报告 ## 测试概览 - 被测类：`{className}` - 测试类：`{className}Test` - 测试框架：{framework} - 测试方法数：{count} - 预估覆盖率：{coverage}% ## 测试代码 ```java import org.junit.jupiter.api.*; import org.mockito.*; import static org.junit.jupiter.api.Assertions.*; import static org.mockito.Mockito.*; @DisplayName("{className} 单元测试") class {className}Test { @Mock private Dependency mockDependency; @InjectMocks private {className} target; @BeforeEach void setUp() { MockitoAnnotations.openMocks(this); } // ========== 方法一：methodName ========== @Test @DisplayName("正常路径：输入有效参数应返回正确结果") void methodName_validInput_returnsCorrectResult() { // Arrange var input = TestDataFactory.createValidInput(); when(mockDependency.call()).thenReturn(expectedValue); // Act var result = target.methodName(input); // Assert assertNotNull(result); assertEquals(expectedValue, result.getValue()); verify(mockDependency).call(); } @Test @DisplayName("边界条件：输入为空应抛出 IllegalArgumentException") void methodName_nullInput_throwsIllegalArgumentException() { assertThrows(IllegalArgumentException.class, () -> target.methodName(null)); } @ParameterizedTest @ValueSource(strings = {"", " ", "\t"}) @DisplayName("边界条件：空白字符串应抛出异常") void methodName_blankInput_throwsException(String input) { assertThrows(IllegalArgumentException.class, () -> target.methodName(input)); } }

测试要点说明

• 使用@ParameterizedTest减少重复测试代码
• 通过 Mock 隔离数据库/外部 API 依赖
• 异常路径覆盖了 null 和空白输入

4.2 进阶：集成覆盖率工具

将 AI Skill 与 JaCoCo / pytest-cov 等工具结合，形成闭环：

## 执行流程 1. AI 生成测试代码 2. 开发者 review 并合并 3. 运行 `mvn test` + JaCoCo 报告 4. 将覆盖率报告反馈给 AI，补充缺失的测试用例 5. 迭代直到达到覆盖率目标

5. 实战 Skill 三：API 文档自动生成

5.1 Skill 定义

# Skill: api-doc-generator # 版本: 1.0 # 适用场景: 从代码注释或接口定义生成 API 文档 ## 输入参数 - `{code}`：接口定义代码（Controller / Router 等） - `{format}`：输出格式（OpenAPI 3.0 / Markdown / HTML） - `{include_examples}`：是否包含请求/响应示例（true/false） ## 角色设定 你是一位 API 文档工程师，精通 RESTful API 设计规范和 OpenAPI 标准。 ## 任务描述 请根据以下接口代码生成完整的 API 文档，要求： 1. 提取所有端点及其 HTTP 方法 2. 解析请求参数（Path / Query / Header / Body） 3. 解析响应状态码和响应体结构 4. 生成清晰的接口描述和字段说明 5. 包含请求/响应示例（如果 {include_examples} 为 true） ## 约束条件 1. 遵循 OpenAPI 3.0 规范（如果格式为 OpenAPI） 2. 每个字段标注类型、是否必填、取值范围 3. 错误响应也要文档化 4. 接口描述使用业务语言，而非技术实现细节 ## 输出模板（Markdown 格式） ```markdown # {API名称} API 文档 ## 概览 - 基础路径：`/api/v1/{resource}` - 版本：v1 - 认证方式：Bearer Token ## 端点列表 ### GET /api/v1/users 获取用户列表 **请求参数** | 参数名 | 位置 | 类型 | 必填 | 说明 | |--------|------|------|------|------| | page | Query | Integer | 否 | 页码，默认 1 | | size | Query | Integer | 否 | 每页条数，默认 20 | | keyword | Query | String | 否 | 搜索关键词 | **响应** - 200 OK ```json { "code": 0, "data": { "total": 100, "items": [ { "id": 1, "name": "张三", "email": "zhangsan@example.com" } ] }, "message": "success" }

• 401 Unauthorized：Token 无效或过期
• 403 Forbidden：无权限访问

6. 实战 Skill 四：代码审查（Code Review）

6.1 Skill 定义

# Skill: code-review # 版本: 1.0 # 适用场景: Pull Request 代码审查 ## 输入参数 - `{diff}`：代码变更 diff - `{context}`：PR 描述和背景信息 - `{focus_areas}`：重点关注领域（性能/安全/可维护性等） ## 角色设定 你是一位经验丰富的代码审查员，负责确保代码质量、安全性和可维护性。 ## 任务描述 请对以下代码变更进行全面审查，重点关注： 1. 逻辑正确性：是否存在潜在的 bug 或逻辑错误 2. 安全性：是否存在安全漏洞（注入、XSS、认证绕过等） 3. 性能：是否存在性能瓶颈或不必要的资源消耗 4. 可维护性：代码是否清晰、模块化、易于扩展 5. 测试覆盖：变更是否包含充分的测试 6. 兼容性：是否破坏现有功能或 API 契约 ## 约束条件 1. 每个问题标注严重程度：BLOCKER > CRITICAL > MAJOR > MINOR 2. BLOCKER/CRITICAL 问题必须给出具体修复建议 3. 正面评价也要给出，鼓励好的实践 4. 评论语气保持专业和建设性 ## 输出模板 ```markdown # Code Review 报告 ## 概览 - PR 标题：{title} - 变更文件数：{files} - 新增行数：{additions} - 删除行数：{deletions} ## 审查结果 ### 🚫 Blocker（必须修复） ... ### 🔴 Critical（强烈建议修复） ... ### 🟡 Major（建议修复） ... ### 🟢 Minor（仅供参考） ... ### ✅ 亮点 - 使用了参数化查询，防止 SQL 注入 - 添加了完整的单元测试覆盖 ## 总结 总体质量：{rating}/5 建议：{summary}

## 7. 实战 Skill 五：技术方案设计 ### 7.1 Skill 定义 ```markdown # Skill: tech-design-doc # 版本: 1.0 # 适用场景: 生成技术方案设计文档 ## 输入参数 - `{requirement}`：业务需求描述 - `{tech_stack}`：技术栈约束 - `{constraints}`：非功能性约束（性能/可用性/成本等） - `{existing_system}`：现有系统架构（可选） ## 角色设定 你是一位资深系统架构师，擅长设计高可用、可扩展的技术方案。 ## 任务描述 请根据以下需求生成技术方案设计文档，包含： 1. 背景与目标 2. 技术选型及理由 3. 系统架构设计（含架构图描述） 4. 核心模块设计 5. 数据模型设计 6. 接口设计 7. 非功能性设计（性能/安全/可扩展性） 8. 部署方案 9. 风险与应对措施 ## 约束条件 1. 技术选型必须给出对比分析 2. 架构设计要说明权衡（trade-off） 3. 包含备选方案 4. 数据模型要说明索引策略 5. 接口设计要说明限流和降级策略 ## 输出模板 ```markdown # {项目名称} 技术方案设计 ## 1. 背景与目标 ... ## 2. 技术选型 | 组件 | 选型 | 备选 | 选择理由 | |------|------|------|----------| | 数据库 | PostgreSQL | MySQL | 支持 JSONB、CTE、扩展性好 | | 缓存 | Redis | Memcached | 支持丰富数据结构、持久化 | | 消息队列 | Kafka | RabbitMQ | 高吞吐、持久化、流处理 | ## 3. 系统架构 ```mermaid flowchart TD A["客户端"] --> B["API Gateway"] B --> C["用户服务"] B --> D["订单服务"] B --> E["支付服务"] C --> F["PostgreSQL"] D --> F E --> G["Redis"] D --> H["Kafka"]

4. 核心模块设计

…

8. 构建你的 AI Skill 工作流

8.1 工作流编排

将多个 Skill 串联成完整的工作流：

8.2 集成到 CI/CD

将 AI Skill 集成到 GitHub Actions / GitLab CI：

# .github/workflows/ai-code-quality.ymlname:AI Code Quality Checkon:[pull_request]jobs:ai-review:runs-on:ubuntu-lateststeps:-uses:actions/checkout@v4-name:Run AI Code Style Checkrun:|# 调用 AI Skill API curl -X POST https://api.example.com/skills/code-style-check \ -H "Authorization: Bearer ${{ secrets.AI_TOKEN }}" \ -d @- << EOF { "code": "$(cat ${{ github.event.pull_request.diff }})", "language": "java" } EOF-name:Post Review Commentuses:actions/github-script@v7with:script:|// 将 AI 审查结果作为 PR 评论发布

8.3 持续优化

建立 Skill 的迭代机制：

1. 收集反馈：记录每次 Skill 执行的结果和开发者满意度
2. 分析失败模式：哪些场景下 Skill 输出质量不高
3. 优化提示词：补充边界案例、调整约束条件
4. 版本管理：为 Skill 打版本标签，支持回滚
5. 共享复用：在团队内建立 Skill 市场，鼓励贡献

9. 最佳实践与注意事项

9.1 提示词设计原则

• 具体明确：避免模糊描述，给出可量化的标准
• 分步引导：复杂任务拆解为多个子步骤
• 示例驱动：提供输入输出示例，减少歧义
• 约束前置：把最重要的约束放在最前面
• 格式固定：使用模板确保输出一致性

9.2 常见陷阱

9.3 安全注意事项

• 不要在 Skill 提示词中包含敏感信息（密钥、密码）
• 对 AI 生成的代码进行安全审查后再合并
• 限制 AI 对生产环境的直接操作权限
• 记录所有 AI 操作日志，便于审计

10. 总结与展望

通过本文，你已经学会了如何用 AI Skill 封装开发中的常见工作流：

• 代码规范检查：自动化代码质量门禁
• 单元测试生成：提升测试覆盖率和编写效率
• API 文档生成：保持文档与代码同步
• 代码审查：辅助人工审查，发现潜在问题
• 技术方案设计：加速架构设计过程

未来，随着 AI 能力的提升，AI Skill 将变得更加智能和自主。你可以期待：

• 自适应 Skill：根据历史反馈自动优化提示词
• 多模态 Skill：结合代码、图表、日志等多种输入
• 协作式 Skill：多个 AI Skill 协同完成复杂任务
• 领域专用 Skill：针对特定业务场景深度定制

现在就开始构建你的第一个 AI Skill 吧！从最简单的代码规范检查开始，逐步扩展到全流程，让 AI 成为你最高效的开发伙伴。