16.1 Skills 创建方式

Skills 创建方式概述

Claude Code 提供了多种创建 Skills 的方式，从简单的自然语言描述到复杂的编程实现，满足不同场景和技能水平的需求。本节将详细介绍各种创建方式及其适用场景。

## 创建方式分类

### 1\. 自然语言描述

#### 1.1 基本描述

    markdown


    ## Skill: 代码审查

    ### 功能
    自动审查代码质量，检查安全性、性能和最佳实践。

    ### 输入
    - 代码文件路径
    - 审查标准（可选）
    - 严格程度（可选）

    ### 执行步骤
    1. 读取代码文件
    2. 分析代码结构
    3. 检查安全问题
    4. 评估代码质量
    5. 生成审查报告

    ### 输出
    - 审查报告
    - 问题列表
    - 改进建议

#### 1.2 详细描述

    markdown


    ## Skill: API 端点生成

    ### 目标
    根据数据模型自动生成 REST API 端点

    ### 功能描述
    本 Skill 能够分析数据模型定义，自动生成符合 RESTful 规范的 API 端点，包括路由定义、控制器逻辑、输入验证和响应格式。

    ### 输入参数
    - `model_file`: 数据模型文件路径（必需）
    - `framework`: 使用的框架（可选，默认：Flask）
    - `output_dir`: 输出目录（可选，默认：./api）
    - `include_tests`: 是否生成测试（可选，默认：true）

    ### 执行流程
    1. **模型分析阶段**
       - 读取数据模型文件
       - 解析模型定义
       - 识别字段和关系

    2. **端点生成阶段**
       - 为每个模型生成 CRUD 端点
       - 创建路由定义
       - 实现控制器逻辑

    3. **验证实现阶段**
       - 添加输入验证
       - 实现数据验证规则
       - 生成验证错误处理

    4. **文档生成阶段**
       - 生成 API 文档
       - 添加端点说明
       - 提供示例代码

    5. **测试生成阶段**
       - 生成单元测试
       - 创建集成测试
       - 添加测试数据

    ### 输出内容
    - 路由文件（routes.py）
    - 控制器文件（controllers.py）
    - 验证文件（validators.py）
    - API 文档（api.md）
    - 测试文件（test_api.py）

    ### 示例

    输入：

    ```python

    class User:
        id: int
        name: str
        email: str
        created_at: datetime

输出：

python


# routes.py
from flask import Blueprint, request, jsonify
from datetime import datetime

users_bp = Blueprint('users', __name__)

@users_bp.route('/users', methods=['GET'])
def get_users():
    """获取用户列表"""
    users = User.query.all()
    return jsonify([{
        'id': user.id,
        'name': user.name,
        'email': user.email,
        'created_at': user.created_at.isoformat()
    } for user in users])

@users_bp.route('/users/<int:id>', methods=['GET'])
def get_user(id):
    """获取单个用户"""
    user = User.query.get_or_404(id)
    return jsonify({
        'id': user.id,
        'name': user.name,
        'email': user.email,
        'created_at': user.created_at.isoformat()
    })

@users_bp.route('/users', methods=['POST'])
def create_user():
    """创建新用户"""
    data = request.get_json()
    user = User(
        name=data['name'],
        email=data['email']
    )
    from flask_sqlalchemy import SQLAlchemy
    db.session.add(user)
    db.session.commit()
    return jsonify({
        'id': user.id,
        'name': user.name,
        'email': user.email,
        'created_at': user.created_at.isoformat()
    }), 201

@users_bp.route('/users/<int:id>', methods=['PUT'])
def update_user(id):
    """更新用户信息"""
    user = User.query.get_or_404(id)
    data = request.get_json()
    user.name = data.get('name', user.name)
    user.email = data.get('email', user.email)
    db.session.commit()
    return jsonify({
        'id': user.id,
        'name': user.name,
        'email': user.email,
        'created_at': user.created_at.isoformat()
    })

@users_bp.route('/users/<int:id>', methods=['DELETE'])
def delete_user(id):
    """删除用户"""
    user = User.query.get_or_404(id)
    db.session.delete(user)
    db.session.commit()
    return '', 204

bash


### 2. 示例驱动

#### 2.1 输入输出示例

```markdown

## Skill: 代码格式化

    ### 功能
    根据项目规范自动格式化代码

    ### 输入示例

def calculate_sum(numbers): total=0 for n in numbers: total+=n return total

    bash


    ### 输出示例

def calculate_sum(numbers): total = 0 for n in numbers: total += n return total

    bash


    ### 变换规则
    - 运算符周围添加空格
    - 逗号后添加空格
    - 缩进使用 4 个空格
    - 函数定义后添加空行

    ### 2.2 多示例学习

    ```markdown

    ## Skill: 函数重构

```python
    ### 功能
    将复杂函数重构为更小的、可维护的函数

    ### 示例 1

    ```python

    # 输入

    def process_user_data(data):
        if not data:
            return None
        user = User()
        user.name = data.get('name')
        user.email = data.get('email')
        if not user.email:
            raise ValueError('Email is required')
        user.age = data.get('age', 0)
        if user.age < 0:
            raise ValueError('Age must be positive')
        return user

    python

# 输出
def validate_email(email):
    if not email:
        raise ValueError('Email is required')
    return email

def validate_age(age):
    if age < 0:
        raise ValueError('Age must be positive')
    return age

def create_user_from_data(data):
    if not data:
        return None

    user = User()
    user.name = data.get('name')
    user.email = validate_email(data.get('email'))
    user.age = validate_age(data.get('age', 0))

    return user

示例 2

python


# 输入
def calculate_price(items):
    total = 0
    for item in items:
        if item['type'] == 'book':
            total += item['price'] * 0.9
        elif item['type'] == 'food':
            total += item['price'] * 0.95
        else:
            total += item['price']
    return total

python


# 输出
def apply_discount(item):
    if item['type'] == 'book':
        return item['price'] * 0.9
    elif item['type'] == 'food':
        return item['price'] * 0.95
    else:
        return item['price']

def calculate_price(items):
    total = 0
    for item in items:
        total += apply_discount(item)
    return total

bash


#### 3.1 模板定义

```markdown

## Skill: 文件生成模板

    ### 模板内容

# {{file_name}}

# Generated by Claude Code Skill

# Date: {{date}}

import {{imports}}

class {{class_name}}: """{{class_description}}"""

    bash

    def __init__(self{{init_params}}):
        """Initialize {{class_name}}"""
        {{init_body}}

    def {{method_name}}(self{{method_params}}):
        """{{method_description}}"""
        {{method_body}}

    bash

### 变量说明
- `file_name`: 文件名
- `date`: 生成日期
- `imports`: 导入语句
- `class_name`: 类名
- `class_description`: 类描述
- `init_params`: 初始化参数
- `init_body`: 初始化方法体
- `method_name`: 方法名
- `method_params`: 方法参数
- `method_description`: 方法描述
- `method_body`: 方法体

3.2 模板使用

markdown

    ## Skill: 模型生成

    ### 使用模板

# user.py

# Generated by Claude Code Skill

# Date: 2024-01-15

from datetime import datetime from typing import Optional

class User: """User model representing a user in the system"""

    bash

    def __init__(self, id: int, name: str, email: str, created_at: Optional[datetime] = None):
        """Initialize User"""
        self.id = id
        self.name = name
        self.email = email
        self.created_at = created_at or datetime.now()

    def validate(self):
        """Validate user data"""
        if not self.email:
            raise ValueError("Email is required")
        if not self.name:
            raise ValueError("Name is required")

    bash

    ### 参数映射

    ```json

    {
      "file_name": "user.py",
      "date": "2024-01-15",
      "imports": "from datetime import datetime\nfrom typing import Optional",
      "class_name": "User",
      "class_description": "User model representing a user in the system",
      "init_params": ", id: int, name: str, email: str, created_at: Optional[datetime] = None",
      "init_body": "self.id = id\n        self.name = name\n        self.email = email\n        self.created_at = created_at or datetime.now()",
      "method_name": "validate",
      "method_params": "",
      "method_description": "Validate user data",
      "method_body": "if not self.email:\n            raise ValueError(\"Email is required\")\n        if not self.name:\n            raise ValueError(\"Name is required\")"
    }

### 4\. 编程实现

#### 4.1 基础实现

    python

class CodeReviewSkill:
    def __init__(self):
        self.name = "code-review"
        self.version = "1.0.0"
        self.description = "自动审查代码质量"

    def validate_parameters(self, parameters):
        required = ["file"]
        for param in required:
            if param not in parameters:
                raise ValueError(f"Missing required parameter: {param}")
        return True

    def execute(self, parameters, context):
        # 验证参数
        self.validate_parameters(parameters)

        # 读取文件
        file_path = parameters["file"]
        with open(file_path, 'r') as f:
            code = f.read()

        # 分析代码
        issues = self.analyze_code(code)

        # 生成报告
        report = self.generate_report(issues)

        return report

    def analyze_code(self, code):
        issues = []

        # 检查代码长度
        if len(code) > 1000:
            issues.append({
                "type": "complexity",
                "severity": "medium",
                "message": "代码过长，建议拆分"
            })

        # 检查注释
        if '"""' not in code and "'''" not in code:
            issues.append({
                "type": "documentation",
                "severity": "low",
                "message": "缺少文档字符串"
            })

        return issues

    def generate_report(self, issues):
        report = {
            "total_issues": len(issues),
            "issues": issues,
            "summary": self.generate_summary(issues)
        }
        return report

    def generate_summary(self, issues):
        severity_count = {}
        for issue in issues:
            severity = issue["severity"]
            severity_count[severity] = severity_count.get(severity, 0) + 1
        return severity_count

4.2 高级实现

python


import ast
import re
from typing import List, Dict, Any

class AdvancedCodeReviewSkill:
    def __init__(self):
        self.name = "advanced-code-review"
        self.version = "2.0.0"
        self.description = "高级代码审查"
        self.checkers = [
            SecurityChecker(),
            PerformanceChecker(),
            StyleChecker(),
            ComplexityChecker()
        ]

    def execute(self, parameters, context):
        # 验证参数
        self.validate_parameters(parameters)

        # 读取文件
        file_path = parameters["file"]
        code = self.read_file(file_path)

        # 解析 AST
        tree = ast.parse(code)

        # 运行检查器
        all_issues = []
        for checker in self.checkers:
            issues = checker.check(tree, code, context)
            all_issues.extend(issues)

        # 生成报告
        report = self.generate_report(all_issues, file_path)
        return report

    def read_file(self, file_path):
        with open(file_path, 'r', encoding='utf-8') as f:
            return f.read()

    def generate_report(self, issues, file_path):
        return {
            "file": file_path,
            "total_issues": len(issues),
            "issues_by_severity": self.group_by_severity(issues),
            "issues_by_type": self.group_by_type(issues),
            "issues": issues,
            "recommendations": self.generate_recommendations(issues)
        }

    def group_by_severity(self, issues):
        grouped = {}
        for issue in issues:
            severity = issue["severity"]
            if severity not in grouped:
                grouped[severity] = []
            grouped[severity].append(issue)
        return grouped

    def group_by_type(self, issues):
        grouped = {}
        for issue in issues:
            issue_type = issue["type"]
            if issue_type not in grouped:
                grouped[issue_type] = []
            grouped[issue_type].append(issue)
        return grouped

    def generate_recommendations(self, issues):
        recommendations = []
        for issue in issues:
            if issue["severity"] in ["high", "critical"]:
                recommendations.append({
                    "issue": issue,
                    "priority": "high",
                    "action": self.get_fix_action(issue)
                })
        return recommendations

    def get_fix_action(self, issue):
        actions = {
            "security": "立即修复安全问题",
            "performance": "优化性能瓶颈",
            "style": "调整代码风格",
            "complexity": "简化复杂逻辑"
        }
        return actions.get(issue["type"], "审查并修复")

class SecurityChecker:
    def check(self, tree, code, context):
        issues = []

        # 检查 SQL 注入
        sql_pattern = re.compile(r'execute\(["\'].*\+.*["\']\)')
        if sql_pattern.search(code):
            issues.append({
                "type": "security",
                "severity": "critical",
                "message": "潜在的 SQL 注入漏洞",
                "line": self.find_line(code, sql_pattern)
            })

        # 检查硬编码密码
        password_pattern = re.compile(r'password\s*=\s*["\'][^"\']+["\']')
        if password_pattern.search(code):
            issues.append({
                "type": "security",
                "severity": "high",
                "message": "硬编码密码",
                "line": self.find_line(code, password_pattern)
            })

        return issues

    def find_line(self, code, pattern):
        match = pattern.search(code)
        if match:
            return code[:match.start()].count('\n') + 1
        return 0

class PerformanceChecker:
    def check(self, tree, code, context):
        issues = []

        # 检查循环中的数据库查询
        for node in ast.walk(tree):
            if isinstance(node, ast.For):
                for child in ast.walk(node):
                    if isinstance(child, ast.Call):
                        if self.is_database_call(child):
                            issues.append({
                                "type": "performance",
                                "severity": "high",
                                "message": "循环中的数据库查询",
                                "line": node.lineno
                            })

        return issues

    def is_database_call(self, node):
        # 简化的数据库调用检测
        if isinstance(node.func, ast.Attribute):
            return node.func.attr in ['query', 'execute', 'find']
        return False

class StyleChecker:
    def check(self, tree, code, context):
        issues = []

        # 检查行长度
        for i, line in enumerate(code.split('\n'), 1):
            if len(line) > 100:
                issues.append({
                    "type": "style",
                    "severity": "low",
                    "message": "行过长",
                    "line": i
                })

        return issues

    def calculate_complexity(self, node):
        complexity = 1
        for child in ast.walk(node):
            if isinstance(child, (ast.If, ast.For, ast.While, ast.Try)):
                complexity += 1
        return complexity

### 5. 组合创建
#### 5.1 混合方式

```markdown

## Skill: 智能代码生成

    ### 创建方式
    - 自然语言描述：定义目标和约束
    - 示例驱动：提供输入输出示例
    - 模板化：使用代码模板
    - 编程实现：实现核心逻辑

    ### 自然语言描述
    根据用户需求生成符合项目规范的代码，包括函数定义、类实现、错误处理和文档。

    ### 示例驱动
    提供多个代码示例，展示不同场景下的生成结果。

    ### 模板化
    使用预定义的代码模板，确保生成的代码符合项目规范。

    ### 编程实现
    实现代码生成逻辑，包括 AST 解析、代码分析和模板渲染。

#### 5.2 分层实现

    python

    class HybridCodeGenerator:
        def __init__(self):
            self.description = self.load_description()
            self.examples = self.load_examples()
            self.templates = self.load_templates()
            self.generator = CodeGenerator()

        def execute(self, parameters, context):
            # 1. 理解需求（自然语言）
            requirements = self.understand_requirements(parameters)
            # 2. 查找示例（示例驱动）
            similar_examples = self.find_similar_examples(requirements)
            # 3. 选择模板（模板化）
            template = self.select_template(requirements, similar_examples)
            # 4. 生成代码（编程实现）
            code = self.generator.generate(requirements, template, context)
            # 5. 验证结果
            validated = self.validate_code(code, requirements)
            return validated

        def understand_requirements(self, parameters):
            # 使用自然语言理解解析需求
            pass

        def find_similar_examples(self, requirements):
            # 查找相似的示例
            pass

        def select_template(self, requirements, examples):
            # 选择合适的模板
            pass

        def validate_code(self, code, requirements):
            # 验证生成的代码
            pass

## 创建流程

### 1\. 需求分析

    markdown

    ## 需求分析步骤

    ### 1.1 明确目标
    - Skill 要解决什么问题？
    - 预期的输入和输出是什么？
    - 有什么特殊要求？

    ### 1.2 确定范围
    - Skill 的功能边界在哪里？
    - 需要支持哪些场景？
    - 有什么限制条件？

    ### 1.3 评估可行性
    - 技术上是否可行？
    - 需要什么资源？
    - 有什么风险？

### 2\. 设计 Skill

    markdown

    ## Skill 设计步骤

    ### 2.1 定义接口
    - 输入参数
    - 输出格式
    - 错误处理

    ### 2.2 设计流程
    - 执行步骤
    - 决策点
    - 异常处理

    ### 2.3 选择实现方式
    - 自然语言描述
    - 示例驱动
    - 模板化
    - 编程实现
    - 组合方式

### 3\. 实现 Skill

    markdown

    ## Skill 实现步骤

    ### 3.1 基础实现
    - 实现 Skill 框架
    - 实现基本功能
    - 添加错误处理

    ### 3.2 功能完善
    - 添加高级功能
    - 优化性能
    - 改进用户体验

    ### 3.3 测试验证
    - 单元测试
    - 集成测试
    - 性能测试

### 4\. 部署使用

    markdown

    ## Skill 部署步骤

    ### 4.1 注册 Skill
    - 添加到 Skill 库
    - 配置元数据
    - 设置权限

    ### 4.2 测试运行
    - 功能测试
    - 性能测试
    - 用户测试

    ### 4.3 文档编写
    - 使用说明
    - API 文档
    - 示例代码

## 最佳实践

### 1\. 简单场景

    markdown

## 简单场景建议

### 使用自然语言描述
- 任务简单明确
- 逻辑不复杂
- 不需要精确控制

### 示例
代码格式化、简单文本处理、基础代码生成

2. 中等复杂度

markdown


## 中等复杂度建议

### 使用示例驱动
- 需要展示模式
- 有多个变体
- 需要学习示例

### 示例
代码重构、模式应用、风格转换

3. 高复杂度

markdown


## 高复杂度建议

### 使用编程实现
- 需要精确控制
- 逻辑复杂
- 性能要求高

### 示例
复杂代码分析、性能优化、安全审计

4. 需要灵活性

markdown


## 需要灵活性建议

### 使用组合方式
- 需要多种能力
- 场景多变
- 需要适应性强

### 示例
智能代码生成、自动化工作流、复杂任务编排