Skill—— AI 能力封装与复用

Skill 是对 AI 能力的封装，使特定任务能够被复用，是构建可维护 AI 系统的关键。

---

6.1 什么是 Skill？

Skill 是对特定 AI 能力的标准化封装，让复杂任务能够以简单的命令方式调用：

┌─────────────────────────────────────────────────────────┐
│                    Skill 架构                            │
├─────────────────────────────────────────────────────────┤
│                                                         │
│   用户指令 ──▶ Skill 解析 ──▶ 能力执行 ──▶ 结果返回    │
│                    │                                    │
│                    ▼                                    │
│              ┌──────────┐                              │
│              │  Skills  │                              │
│              ├──────────┤                              │
│              │ /commit  │ 提交代码                      │
│              │ /review  │ 代码审查                      │
│              │ /test    │ 运行测试                      │
│              │ /deploy  │ 部署应用                      │
│              └──────────┘                              │
└─────────────────────────────────────────────────────────┘

核心价值

价值	说明
复用性	一次定义，到处使用
标准化	统一的接口和输出格式
可维护	集中管理，便于更新
可组合	多个 Skill 组合完成复杂任务

---

6.2 Skill 设计模式

6.2.1 单一职责模式

每个 Skill 只做一件事，职责明确：

# 好的设计：每个 Skill 职责单一
skills:
  - name: commit
    trigger: /commit
    description: 生成提交信息并提交代码
    action: git commit with AI-generated message

  - name: review-pr
    trigger: /review-pr
    description: 审查 Pull Request
    action: review pull request changes

  - name: simplify
    trigger: /simplify
    description: 检查代码质量
    action: review code for reuse and quality

# 不好的设计：一个 Skill 做太多事情
skills:
  - name: do-everything
    trigger: /run
    description: 提交、测试、部署一体化
    action: commit, test, deploy all in one

6.2.2 组合模式

多个 Skill 组合完成复杂任务：

# 发布流程组合
release_workflow:
  name: 完整发布流程
  description: 代码提交到部署的完整流程
  steps:
    - skill: test          # 运行测试
      on_failure: abort

    - skill: review        # 代码审查
      on_failure: notify

    - skill: version-bump  # 版本更新
      params:
        type: minor

    - skill: changelog     # 生成变更日志

    - skill: commit        # 提交更改
      params:
        message: "chore: release v${version}"

    - skill: deploy        # 部署应用
      env: production

6.2.3 参数化模式

Skill 支持参数化调用：

skill:
  name: generate-docs
  trigger: /docs
  description: 生成 API 文档

  parameters:
    - name: format
      type: select
      options: [markdown, html, openapi]
      default: markdown
      description: 输出格式

    - name: output
      type: path
      default: ./docs
      description: 输出目录

    - name: include-private
      type: boolean
      default: false
      description: 是否包含私有 API

  examples:
    - command: /docs
      description: 使用默认参数生成文档

    - command: /docs --format html --output ./api-docs
      description: 生成 HTML 格式文档到指定目录

---

6.3 实战案例：构建项目专属 Skill

场景：Java 项目代码规范 Skill

为团队构建一个自动检查 Java 代码规范的 Skill。

Skill 配置文件

# .claude/skills/java-standards/skill.yaml
name: java-standards
version: 1.0.0
description: Java 项目代码规范检查与修复
author: Team

# 触发条件
trigger:
  patterns:
    - /java-check
    - /规范检查
  keywords:
    - "检查代码规范"
    - "Java 规范"

# 执行定义
execution:
  type: prompt
  template: |
    请检查以下 Java 代码是否符合项目规范：

    ## 代码规范要求

    ### 命名规范
    - 类名使用 PascalCase（如：UserService）
    - 方法名和变量名使用 camelCase（如：getUserById）
    - 常量使用 UPPER_SNAKE_CASE（如：MAX_RETRY_COUNT）
    - 包名全部小写（如：com.example.service）

    ### 注释规范
    - 类和公共方法必须有 Javadoc 注释
    - 复杂逻辑需要行内注释
    - 注释使用中文
    - 注释格式：
      ```java
      /**
       * 用户服务类
       * @author 开发者
       * @date 2025-01-01
       */

### 代码结构
- 单个类不超过 500 行
- 单个方法不超过 50 行
- 方法参数不超过 5 个
- 使用 try-with-resources 处理资源

### 注解使用
- 使用 Lombok 减少样板代码（@Data, @Builder）
- 使用 @NonNull 进行空值检查
- 使用 @Override 标注重写方法

### 日志规范
- 使用 SLF4J + Logback
- 日志级别：ERROR > WARN > INFO > DEBUG > TRACE
- 敏感信息脱敏处理

### 异常处理
- 不捕获 Exception，捕获具体异常
- 异常必须包含上下文信息
- 不使用 e.printStackTrace()

请检查代码：
{{code}}

## 输出格式

### 1. 问题列表
| 文件 | 行号 | 严重程度 | 问题描述 | 建议修改 |
|------|------|----------|----------|----------|

### 2. 修复后的代码
```java
// 修复后的完整代码
```

示例

examples:

• input: "/java-check src/main/java/com/example/UserService.java" output: |

  检查结果：UserService.java

  问题列表

  文件	行号	严重程度	问题描述	建议修改
  UserService.java	1	高	缺少类级别 Javadoc 注释	添加类注释
  UserService.java	15	中	方法名 getuser 不符合规范	改为 getUser
  UserService.java	23	低	日志使用 System.out	改用 log.info()

  修复后的代码

  /**
   * 用户服务类
   * @author team
   * @date 2025-03-17
   */
  @Service
  @Slf4j
  public class UserService {
  
      /**
       * 根据ID获取用户信息
       * @param id 用户ID
       * @return 用户信息
       */
      public User getUser(Long id) {
          log.info("获取用户信息, id: {}", id);
          // ...
      }
  }

元数据

metadata: language: java tags: [code-quality, lint, standards] scope: project

### 使用方式

```bash
# 在 Claude Code 中使用
> /java-check src/main/java/com/example/UserService.java

# 或者
> 请帮我检查这个 Java 文件是否符合规范: UserService.java

# 批量检查
> /java-check src/main/java/**/*.java

---

6.4 企业 Skill 库构建

目录结构

enterprise-skill-library/
├── skills/
│   ├── code-review/
│   │   ├── skill.yaml           # Skill 定义
│   │   └── templates/
│   │       ├── review-prompt.md
│   │       └── report-template.md
│   │
│   ├── api-docs/
│   │   ├── skill.yaml
│   │   └── templates/
│   │       ├── openapi-template.yaml
│   │       └── markdown-template.md
│   │
│   ├── test-gen/
│   │   ├── skill.yaml
│   │   └── templates/
│   │       ├── unit-test.java
│   │       └── integration-test.java
│   │
│   ├── security-scan/
│   │   ├── skill.yaml
│   │   └── rules/
│   │       ├── sql-injection.yaml
│   │       ├── xss.yaml
│   │       └── sensitive-data.yaml
│   │
│   └── java-standards/
│       ├── skill.yaml
│       └── rules/
│           ├── naming.yaml
│           └── structure.yaml
│
├── shared/
│   ├── prompts/
│   │   ├── common-header.md
│   │   └── output-format.md
│   │
│   └── schemas/
│       ├── issue-schema.json
│       └── report-schema.json
│
├── config.yaml
└── README.md

配置文件

# config.yaml
version: 1.0.0
name: Enterprise Skill Library
description: 企业级 AI 能力库

# 全局配置
global:
  default_model: gpt-4
  max_tokens: 4000
  temperature: 0.1

  # 共享模板
  templates:
    header: shared/prompts/common-header.md
    output_format: shared/prompts/output-format.md

# Skill 注册
skills:
  - name: code-review
    path: skills/code-review
    enabled: true
    triggers: [/review, /code-review]

  - name: api-docs
    path: skills/api-docs
    enabled: true
    triggers: [/docs, /api-docs]

  - name: test-gen
    path: skills/test-gen
    enabled: true
    triggers: [/test, /gen-test]

  - name: security-scan
    path: skills/security-scan
    enabled: true
    triggers: [/security, /scan]

  - name: java-standards
    path: skills/java-standards
    enabled: true
    triggers: [/java-check, /规范检查]

# 权限配置
permissions:
  code-review:
    - developer
    - tech_lead
  security-scan:
    - security_team
    - tech_lead
  api-docs:
    - developer
    - tech_writer

共享模板示例

# shared/prompts/common-header.md

你是一个专业的 {{role}}，拥有丰富的 {{domain}} 经验。

## 工作原则
1. 严谨：每个结论都有依据
2. 实用：建议具有可操作性
3. 清晰：表达简洁明了

## 输出规范
- 使用 Markdown 格式
- 代码块标注语言类型
- 问题按严重程度排序

输出 Schema 定义

// shared/schemas/issue-schema.json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "issues": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["file", "line", "severity", "message", "suggestion"],
        "properties": {
          "file": {"type": "string", "description": "文件路径"},
          "line": {"type": "integer", "description": "行号"},
          "severity": {
            "type": "string",
            "enum": ["high", "medium", "low", "info"],
            "description": "严重程度"
          },
          "message": {"type": "string", "description": "问题描述"},
          "suggestion": {"type": "string", "description": "修改建议"},
          "rule": {"type": "string", "description": "规则 ID"}
        }
      }
    },
    "summary": {
      "type": "object",
      "properties": {
        "total": {"type": "integer"},
        "high": {"type": "integer"},
        "medium": {"type": "integer"},
        "low": {"type": "integer"},
        "info": {"type": "integer"}
      }
    }
  }
}

---

6.5 Skill 最佳实践

1. 清晰的触发条件

# ✅ 好的设计
trigger:
  patterns:
    - /commit
    - /提交
  keywords:
    - "提交代码"
    - "生成 commit message"
    - "帮我提交"

# ❌ 不好的设计
trigger:
  patterns:
    - /c  # 太短，容易误触发

2. 结构化输出

# ✅ 好的设计：结构化输出
output:
  type: structured
  schema:
    type: object
    properties:
      issues:
        type: array
        items:
          type: object
          properties:
            file: string
            line: number
            severity: string
            message: string

# ❌ 不好的设计：无结构输出
output:
  type: text  # 难以解析和复用

3. 错误处理

error_handling:
  - condition: "file_not_found"
    action: "提示用户检查文件路径"
    message: "文件不存在，请检查路径: {{path}}"

  - condition: "parse_error"
    action: "提示代码语法错误"
    message: "代码解析失败，请检查语法: {{error}}"

  - condition: "timeout"
    action: "提供简化版本"
    message: "处理超时，已生成简化报告"

4. 版本管理

# skill.yaml
version: 2.0.0
changelog:
  - version: 2.0.0
    date: 2025-03-17
    changes:
      - "新增安全扫描规则"
      - "优化输出格式"
  - version: 1.0.0
    date: 2025-01-01
    changes:
      - "初始版本"

5. 文档完善

# skill.yaml
documentation:
  overview: |
    该 Skill 用于检查 Java 代码是否符合团队规范。

  usage: |
    基本用法：/java-check <文件路径>
    批量检查：/java-check <目录>/**/*.java

  examples:
    - command: /java-check UserService.java
      result: 检查单个文件
    - command: /java-check src/**/*.java
      result: 检查整个 src 目录

  limitations:
    - 不支持 Kotlin 代码
    - 最大文件大小 100KB

---

6.6 常用 Skill 示例

代码审查 Skill

name: code-review
description: 智能 PR 代码审查

trigger:
  patterns: [/review, /pr-review]

execution:
  type: prompt
  template: |
    请对以下代码变更进行审查：

    ## 变更内容
    {{diff}}

    ## 审查维度
    1. 代码质量
       - 命名规范
       - 代码结构
       - 注释完整性

    2. 潜在问题
       - 空指针风险
       - 资源泄漏
       - 并发安全

    3. 性能考量
       - 时间复杂度
       - 空间复杂度
       - 数据库查询优化

    4. 安全风险
       - SQL 注入
       - XSS 攻击
       - 敏感数据暴露

    ## 输出格式
    ### 总体评价：👍/⚠️/❌

    ### 问题列表
    | 类型 | 严重程度 | 问题描述 | 位置 | 建议 |

    ### 亮点
    - ...

    ### 改进建议
    - ...

测试生成 Skill

name: test-gen
description: 自动生成单元测试

trigger:
  patterns: [/test, /gen-test]

parameters:
  - name: framework
    type: select
    options: [junit5, jest, pytest]
    default: junit5
  - name: coverage
    type: number
    default: 80
    description: 目标覆盖率

execution:
  type: prompt
  template: |
    为以下代码生成单元测试：

    ## 代码
    ```{{language}}
    {{code}}

## 要求
- 测试框架：{{framework}}
- 目标覆盖率：{{coverage}}%
- 包含正常流程和异常流程
- 使用 Mock 隔离外部依赖

## 输出
```{{language}}
// 测试代码
```

---

## 6.7 Skill 与其他技术集成

### 与 MCP 集成

```typescript
// 将 Skill 暴露为 MCP Tool
import { Tool } from "@modelcontextprotocol/sdk/types.js";

const codeReviewSkill: Tool = {
  name: "code_review",
  description: "执行代码审查 Skill",
  inputSchema: {
    type: "object",
    properties: {
      file_path: { type: "string" },
      options: {
        type: "object",
        properties: {
          check_security: { type: "boolean" },
          check_performance: { type: "boolean" }
        }
      }
    },
    required: ["file_path"]
  }
};

与 Agent 集成

# 在 Agent 中使用 Skill
from langchain.tools import Tool

def create_skill_tool(skill_config):
    return Tool(
        name=skill_config["name"],
        description=skill_config["description"],
        func=lambda x: execute_skill(skill_config, x)
    )

# Agent 配置
skills = load_skills("./skill-library")
tools = [create_skill_tool(s) for s in skills]

agent = initialize_agent(
    tools=tools,
    llm=ChatOpenAI(model="gpt-4"),
    agent_type="structured-chat-zero-shot-react-description"
)

---

**下一篇：总结与项目汇总

---

欢迎关注的我的公众号《码上未来》，一起交流AI前沿技术!

添加我微信 return_not_null 进群聊AI