Skill Creator 完整指南

本文档包含创建专业 Skills 的完整流程、高级设计模式和实战技巧。如果您是初次接触，建议先阅读 📋 概览。

Skill 深度解析

Skill 的本质

Skill = 入职指南

把 Skill 想象成新员工入职培训：

通用培训（AI 的基础能力）：基本语法、常识、通用算法
岗位培训（Skill）：特定流程、公司架构、领域知识

关键洞察：模型已经"很聪明"，Skill 只需提供模型无法自行推理的程序性知识。

Skill 的价值主张

场景	无 Skill	有 Skill
PDF 旋转	每次重写旋转代码	调用 `scripts/rotate_pdf.py`
BigQuery 查询	每次猜测表结构	参考 `references/schema.md`
品牌应用	每次询问品牌色	使用 `assets/logo.png` + 色彩变量
内部沟通	每次重新格式化	遵循 `references/templates.md`

结果：更快、更一致、更可靠。

设计原则深度解析

原则 1：上下文窗口经济学

问题：上下文窗口是有限资源

解决：渐进式披露 + 最小必要信息

三级加载系统

┌─────────────────────────────────────┐
│ 级别 1: 元数据 (始终加载)          │
│ ─────────────────────────────────   │
│ name: pdf-editor                    │
│ description: 编辑、旋转 PDF...      │
│ (~100 token)                        │
└─────────────────────────────────────┘
            ↓ (仅当触发时)
┌─────────────────────────────────────┐
│ 级别 2: SKILL.md 正文               │
│ ─────────────────────────────────   │
│ # PDF Editor                        │
│ ## 快速开始                         │
│ python scripts/rotate_pdf.py...     │
│ (~2000 token)                       │
└─────────────────────────────────────┘
            ↓ (仅当 AI 判断需要时)
┌─────────────────────────────────────┐
│ 级别 3: 打包资源                    │
│ ─────────────────────────────────   │
│ references/FORMS.md                 │
│ references/ADVANCED.md              │
│ scripts/rotate_pdf.py (可能不加载)  │
│ (无限制)                            │
└─────────────────────────────────────┘

最小必要信息原则

反面教材：

# PDF Editor

## 关于 PDF

PDF（Portable Document Format）是由 Adobe 在 1993 年发明的文件格式...
[500 字关于 PDF 历史]

## 关于 PyPDF2

PyPDF2 是一个 Python 库，用于读取和操作 PDF 文件...
[300 字关于库的介绍]

## 安装

首先安装依赖...

Token 成本: ~1000 token，但 AI 已经知道这些！

正确做法：

# PDF Editor

旋转 PDF：
\`\`\`bash
python scripts/rotate_pdf.py input.pdf --angle 90
\`\`\`

合并 PDF：
\`\`\`bash
python scripts/merge_pdfs.py file1.pdf file2.pdf output.pdf
\`\`\`

**高级功能**: 参见 [ADVANCED.md](references/ADVANCED.md)

Token 成本: ~100 token，直击要点。

原则 2：自由度的艺术

自由度光谱

低自由度 ←───────────────────→ 高自由度
(脚本)                        (文本指令)

├─────────┼─────────┼─────────┤
具体脚本   伪代码     启发式指导

何时使用低自由度（脚本）

特征：

操作脆弱（容易出错）
一致性关键
重复执行

示例：

# scripts/rotate_pdf.py
def rotate_pdf(input_path, output_path, angle):
    # 精确的旋转逻辑
    # 错误处理
    # 边缘情况处理

为什么不用文本指令：

AI 可能遗漏边缘情况
不同实例可能实现不同
调试困难

何时使用中自由度（伪代码 + 参数）

特征：

存在首选模式
允许一定变化
配置影响行为

示例：

## 数据分析流程

\`\`\`python
# 伪代码
data = load_data(source)
data = clean_data(data, remove_nulls=True, deduplicate=True)
insights = analyze(data, method='statistical')  # 或 'ml'
report = generate_report(insights, format='markdown')  # 或 'html'
\`\`\`

**参数说明**:
- `method`: 'statistical' 用于简单分析，'ml' 用于复杂模式
- `format`: 根据受众选择（技术受众用 markdown）

何时使用高自由度（文本指令）

特征：

多种方法有效
决策依赖上下文
启发式指导

示例：

## 撰写内部沟通

### 语气选择

根据受众调整语气：
- **工程团队**: 技术细节、精确性、代码示例
- **高管**: 业务影响、ROI、简洁摘要
- **全体员工**: 积极向上、包容性、故事化

### 结构建议

使用倒金字塔：
1. 最重要信息在前（便于扫描）
2. 支持细节在中
3. 背景信息在后

原则 3：渐进式披露实战

反模式：扁平结构

# BigQuery Skill

## 财务表
[3000 字关于 revenue、billing 表]

## 销售表
[2000 字关于 opportunities、pipeline 表]

## 产品表
[2500 字关于 usage、features 表]

## 营销表
[2000 字关于 campaigns 表]

问题：

用户问销售问题，加载了 9500 字
只需要 2000 字，浪费 7500 token

正确模式：分层结构

bigquery-skill/
├── SKILL.md
└── references/
    ├── finance.md    (财务表详情)
    ├── sales.md      (销售表详情)
    ├── product.md    (产品表详情)
    └── marketing.md  (营销表详情)

SKILL.md (导航层)：

# BigQuery Skill

## 领域选择

根据查询类型选择参考文档：

- **财务指标** (revenue, billing) → [finance.md](references/finance.md)
- **销售数据** (opportunities, pipeline) → [sales.md](references/sales.md)
- **产品使用** (API calls, features) → [product.md](references/product.md)
- **营销归因** (campaigns, conversions) → [marketing.md](references/marketing.md)

## 快速查询模板

\`\`\`sql
-- 今日活跃用户
SELECT COUNT(DISTINCT user_id) 
FROM events 
WHERE DATE(timestamp) = CURRENT_DATE()
\`\`\`

结果：

销售查询 → 只加载 SKILL.md (200 字) + sales.md (2000 字)
节省 7300 token

6 步创建流程详解

步骤 1：理解具体示例（深度版）

为什么需要具体示例？

错误起点：

用户："我需要一个 PDF 编辑器 skill"
AI："好的，我会创建..."

问题：太模糊！"PDF 编辑器"可能意味着：

简单旋转？
复杂表单填充？
OCR 文字识别？
数字签名？

正确起点：

AI："能给我一些具体示例吗？你会如何使用这个 skill？"

用户：
"示例 1: 我有扫描的文档倒置了，需要旋转 180 度"
"示例 2: 我需要合并多个报告 PDF 成一个文件"
"示例 3: 我需要从大文档中提取特定页面"

AI："明白了！主要是旋转、合并、提取页面。不需要表单填充或 OCR？"

用户："对，暂时不需要"

收集示例的技巧

问题层级：

功能层："skill 应该支持什么功能？"
场景层："能给一些使用场景吗？"
触发层："用户会怎么说来触发这个 skill？"
边界层："有什么是不应该包含的？"

示例对话：

AI："这个图像编辑 skill 应该支持什么功能？"
用户："编辑、旋转、调整大小"

AI："'编辑'包含哪些具体操作？"
用户："去除红眼、调整亮度、裁剪"

AI："用户可能怎么说？给我一些例子"
用户：
- "移除这张照片的红眼"
- "把这张图片旋转 90 度"
- "将图片尺寸调整为 800x600"

AI："滤镜效果（如黑白、复古）应该包含吗？"
用户："不，那太复杂了。专注基本编辑"

步骤 2：规划可复用内容（深度版）

分析框架

对每个示例问：

执行复杂度：从零开始需要多少步骤？
重复性：会经常执行吗？
确定性需求：必须完全一致吗？
上下文依赖：需要领域知识吗？

决策矩阵

特征	解决方案	放在哪里
重复代码	脚本	`scripts/`
领域知识	文档	`references/`
样板文件	模板	`assets/`
简单指令	文本	`SKILL.md`

实战案例分析

案例 1：前端应用构建器

示例：

"创建一个待办事项应用"
"构建一个仪表板追踪我的步数"
"做一个天气应用"

分析：

执行复杂度：中等（需要 HTML/React 样板）
重复性：高（每个应用都需要相同样板）
确定性需求：中等（结构相似但内容不同）
上下文依赖：低

决策：

assets/
├── react-template/
│   ├── package.json
│   ├── index.html
│   ├── App.jsx
│   └── main.jsx
└── html-template/
    ├── index.html
    └── styles.css

案例 2：BigQuery 数据查询

示例：

"今天有多少用户登录了？"
"上周的收入是多少？"
"哪些功能使用最频繁？"

分析：

执行复杂度：低（SQL 查询简单）
重复性：高（经常查询）
确定性需求：低（查询可变化）
上下文依赖：高（必须知道表结构）

决策：

references/
├── schema.md         # 表结构、关系
├── common-queries.md # 常见查询模板
└── metrics.md        # 指标定义

案例 3：PDF 旋转

示例：

"旋转这个 PDF 90 度"
"把倒置的扫描文档转正"

分析：

执行复杂度：中等（需要库、错误处理）
重复性：高
确定性需求：高（必须精确旋转）
上下文依赖：低

决策：

scripts/
└── rotate_pdf.py    # 确定性脚本

步骤 3-5：实现与打包（深度版）

脚本编写最佳实践

1. 清晰的参数处理

#!/usr/bin/env python3
"""
旋转 PDF 文件

Usage:
    rotate_pdf.py <input> <output> --angle <90|180|270>
    rotate_pdf.py <input> <output> -a <angle>
"""
import argparse
from PyPDF2 import PdfReader, PdfWriter

def main():
    parser = argparse.ArgumentParser(description='旋转 PDF 文件')
    parser.add_argument('input', help='输入 PDF 路径')
    parser.add_argument('output', help='输出 PDF 路径')
    parser.add_argument('-a', '--angle', type=int, required=True,
                       choices=[90, 180, 270],
                       help='旋转角度 (90, 180, 或 270)')
    
    args = parser.parse_args()
    rotate_pdf(args.input, args.output, args.angle)

def rotate_pdf(input_path, output_path, angle):
    try:
        reader = PdfReader(input_path)
        writer = PdfWriter()
        
        for page in reader.pages:
            page.rotate(angle)
            writer.add_page(page)
        
        with open(output_path, 'wb') as f:
            writer.write(f)
        
        print(f"✓ 成功旋转 {len(reader.pages)} 页 ({angle}°)")
        print(f"✓ 已保存: {output_path}")
    
    except FileNotFoundError:
        print(f"✗ 错误: 找不到文件 {input_path}")
        exit(1)
    except Exception as e:
        print(f"✗ 错误: {str(e)}")
        exit(1)

if __name__ == '__main__':
    main()

2. 测试脚本

# 创建测试 PDF
echo "测试" | enscript -B -o - | ps2pdf - test.pdf

# 测试旋转
python scripts/rotate_pdf.py test.pdf output.pdf --angle 90

# 验证输出
ls -lh output.pdf  # 应该存在

SKILL.md 编写技巧

1. description 的完整性

❌ 不完整：

description: Edit PDF files.

问题：

没说支持什么操作
没说何时触发
太模糊

✅ 完整：

description: >
  Edit, rotate, merge, and extract pages from PDF files using PyPDF2. 
  Use this skill when working with PDF documents for:
  (1) Rotating pages (90/180/270 degrees),
  (2) Merging multiple PDFs into one file,
  (3) Extracting specific pages from a document,
  (4) Analyzing PDF structure and metadata.
  Do NOT use for OCR, form filling, or digital signatures.

包含：

做什么（Edit, rotate, merge, extract）
何时使用（4 个具体场景）
不做什么（明确边界）

2. 正文的清晰性

结构模板：

# [Skill Name]

## 快速开始
[最简单 80% 场景的示例]

## 核心功能
### 功能 1
[说明 + 示例]

### 功能 2
[说明 + 示例]

## 高级功能
[链接到 references/]

## 常见问题
[FAQ]

步骤 6：迭代（深度版）

迭代触发点

何时迭代：

使用中发现低效："每次都要手动查找表名"
用户反馈："能不能支持批量旋转？"
边缘情况："遇到加密 PDF 就失败了"
新需求："现在也需要 OCR 功能"

迭代模式

模式 1：扩展脚本

# 原始版本
def rotate_pdf(input_path, output_path, angle):
    # 基本旋转

# 迭代后
def rotate_pdf(input_path, output_path, angle, 
               pages=None,        # 新增：仅旋转特定页
               preserve_links=True):  # 新增：保留链接
    # 增强功能

模式 2：拆分 references

# 原始结构
references/
└── all-in-one.md (5000 行)

# 迭代后
references/
├── basic.md     (常用功能)
├── advanced.md  (高级功能)
└── api-ref.md   (完整 API)

模式 3：添加示例

# 原始版本
## 合并 PDF
使用 merge_pdfs.py 合并文件。

# 迭代后
## 合并 PDF

### 基本合并
\`\`\`bash
python scripts/merge_pdfs.py file1.pdf file2.pdf output.pdf
\`\`\`

### 高级：选择性合并页面
\`\`\`bash
# 合并 file1 的第 1-3 页和 file2 的第 5 页
python scripts/merge_pdfs.py \\
  file1.pdf:1-3 \\
  file2.pdf:5 \\
  output.pdf
\`\`\`

高级设计模式

模式 1：多框架支持

场景：Skill 支持多个框架（AWS/GCP/Azure、React/Vue等）

反模式：所有框架混在一起

# Cloud Deploy

## AWS 部署
[3000 字 AWS 详情]

## GCP 部署
[2500 字 GCP 详情]

## Azure 部署
[2800 字 Azure 详情]

问题：用户选 AWS，加载了 8300 字，只需要 3000 字。

正确模式：按框架分离

cloud-deploy/
├── SKILL.md (框架选择 + 通用流程)
└── references/
    ├── aws.md
    ├── gcp.md
    └── azure.md

SKILL.md：

# Cloud Deploy

## 选择云提供商

根据项目需求选择：
- **AWS** → [aws.md](references/aws.md)
- **GCP** → [gcp.md](references/gcp.md)
- **Azure** → [azure.md](references/azure.md)

## 通用部署流程

1. 配置环境变量
2. 构建应用
3. 推送到云平台
4. 验证部署

具体步骤参见各平台文档。

模式 2：工作流程链

场景：复杂多步骤流程，每步可能失败

模式：检查点 + 状态管理

# Data Pipeline

## 流程概览

数据管道包含 5 个阶段：

1. **提取** (Extract) → 运行 `scripts/extract.py`
2. **清洗** (Clean) → 运行 `scripts/clean.py`
3. **转换** (Transform) → 运行 `scripts/transform.py`
4. **验证** (Validate) → 运行 `scripts/validate.py`
5. **加载** (Load) → 运行 `scripts/load.py`

## 状态管理

每个脚本会创建检查点文件：

\`\`\`
.pipeline/
├── extract.done      # 提取完成标记
├── clean.done        # 清洗完成标记
├── transform.done    # 转换完成标记
└── validate.done     # 验证完成标记
\`\`\`

## 错误恢复

如果某步失败：

1. 查看错误日志：`logs/<step>.log`
2. 修复问题
3. 从失败步骤重新开始：`python scripts/<step>.py --resume`

不需要从头运行整个管道。

模式 3：条件参考加载

场景：某些功能仅在特定条件下需要

模式：条件触发器

# DOCX Processing

## 创建文档
[基本创建流程]

## 编辑文档

### 简单编辑
直接修改 XML：
\`\`\`python
# 示例代码
\`\`\`

### 复杂场景

**需要追踪更改？** → 参见 [TRACK-CHANGES.md](references/TRACK-CHANGES.md)  
**需要样式继承？** → 参见 [STYLES.md](references/STYLES.md)  
**需要表格操作？** → 参见 [TABLES.md](references/TABLES.md)

仅在需要时加载相应文档。

质量检查清单

级别 1：基本合规

[ ] name 字段存在且符合命名规范
[ ] description 字段存在且完整
[ ] SKILL.md 文件结构正确
[ ] 引用的文件都存在

级别 2：内容质量

[ ] description 包含"做什么"和"何时使用"
[ ] SKILL.md <500 行（或有充分理由）
[ ] 无重复信息（信息只在一处）
[ ] 使用祈使句/不定式
[ ] 示例优于解释

级别 3：设计优化

[ ] 采用渐进式披露
[ ] 自由度设置恰当
[ ] 脚本已测试可运行
[ ] References 按需加载
[ ] 无冗余上下文

级别 4：用户体验

[ ] 新用户 5 分钟内能上手
[ ] 文档易于扫描
[ ] 错误消息清晰
[ ] 边缘情况有处理
[ ] 有实际使用示例

故障排除

问题 1：Skill 未触发

症状：用户请求相关任务，但 Skill 未被使用

可能原因：

description 太模糊
缺少关键触发词
与其他 Skill 冲突

解决：

# 改进前
description: Process documents.

# 改进后
description: >
  Create, edit, and analyze Word documents (.docx). 
  Use when working with DOCX files for: 
  document creation, content editing, tracked changes, 
  comment management, or text extraction.

问题 2：加载不必要的上下文

症状：Skill 触发后加载大量无关内容

可能原因：

SKILL.md 太长
未使用 references 分离
所有变体混在一起

解决：拆分文件

# 改进前
SKILL.md (8000 行，包含所有框架)

# 改进后
SKILL.md (500 行，导航)
references/
├── react.md (React 细节)
├── vue.md (Vue 细节)
└── angular.md (Angular 细节)

问题 3：脚本执行失败

症状：调用脚本时出错

可能原因：

脚本未测试
依赖未安装
路径问题

解决：

# 添加依赖检查
try:
    from PyPDF2 import PdfReader
except ImportError:
    print("✗ 错误: 请先安装 PyPDF2")
    print("  运行: pip install PyPDF2")
    exit(1)

# 添加路径处理
import os
script_dir = os.path.dirname(os.path.abspath(__file__))
input_path = os.path.join(script_dir, input_file)

返回：📋 概览 | 技能列表