📋 Skill Creator - 技能创建器

自由度	适用场景	示例
高 (文本指令)	多种方法有效、决策依赖上下文	撰写内部沟通
中 (伪代码 + 参数)	存在首选模式、允许一定变化	数据分析流程
低 (具体脚本)	操作脆弱易错、一致性关键	PDF 旋转、文件格式转换

类比：窄桥需要护栏（低自由度），开阔原野允许多条路线（高自由度）。

3. 渐进式披露

Skills 使用三级加载系统高效管理上下文：

级别 1：元数据 (name + description)
       ↓ 始终在上下文中 (~100 词)
       
级别 2：SKILL.md 正文
       ↓ 当 skill 触发时加载 (<5k 词)
       
级别 3：打包资源 (scripts, references, assets)
       ↓ AI 按需加载（无限制）

关键模式：将核心流程保留在 SKILL.md，将变体细节移至单独的参考文件。

Skill 结构

基本结构

skill-name/
├── SKILL.md (必需)
│   ├── YAML 前置元数据 (必需)
│   │   ├── name: (必需)
│   │   └── description: (必需)
│   └── Markdown 指令 (必需)
└── 打包资源 (可选)
    ├── scripts/          - 可执行代码
    ├── references/       - 参考文档
    └── assets/           - 输出用文件

SKILL.md 详解

前置元数据 (YAML)

---
name: pdf-editor
description: 编辑、旋转、合并 PDF 文件。当需要处理 PDF 文件时使用：
  (1) 旋转页面，(2) 合并多个 PDF，(3) 提取页面
---

关键点：

description 是主要触发机制
包含 "做什么" 和 "何时使用"
所有触发信息都在这里（正文只在触发后加载）

正文 (Markdown)

# PDF Editor

## 快速开始

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

## 高级功能

- **表单填充**：参见 [FORMS.md](references/FORMS.md)
- **API 参考**：参见 [REFERENCE.md](references/REFERENCE.md)

打包资源

1. Scripts (`scripts/`)

用途：需要确定性可靠性或重复编写的可执行代码

何时包含：

相同代码被反复重写
需要确定性可靠性

示例：

scripts/
├── rotate_pdf.py      - 旋转 PDF
├── merge_pdfs.py      - 合并多个 PDF
└── extract_pages.py   - 提取特定页面

优势：

Token 高效
确定性执行
可能无需加载到上下文即可执行

2. References (`references/`)

用途：按需加载到上下文以指导 AI 思考的文档

何时包含：

AI 工作时应参考的文档

示例：

references/
├── schema.md          - 数据库架构
├── api_docs.md        - API 规范
├── policies.md        - 公司政策
└── examples.md        - 常见模式

最佳实践：

保持 SKILL.md 精简
仅在 AI 判断需要时加载
大文件 (>10k 词) 在 SKILL.md 中包含 grep 搜索模式

3. Assets (`assets/`)

用途：不加载到上下文，而是在输出中使用的文件

何时包含：

Skill 需要在最终输出中使用的文件

示例：

assets/
├── logo.png           - 品牌资产
├── template.pptx      - PowerPoint 模板
├── boilerplate/       - HTML/React 样板代码
└── fonts/             - 自定义字体

用例：模板、图片、图标、样板代码、字体

6 步创建流程

步骤 1：理解具体示例

目标：通过具体示例清楚了解 skill 的使用方式

问题示例（图像编辑器 skill）：

"这个 skill 应该支持什么功能？"
"能给一些使用示例吗？"
"用户会怎么说来触发这个 skill？"

何时完成：清楚知道 skill 应该支持的功能

步骤 2：规划可复用内容

目标：识别需要哪些脚本、参考文档和资产

分析每个示例：

示例 1：PDF 旋转

问题：旋转 PDF 需要每次重写相同代码
解决：创建 scripts/rotate_pdf.py

示例 2：前端应用构建

问题：每次需要相同的 HTML/React 样板
解决：创建 assets/hello-world/ 模板

示例 3：BigQuery 查询

问题：每次需要重新发现表结构
解决：创建 references/schema.md

步骤 3：初始化 Skill

使用脚本：

scripts/init_skill.py <skill-name> --path <output-directory>

脚本会创建：

Skill 目录
SKILL.md 模板（含前置元数据和 TODO 占位符）
示例资源目录：scripts/、references/、assets/
每个目录中的示例文件

下一步：自定义或删除生成的文件

步骤 4：编辑 Skill

4.1 实现可复用资源

按计划创建：

scripts/ - 测试所有脚本确保无 bug
references/ - 可能需要用户提供文档
assets/ - 可能需要用户提供模板/品牌资产

删除不需要的示例文件

4.2 更新 SKILL.md

前置元数据：

---
name: skill-name
description: >
  做什么 + 何时使用的完整描述。
  包含所有触发场景和用例。
---

正文：

使用祈使句/不定式
核心工作流程和指导
引用打包资源
保持 <500 行

学习设计模式：

多步骤流程 → 参见 references/workflows.md
特定输出格式 → 参见 references/output-patterns.md

步骤 5：打包 Skill

命令：

scripts/package_skill.py <path/to/skill-folder>

脚本会：

验证 skill：
- YAML 格式和必需字段
- 命名约定和目录结构
- 描述完整性和质量
- 文件组织和资源引用
打包 skill（如果验证通过）：
- 创建 .skill 文件（实际是 zip 文件）
- 包含所有文件并保持目录结构

如果验证失败：修复错误并重新运行

步骤 6：迭代

迭代工作流：

在真实任务中使用 skill
注意困难或低效之处
识别 SKILL.md 或资源需要更新的地方
实施更改并再次测试

设计模式速查

模式 1：高级指南 + 参考文档

# PDF Processing

## 快速开始
[代码示例]

## 高级功能
- **表单填充**: 参见 [FORMS.md](FORMS.md)
- **API 参考**: 参见 [REFERENCE.md](REFERENCE.md)

AI 仅在需要时加载 FORMS.md 或 REFERENCE.md。

模式 2：领域特定组织

bigquery-skill/
├── SKILL.md (概览和导航)
└── reference/
    ├── finance.md (财务指标)
    ├── sales.md (销售管道)
    ├── product.md (产品使用)
    └── marketing.md (营销归因)

用户询问销售指标时，AI 只读 sales.md。

模式 3：条件详情

## 创建文档
使用 docx-js。参见 [DOCX-JS.md](DOCX-JS.md)

## 编辑文档
简单编辑直接修改 XML。

**追踪更改**: 参见 [REDLINING.md](REDLINING.md)
**OOXML 详情**: 参见 [OOXML.md](OOXML.md)

AI 仅在用户需要这些功能时读取相应文件。

工作流程模式

顺序工作流

填写 PDF 表单包含这些步骤：

1. 分析表单 (运行 analyze_form.py)
2. 创建字段映射 (编辑 fields.json)
3. 验证映射 (运行 validate_fields.py)
4. 填充表单 (运行 fill_form.py)
5. 验证输出 (运行 verify_output.py)

条件工作流

1. 确定修改类型：
   **创建新内容？** → 遵循 "创建工作流"
   **编辑现有内容？** → 遵循 "编辑工作流"

2. 创建工作流: [步骤]
3. 编辑工作流: [步骤]

输出模式

模板模式

严格要求（API 响应、数据格式）：

## 报告结构

始终使用这个精确的模板结构：

# [分析标题]

## 执行摘要
[一段关键发现概述]

## 主要发现
- 发现 1 + 支持数据
- 发现 2 + 支持数据

灵活指导（允许适应）：

## 报告结构

这是合理的默认格式，但请使用最佳判断：

[结构...]

根据特定分析类型调整部分。

示例模式

## 提交消息格式

遵循这些示例生成提交消息：

**示例 1:**
输入: 添加了 JWT token 用户认证
输出:
\`\`\`
feat(auth): implement JWT-based authentication

Add login endpoint and token validation middleware
\`\`\`

遵循此风格：type(scope): 简要描述，然后详细说明。

避免的陷阱

❌ 不要包含的内容

README.md
INSTALLATION_GUIDE.md
QUICK_REFERENCE.md
CHANGELOG.md
其他辅助文档

原因：Skill 应仅包含 AI 执行任务所需的信息，不包含辅助上下文、设置流程或面向用户的文档。

❌ 常见错误

错误	正确做法
冗长解释	简洁示例
将所有内容放在 SKILL.md	拆分到 references/
深度嵌套引用	保持一级引用
description 太简单	包含所有触发场景
重复信息	信息只存在于一处

常见问题

Q: Skill 应该多大？

SKILL.md: <500 行（保持精简）
References: 无限制（按需加载）
Scripts: 无限制（可能无需加载即执行）

Q: 何时使用 scripts vs references？

Scripts: 确定性代码，重复执行
References: 文档、架构、示例，指导 AI 思考

Q: 如何组织大型 skill？

A: 使用领域特定或变体特定的 references：

skill/
├── SKILL.md (导航)
└── references/
    ├── variant-a.md
    ├── variant-b.md
    └── variant-c.md

关键词

技能创建、AI 扩展、工作流程、领域专业知识、模块化、渐进式披露、上下文管理、可复用资源

下一步：

📖 查看完整指南了解详细创建流程和高级模式
📝 探索 Template Skill 获取基础模板
🎨 参考其他 Skills 学习设计模式

返回: 技能列表