chatgpt-on-wechat/skills/skill-creator/USAGE_GUIDE.md

# Skill Creator 使用指南（修订版）

## 🎯 什么是 skill-creator？

**skill-creator 是一个 Skill（技能），而不是 Tool（工具）**

- 它教 Agent 如何使用现有工具（bash, read, write, edit）来创建新技能
- 它提供了完整的技能创建工作流指导
- Agent 会组合使用多个工具来完成技能创建任务

## 📚 Skills vs Tools

| 类型 | 说明 | 示例 |
|------|------|------|
| **Tool（工具）** | 底层能力，执行单一操作 | bash, read, write, calculator |
| **Skill（技能）** | 工作流指导，组合多个工具 | skill-creator, code-reviewer |

## 🚀 如何使用

### 触发条件

当用户提到以下关键词时，skill-creator 技能会被触发：
- "创建技能"
- "新建 skill"
- "创建一个新技能"
- "initialize a skill"

### 完整示例

```
用户: "创建一个新技能叫 weather-api"

Agent 执行流程:
1. 加载 skill-creator 技能
2. 阅读 SKILL.md 了解工作流
3. 使用 bash 工具:
   cd skills/skill-creator && python3 scripts/init_skill.py weather-api --path ../../workspace/skills
4. 报告成功 ✅

用户: "完善这个技能，用于调用天气 API 获取天气数据"

Agent 执行流程:
1. 使用 read 工具读取 workspace/skills/weather-api/SKILL.md
2. 使用 edit 工具修改 description 和内容
3. 报告完成 ✅

用户: "验证这个技能"

Agent 执行流程:
1. 使用 bash 工具:
   cd skills/skill-creator && python3 scripts/quick_validate.py ../../workspace/skills/weather-api
2. 报告验证结果 ✅

用户: "打包这个技能"

Agent 执行流程:
1. 使用 bash 工具:
   cd skills/skill-creator && python3 scripts/package_skill.py ../../workspace/skills/weather-api
2. 生成 weather-api.skill 文件 ✅
```

## 🔄 工作流程

### 1. 创建技能模板
```
说法: "创建新技能 desktop-viewer"
Agent: 运行 init_skill.py 脚本
结果: workspace/skills/desktop-viewer/ 目录创建
```

### 2. 编辑技能内容
```
说法: "完善 SKILL.md 的描述"
Agent: 使用 write/edit 工具修改
结果: SKILL.md 更新
```

### 3. 添加资源文件（可选）
```
说法: "在 scripts 目录创建 xxx.py"
Agent: 使用 write 工具创建文件
结果: 脚本文件创建
```

### 4. 验证技能
```
说法: "验证 desktop-viewer 技能"
Agent: 运行 quick_validate.py 脚本
结果: 显示验证结果
```

### 5. 打包技能
```
说法: "打包 desktop-viewer 技能"
Agent: 运行 package_skill.py 脚本
结果: desktop-viewer.skill 文件生成
```

## ✅ 推荐的提问方式

### 创建技能
✅ "创建一个新技能叫 XXX"
✅ "初始化技能 XXX"
✅ "新建 skill: XXX"

### 编辑技能
✅ "完善 XXX 技能的描述"
✅ "在 XXX 技能的 scripts 目录创建文件"
✅ "修改 XXX 技能的 SKILL.md"

### 验证技能
✅ "验证 XXX 技能"
✅ "检查 XXX 技能的格式"

### 打包技能
✅ "打包 XXX 技能"
✅ "导出 XXX skill"

## ❌ 避免的说法

❌ "帮我写一个查看桌面文件的功能"
- 问题：太具体，Agent 会直接写代码而不是创建技能

❌ "做一个脚本来..."
- 问题：Agent 会直接写脚本而不是创建技能

✅ **正确方式**：
1. 先说："创建技能 desktop-viewer"
2. 再说："这个技能用于查看桌面文件"

## 🔍 如何确认技能已加载？

查看 Agent 启动日志：
```
[INFO] Loaded X skills from all sources
[INFO] SkillManager: Loaded X skills
```

或者直接问：
```
"列出所有已加载的 skills"
```

## 📂 技能存放位置

- **创建的新技能**: `workspace/skills/<skill-name>/`
- **skill-creator 本身**: `skills/skill-creator/`
- **打包后的文件**: 项目根目录下的 `<skill-name>.skill`

## 💡 实用技巧

### 1. 分步操作
不要一次性说太多，分步骤进行：
```
步骤 1: "创建技能 pdf-processor"
步骤 2: "添加描述：用于处理 PDF 文件"
步骤 3: "创建脚本 extract_text.py"
步骤 4: "验证技能"
步骤 5: "打包技能"
```

### 2. 明确技能名称
使用 hyphen-case 格式：
✅ weather-api
✅ pdf-processor
✅ file-manager

❌ weather api（有空格）
❌ WeatherAPI（驼峰）
❌ weather_api（下划线）

### 3. 查看创建的文件
```
"列出 workspace/skills/XXX 目录的内容"
"读取 workspace/skills/XXX/SKILL.md"
```

## 🛠️ 直接运行脚本（备选）

如果需要直接运行脚本：

```bash
# 创建技能
cd skills/skill-creator
python3 scripts/init_skill.py my-skill --path ../../workspace/skills

# 验证技能
python3 scripts/quick_validate.py ../../workspace/skills/my-skill

# 打包技能
python3 scripts/package_skill.py ../../workspace/skills/my-skill
```

## 📖 技能开发流程

```
1. 规划 → 确定技能功能
2. 创建 → 使用 init_skill.py 生成模板
3. 编辑 → 完善 SKILL.md 和资源文件
4. 验证 → 使用 quick_validate.py 检查格式
5. 测试 → 在 Agent 中加载并测试
6. 打包 → 使用 package_skill.py 生成 .skill 文件
7. 分享 → 将 .skill 文件分享给其他用户
```

## ❓ 常见问题

### Q: Agent 没有使用 skill-creator？
**A**: 
1. 确认技能已加载（查看日志）
2. 使用明确的触发词："创建技能 XXX"
3. 不要在一句话中混入太多其他信息

### Q: 技能创建在哪里？
**A**: `workspace/skills/<技能名>/`

### Q: .skill 文件是什么？
**A**: 是 zip 格式的压缩包，包含技能的所有文件，可以分享和安装

### Q: 如何安装别人的 .skill 文件？
**A**: 解压到 `workspace/skills/` 目录

### Q: skill-creator 本身也是技能吗？
**A**: 是的！它是一个教 Agent 如何创建其他技能的技能

---

**记住**: skill-creator 是一个 **Skill（指导方案）**，而不是 **Tool（工具）**！