16.1 Skills创建方式

约 2627 字大约 9 分钟

创建 Skills 的基本流程

Skills 的创建是一个结构化的过程，遵循标准的目录结构和文件格式。本节将详细介绍创建 Skills 的完整流程。

1. 规划 Skills

定义目标和范围

在创建 Skills 之前，需要明确定义其目标和适用范围：

## 目标定义
- **功能描述**：Skills 解决的具体问题
- **适用场景**：何时应该使用这个 Skills
- **预期输出**：使用后的结果和价值
- **限制条件**：Skills 的局限性和边界

分析需求

## 需求分析
- **用户需求**：目标用户的使用场景
- **技术需求**：所需的工具和资源
- **性能需求**：响应时间和资源消耗要求
- **兼容性需求**：支持的平台和环境

2. 创建目录结构

标准目录结构

# 创建 Skills 目录
mkdir my-skill

# 进入目录
cd my-skill

# 查看标准结构
tree -a

目录命名规范

使用小写字母、数字和连字符
长度不超过64个字符
避免连续连字符或以连字符开头/结尾
目录名应与 SKILL.md 中的 name 字段一致

3. 编写 SKILL.md 文件

文件结构

SKILL.md 是 Skills 的核心文件，必须遵循特定的格式：

---
name: my-skill
description: Brief description of what this skill does and when to use it
---

# My Skill

## Overview

Detailed description of the skill's purpose and functionality.

## When to Use

Specific scenarios and conditions for using this skill.

## Instructions

Step-by-step guidance for the AI agent.

## Examples

Concrete examples of input and expected output.

前置元数据详解

必需字段

---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files, forms, or document extraction.
---

name: 唯一标识符，遵循命名规范
description: 功能描述和使用时机，应包含关键词帮助 AI 发现

可选字段

---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents.
license: Apache-2.0
compatibility: Designed for Claude Code (or similar products)
metadata:
  author: example-org
  version: "1.0"
allowed-tools: Read, Grep, Bash(python:*)
---

4. 添加支持文件

脚本文件 (scripts/)

# 创建脚本目录
mkdir scripts

# 添加 Python 脚本
cat > scripts/process_data.py << 'EOF'
#!/usr/bin/env python3
"""
数据处理脚本
"""
import sys
import json

def process_data(input_data):
    """处理输入数据"""
    # 处理逻辑
    return processed_data

if __name__ == "__main__":
    input_data = sys.stdin.read()
    result = process_data(input_data)
    print(json.dumps(result))
EOF

# 设置执行权限
chmod +x scripts/process_data.py

参考文档 (references/)

# 创建参考文档目录
mkdir references

# 添加 API 文档
cat > references/api_reference.md << 'EOF'
# API 参考文档

## 可用端点

### GET /api/data
获取数据列表

**参数：**
- `limit` (可选): 返回结果数量限制
- `offset` (可选): 偏移量

**响应：**
```json
{
  "data": [...],
  "total": 100
}

EOF



#### 静态资源 (assets/)


```bash
# 创建资源目录
mkdir assets

# 添加配置文件模板
cat > assets/config_template.json << 'EOF'
{
  "database": {
    "host": "localhost",
    "port": 5432,
    "name": "myapp"
  },
  "features": {
    "caching": true,
    "logging": true
  }
}
EOF

5. 编写指令内容

结构化指令编写

# My Skill Name

## 概述

[简要介绍 Skills 的功能和价值]

## 使用时机

[明确说明何时应该使用这个 Skills]
- 场景1：具体的使用情况
- 场景2：另一种使用情况

## 详细说明

### 步骤1：准备工作
[具体的执行步骤]

### 步骤2：主要处理
[核心处理逻辑]

### 步骤3：结果验证
[验证和确认结果]

## 示例

### 示例1：基本用法
**输入：**

用户请求示例


**执行步骤：**
1. 解析输入
2. 处理数据
3. 生成输出

**输出：**

预期结果


### 示例2：高级用法
[更复杂的示例]

## 注意事项

### 限制条件
- [已知限制]
- [不支持的场景]

### 错误处理
- [常见错误及解决方法]

### 性能考虑
- [性能特征和优化建议]

## 相关资源

- [API 文档](references/api_reference.md)
- [配置模板](assets/config_template.json)

6. 测试和验证

本地验证

# 验证 SKILL.md 格式
python -c "
import yaml
import os

# 检查文件存在
assert os.path.exists('SKILL.md'), 'SKILL.md not found'

# 读取并解析
with open('SKILL.md', 'r', encoding='utf-8') as f:
    content = f.read()

# 分离元数据和内容
parts = content.split('---', 2)
assert len(parts) >= 3, 'Invalid SKILL.md format'

metadata = yaml.safe_load(parts[1])
assert 'name' in metadata, 'Missing name field'
assert 'description' in metadata, 'Missing description field'

print('SKILL.md format validation passed')
"

功能测试

# 测试脚本执行
python scripts/process_data.py < test_input.json

# 验证输出格式
python scripts/process_data.py < test_input.json | jq .data

7. 部署和发布

本地部署

# 复制到个人 Skills 目录
cp -r my-skill ~/.claude/skills/

# 或复制到项目 Skills 目录
cp -r my-skill .claude/skills/

团队共享

# 添加到版本控制
git add my-skill/
git commit -m "Add my-skill for data processing"

# 推送到远程仓库
git push origin main

插件发布

# 创建插件结构
mkdir my-plugin
cd my-plugin

# 添加 Skills 到插件
cp -r ../my-skill skills/

# 创建插件配置文件
cat > package.json << EOF
{
  "name": "my-plugin",
  "version": "1.0.0",
  "skills": ["skills/my-skill"]
}
EOF

创建最佳实践

1. 从简单开始

从解决单个具体问题开始
避免一开始就设计过于复杂的 Skills
基于实际使用场景逐步扩展

2. 编写清晰的描述

# 好的描述示例
description: Analyze Excel spreadsheets, create pivot tables, and generate charts. Use when working with Excel files, spreadsheets, or .xlsx files.

# 不好的描述示例
description: Helps with data

3. 提供丰富的示例

包含多种使用场景的示例
展示输入输出格式
解释每一步的目的

4. 测试驱动开发

在编写过程中持续测试
验证在不同场景下的表现
收集反馈并改进

5. 遵循命名规范

使用描述性的名称
保持一致的命名风格
避免名称冲突

使用 skill-creator 辅助创建

Anthropic 提供了官方的 skill-creator Skills，可以帮助用户快速创建新的 Skills。这个 Skills 提供了完整的创建流程指导，从需求分析到最终打包。

skill-creator 概述

skill-creator 是 Anthropic 官方提供的 Skills，专门用于指导和辅助创建其他 Skills。它的主要功能包括：

理解需求：通过分析具体示例来理解 Skills 应该实现的功能
规划内容：识别可重用的脚本、参考文档和资源文件
生成结构：自动创建 Skills 的标准目录结构
编写文档：帮助编写 SKILL.md 和相关文档
打包验证：验证并打包 Skills
迭代优化：基于实际使用改进 Skills

使用 skill-creator 创建新 Skills

步骤1：准备示例

在使用 skill-creator 之前，需要准备一些具体的使用示例：

## 示例准备
- **场景描述**：用户请求和预期行为
- **输入输出**：具体的输入数据和期望结果
- **执行流程**：手动执行时的步骤
- **特殊情况**：边界条件和错误处理

步骤2：调用 skill-creator

在 Claude Code 中使用 skill-creator：

# 直接使用 skill-creator
claude --skill skill-creator

# 或在对话中使用
"请使用 skill-creator 帮助我创建一个处理 PDF 文件的 Skills"

步骤3：提供需求描述

向 skill-creator 提供详细的需求信息：

## 需求描述
- **功能目标**：创建一个处理 PDF 文件的 Skills
- **具体任务**：
  - 提取 PDF 中的文本内容
  - 识别表格数据
  - 合并多个 PDF 文件
- **使用场景**：
  - "请从这个 PDF 中提取表格数据"
  - "合并这些 PDF 文件"
- **技术要求**：
  - 支持中文文本
  - 处理扫描版 PDF
  - 输出结构化数据

步骤4：跟随指导创建

skill-creator 会提供分步指导：

需求理解：分析提供的示例和工作流程
资源规划：识别需要创建的脚本和文档
结构初始化：生成标准的 Skills 目录结构
内容编写：帮助编写 SKILL.md 和实现脚本
测试验证：验证 Skills 的功能和格式
打包发布：创建可分发的 Skills 包

步骤5：迭代优化

基于实际使用情况进行优化：

# 测试 Skills
claude --skill my-pdf-skill --test

# 收集反馈并改进
"这个 Skills 在处理中文 PDF 时有问题，请帮我优化"

# 重新打包
skill-creator 会指导重新打包和发布

skill-creator 的优势

1. 结构化指导

提供完整的创建流程
确保遵循最佳实践
避免常见错误

2. 自动化生成

自动创建目录结构
生成模板文件
验证配置正确性

3. 质量保证

内置验证机制
提供测试指导
确保文档完整性

4. 学习辅助

解释每个步骤的目的
提供示例和模板
帮助理解 Skills 设计原则

适用场景

适合使用 skill-creator 的情况：

新手创建者：第一次创建 Skills 的用户
复杂功能：需要多个组件配合的 Skills
标准化需求：需要遵循最佳实践的项目
团队协作：多人协作开发 Skills

不适合使用 skill-creator 的情况：

简单脚本：只需几个命令的简单任务
已有模板：基于现有成熟模板的 Skills
高度定制：需要完全自定义结构的特殊需求

最佳实践

1. 准备充分的示例

提供多样化的使用场景
包含边界条件和错误情况
描述预期的输出格式

2. 遵循指导逐步执行

不要跳过任何步骤
仔细阅读每个指导说明
如有疑问及时寻求 clarification

3. 充分测试和验证

在创建过程中进行测试
验证所有功能正常工作
检查文档和示例的准确性

4. 基于反馈持续改进

收集实际使用中的问题
根据用户反馈进行优化
定期更新和维护 Skills

常见问题和解决方案

文件格式问题

问题：YAML 前置元数据格式错误解决：使用 YAML 验证工具检查语法

路径引用问题

问题：相对路径引用不正确解决：确保所有路径都是相对于 Skills 根目录的

权限问题

问题：脚本文件没有执行权限解决：使用 chmod +x 设置执行权限

编码问题

问题：文件编码导致的解析错误解决：统一使用 UTF-8 编码保存文件

总结

创建 Skills 是一个系统化的过程，需要仔细规划、规范编写和充分测试。通过遵循标准结构和最佳实践，可以创建出高质量、可维护的 Skills，为 AI 代理提供强大的专业能力扩展。

技术说明：本章中的代码示例是为了帮助您理解原理而提供的。实际创建和管理 Skills 时，您不需要编写这些代码，系统会自动处理大部分技术细节。