技能创建器
Skill Creator
用于创建有效技能的指南。当用户想要创建新技能（或更新现有技能）以扩展 Claude 的能力时，应使用此技能。
适用平台：
ChatGPTClaudeGemini
---
name: skill-creator
description: 创建有效技能的指南。当用户想要创建新技能（或更新现有技能）以通过专业知识、工作流或工具集成来扩展 Claude 的能力时，应使用此技能。
license: Complete terms in LICENSE.txt
---
# 技能创建器
此技能提供创建有效技能的指导。
## 关于技能
技能是模块化、自包含的软件包，通过提供专业知识、工作流和工具来扩展 Claude 的能力。将它们视为特定领域或任务的“入职指南”——它们将 Claude 从通用代理转变为配备了任何模型都无法完全拥有的程序知识的专业代理。
### 技能提供什么
1. 专业工作流 - 特定领域的多步骤程序
2. 工具集成 - 使用特定文件格式或 API 的说明
3. 领域专业知识 - 公司特定知识、模式、业务逻辑
4. 捆绑资源 - 用于复杂和重复任务的脚本、参考资料和资产
## 核心原则
### 简洁是关键
上下文窗口是一种公共资源。技能与 Claude 所需的一切共享上下文窗口：系统提示、对话历史、其他技能的元数据以及实际用户请求。
**默认假设：Claude 已经非常聪明。** 只添加 Claude 尚未拥有的上下文。挑战每一条信息：“Claude 真的需要这个解释吗？”和“这段话是否值得其令牌成本？”
优先使用简洁的示例，而不是冗长的解释。
### 设置适当的自由度
将具体程度与任务的脆弱性和可变性相匹配：
**高自由度（基于文本的指令）**：当有多种有效方法、决策取决于上下文或启发式方法指导时使用。
**中等自由度（伪代码或带参数的脚本）**：当存在首选模式、允许一些变体或配置影响行为时使用。
**低自由度（特定脚本，少量参数）**：当操作脆弱且容易出错、一致性至关重要或必须遵循特定序列时使用。
把 Claude 想象成在探索一条路径：一座有悬崖的窄桥需要特定的护栏（低自由度），而一片开阔的田野则允许许多路线（高自由度）。
### 技能的构成
每个技能都包含一个必需的 SKILL.md 文件和可选的捆绑资源：
```
skill-name/
├── SKILL.md (必需)
│ ├── YAML frontmatter 元数据 (必需)
│ │ ├── name: (必需)
│ │ └── description: (必需)
│ └── Markdown 指令 (必需)
└── 捆绑资源 (可选)
├── scripts/ - 可执行代码 (Python/Bash/等)
├── references/ - 旨在根据需要加载到上下文中的文档
└── assets/ - 输出中使用的文件 (模板、图标、字体等)
```
#### SKILL.md (必需)
每个 SKILL.md 都包含：
- **Frontmatter** (YAML)：包含 `name` 和 `description` 字段。这些是 Claude 用来确定何时使用技能的唯一字段，因此在描述技能是什么以及何时使用它时，清晰和全面非常重要。
- **Body** (Markdown)：使用技能的说明和指导。仅在技能触发后（如果触发）才加载。
#### 捆绑资源 (可选)
##### 脚本 (`scripts/`)
用于需要确定性可靠性或重复重写的任务的可执行代码（Python/Bash/等）。
- **何时包含**：当相同的代码被重复重写或需要确定性可靠性时
- **示例**：用于 PDF 旋转任务的 `scripts/rotate_pdf.py`
- **优点**：令牌高效，确定性，可以在不加载到上下文中的情况下执行
- **注意**：脚本可能仍然需要 Claude 读取以进行修补或环境特定的调整
##### 参考资料 (`references/`)
旨在根据需要加载到上下文中，以指导 Claude 的流程和思考的文档和参考材料。
- **何时包含**：当 Claude 在工作时需要参考文档时
- **示例**：`references/finance.md` 用于财务模式，`references/mnda.md` 用于公司 NDA 模板，`references/policies.md` 用于公司政策，`references/api_docs.md` 用于 API 规范
- **用例**：数据库模式、API 文档、领域知识、公司政策、详细的工作流指南
- **优点**：保持 SKILL.md 精简，仅在 Claude 确定需要时才加载
- **最佳实践**：如果文件很大（>10k 字），请在 SKILL.md 中包含 grep 搜索模式
- **避免重复**：信息应存在于 SKILL.md 或参考文件中，而不是两者兼有。
##### 资产 (`assets/`)
不打算加载到上下文中，而是用于 Claude 生成的输出中的文件。
- **何时包含**：当技能需要用于最终输出的文件时
- **示例**：`assets/logo.png` 用于品牌资产，`assets/slides.pptx` 用于 PowerPoint 模板
- **用例**：模板、图像、图标、样板代码、字体、示例文档
### 渐进式披露设计原则
技能使用三级加载系统来有效管理上下文：
1. **元数据（名称 + 描述）** - 始终在上下文中（约 100 词）
2. **SKILL.md 正文** - 技能触发时（<5k 词）
3. **捆绑资源** - Claude 按需加载
将 SKILL.md 正文保持在核心内容，并限制在 500 行以内，以最大程度减少上下文膨胀。
## 技能创建过程
技能创建涉及以下步骤：
1. 通过具体示例理解技能
2. 规划可重用技能内容（脚本、参考资料、资产）
3. 初始化技能（运行 init_skill.py）
4. 编辑技能（实现资源并编写 SKILL.md）
5. 打包技能（运行 package_skill.py）
6. 根据实际使用情况进行迭代
### 步骤 3：初始化技能
从头开始创建新技能时，请务必运行 `init_skill.py` 脚本：
```bash
scripts/init_skill.py <skill-name> --path <output-directory>
```
### 步骤 4：编辑技能
根据您的技能需求查阅以下有用指南：
- **多步骤流程**：请参阅 references/workflows.md 了解顺序工作流和条件逻辑
- **特定输出格式或质量标准**：请参阅 references/output-patterns.md 了解模板和示例模式
### 步骤 5：打包技能
```bash
scripts/package_skill.py <path/to/skill-folder>
```
打包脚本会验证并创建一个 .skill 文件以供分发。
FILE:references/workflows.md
# 工作流模式
## 顺序工作流
对于复杂任务，将操作分解为清晰的顺序步骤。在 SKILL.md 的开头向 Claude 概述整个过程通常很有帮助：
```markdown
填写 PDF 表单涉及以下步骤：
1. 分析表单 (运行 analyze_form.py)
2. 创建字段映射 (编辑 fields.json)
3. 验证映射 (运行 validate_fields.py)
4. 填写表单 (运行 fill_form.py)
5. 验证输出 (运行 verify_output.py)
```
## 条件工作流
对于具有分支逻辑的任务，引导 Claude 完成决策点：
```markdown
1. 确定修改类型：
**创建新内容？** → 遵循下面的“创建工作流”
**编辑现有内容？** → 遵循下面的“编辑工作流”
2. 创建工作流：[步骤]
3. 编辑工作流：[步骤]
```
文件：references/output-patterns.md
# 输出模式
当技能需要产生一致、高质量的输出时，请使用这些模式。
## 模板模式
提供输出格式的模板。根据你的需求匹配严格程度。
**对于严格要求（如 API 响应或数据格式）：**
```markdown
## 报告结构
始终使用此精确的模板结构：
# [分析标题]
## 执行摘要
[一段概述关键发现]
## 关键发现
- 发现 1 及支持数据
- 发现 2 及支持数据
- 发现 3 及支持数据
## 建议
1. 具体可操作的建议
2. 具体可操作的建议
```
**对于灵活指导（当适应性有用时）：**
```markdown
## 报告结构
这是一个合理的默认格式，但请自行判断：
# [分析标题]
## 执行摘要
[概述]
## 关键发现
[根据你的发现调整章节]
## 建议
[根据具体上下文量身定制]
根据具体的分析类型，按需调整章节。
```
## 示例模式
对于输出质量取决于查看示例的技能，提供输入/输出对：
```markdown
## 提交消息格式
生成遵循以下示例的提交消息：
**示例 1：**
输入：添加了使用 JWT 令牌的用户认证
输出：
```
feat(auth): 实现基于 JWT 的认证
添加登录端点和令牌验证中间件
```
**示例 2：**
输入：修复了报告中日期显示不正确的错误
输出：
```
fix(reports): 修正时区转换中的日期格式
在报告生成中始终使用 UTC 时间戳
```
遵循此样式：类型(范围): 简要描述，然后是详细解释。
```
示例有助于 Claude 比单独的描述更清楚地理解所需的样式和详细程度。
文件：scripts/quick_validate.py
#!/usr/bin/env python3
"""
技能的快速验证脚本 - 最小版本
"""
import sys
import os
import re
import yaml
from pathlib import Path
def validate_skill(skill_path):
"""技能的基本验证"""
skill_path = Path(skill_path)
# 检查 SKILL.md 是否存在
skill_md = skill_path / 'SKILL.md'
if not skill_md.exists():
return False, "未找到 SKILL.md"
# 读取并验证前置元数据
content = skill_md.read_text()
if not content.startswith('---'):
return False, "未找到 YAML 前置元数据"
# 提取前置元数据
match = re.match(r'^---\n(.*?)\n---', content, re.DOTALL)
if not match:
return False, "前置元数据格式无效"
frontmatter_text = match.group(1)
# 解析 YAML 前置元数据
try:
frontmatter = yaml.safe_load(frontmatter_text)
if not isinstance(frontmatter, dict):
return False, "前置元数据必须是 YAML 字典"
except yaml.YAMLError as e:
return False, f"前置元数据中的 YAML 无效: {e}"
```
# 定义允许的属性
ALLOWED_PROPERTIES = {'name', 'description', 'license', 'allowed-tools', 'metadata'}
# 检查是否存在意外属性（不包括 metadata 下的嵌套键）
unexpected_keys = set(frontmatter.keys()) - ALLOWED_PROPERTIES
if unexpected_keys:
return False, (
f"SKILL.md frontmatter 中存在意外的键：{', '.join(sorted(unexpected_keys))}。 "
f"允许的属性有：{', '.join(sorted(ALLOWED_PROPERTIES))}"
)
# 检查必填字段
if 'name' not in frontmatter:
return False, "frontmatter 中缺少 'name'"
if 'description' not in frontmatter:
return False, "frontmatter 中缺少 'description'"
# 提取名称进行验证
name = frontmatter.get('name', '')
if not isinstance(name, str):
return False, f"名称必须是字符串，得到的是 {type(name).__name__}"
name = name.strip()
if name:
# 检查命名约定（连字符命名法：小写字母加连字符）
if not re.match(r'^[a-z0-9-]+$', name):
return False, f"名称 '{name}' 应该采用连字符命名法（只包含小写字母、数字和连字符）"
if name.startswith('-') or name.endswith('-') or '--' in name:
return False, f"名称 '{name}' 不能以连字符开头/结尾或包含连续的连字符"
# 检查名称长度（根据规范，最大 64 个字符）
if len(name) > 64:
return False, f"名称过长（{len(name)} 个字符）。最大长度为 64 个字符。"
# 提取并验证描述
description = frontmatter.get('description', '')
if not isinstance(description, str):
return False, f"描述必须是字符串，得到的是 {type(description).__name__}"
description = description.strip()
if description:
# 检查尖括号
if '<' in description or '>' in description:
return False, "描述不能包含尖括号（< 或 >）"
# 检查描述长度（根据规范，最大1024个字符）
if len(description) > 1024:
return False, f"描述过长（{len(description)} 个字符）。最大长度为1024个字符。"
return True, "技能有效！"
if __name__ == "__main__":
if len(sys.argv) != 2:
print("用法: python quick_validate.py <技能目录>")
sys.exit(1)
valid, message = validate_skill(sys.argv[1])
print(message)
sys.exit(0 if valid else 1)
文件:scripts/init_skill.py
#!/usr/bin/env python3
"""
技能初始化器 - 从模板创建新技能
用法:
init_skill.py <技能名称> --path <路径>
示例:
init_skill.py my-new-skill --path skills/public
init_skill.py my-api-helper --path skills/private
init_skill.py custom-skill --path /custom/location
"""
import sys
from pathlib import Path
SKILL_TEMPLATE = """---
name: {skill_name}
description: [TODO: 完整且信息丰富的解释，说明该技能的作用以及何时使用。包括何时使用此技能 - 触发它的特定场景、文件类型或任务。]
---
# {skill_title}
## 概述
[TODO: 1-2句话解释此技能的作用]
## 资源
此技能包含示例资源目录，演示如何组织不同类型的捆绑资源：
"""
### scripts/
可直接运行以执行特定操作的可执行代码（Python/Bash 等）。
### references/
旨在加载到上下文中以指导 Claude 流程和思维的文档和参考资料。
### assets/
不打算加载到上下文中，而是用于 Claude 生成的输出中的文件。
---
**任何不需要的目录都可以删除。**并非每个技能都需要所有三种类型的资源。
"""
EXAMPLE_SCRIPT = '''#!/usr/bin/env python3
"""
{skill_name} 的示例辅助脚本
这是一个可以直接执行的占位符脚本。
请替换为实际实现或在不需要时删除。
"""
def main():
print("这是 {skill_name} 的示例脚本")
# TODO: 在此处添加实际的脚本逻辑
if __name__ == "__main__":
main()
'''
EXAMPLE_REFERENCE = """# {skill_title} 的参考文档
这是详细参考文档的占位符。
请替换为实际的参考内容或在不需要时删除。
"""
EXAMPLE_ASSET = """# 示例资产文件
此占位符表示资产文件将存储在此处。
请替换为实际的资产文件（模板、图像、字体等）或在不需要时删除。
"""
def title_case_skill_name(skill_name):
"""将带连字符的技能名称转换为标题大小写以供显示。"""
return ' '.join(word.capitalize() for word in skill_name.split('-'))
def init_skill(skill_name, path):
"""使用模板 SKILL.md 初始化新的技能目录。"""
skill_dir = Path(path).resolve() / skill_name
if skill_dir.exists():
print(f"❌ 错误：技能目录已存在：{skill_dir}")
return None
try:
skill_dir.mkdir(parents=True, exist_ok=False)
print(f"✅ 已创建技能目录: {skill_dir}")
except Exception as e:
print(f"❌ 创建目录时出错: {e}")
return None
skill_title = title_case_skill_name(skill_name)
skill_content = SKILL_TEMPLATE.format(skill_name=skill_name, skill_title=skill_title)
skill_md_path = skill_dir / 'SKILL.md'
try:
skill_md_path.write_text(skill_content)
print("✅ 已创建 SKILL.md")
except Exception as e:
print(f"❌ 创建 SKILL.md 时出错: {e}")
return None
try:
scripts_dir = skill_dir / 'scripts'
scripts_dir.mkdir(exist_ok=True)
example_script = scripts_dir / 'example.py'
example_script.write_text(EXAMPLE_SCRIPT.format(skill_name=skill_name))
example_script.chmod(0o755)
print("✅ 已创建 scripts/example.py")
references_dir = skill_dir / 'references'
references_dir.mkdir(exist_ok=True)
example_reference = references_dir / 'api_reference.md'
example_reference.write_text(EXAMPLE_REFERENCE.format(skill_title=skill_title))
print("✅ 已创建 references/api_reference.md")
assets_dir = skill_dir / 'assets'
assets_dir.mkdir(exist_ok=True)
example_asset = assets_dir / 'example_asset.txt'
example_asset.write_text(EXAMPLE_ASSET)
print("✅ 已创建 assets/example_asset.txt")
except Exception as e:
print(f"❌ 创建资源目录时出错: {e}")
return None
print(f"\n✅ 技能 '{skill_name}' 已在 {skill_dir} 成功初始化")
return skill_dir
def main():
if len(sys.argv) < 4 or sys.argv[2] != '--path':
print("用法: init_skill.py <技能名称> --path <路径>")
sys.exit(1)
skill_name = sys.argv[1]
path = sys.argv[3]
print(f"🚀 初始化技能: {skill_name}")
print(f" 位置: {path}")
print()
result = init_skill(skill_name, path)
sys.exit(0 if result else 1)
if __name__ == "__main__":
main()
文件:scripts/package_skill.py
#!/usr/bin/env python3
"""
技能打包器 - 将技能文件夹创建为可分发的 .skill 文件
用法:
python utils/package_skill.py <技能文件夹路径> [输出目录]
示例:
python utils/package_skill.py skills/public/my-skill
python utils/package_skill.py skills/public/my-skill ./dist
"""
import sys
import zipfile
from pathlib import Path
from quick_validate import validate_skill
def package_skill(skill_path, output_dir=None):
"""将技能文件夹打包成 .skill 文件。"""
skill_path = Path(skill_path).resolve()
if not skill_path.exists():
print(f"❌ 错误: 未找到技能文件夹: {skill_path}")
return None
if not skill_path.is_dir():
print(f"❌ 错误: 路径不是目录: {skill_path}")
return None
skill_md = skill_path / "SKILL.md"
if not skill_md.exists():
print(f"❌ 错误: 在 {skill_path} 中未找到 SKILL.md")
return None
print("🔍 正在验证技能...")
valid, message = validate_skill(skill_path)
if not valid:
print(f"❌ 验证失败: {message}")
print(" 请在打包前修复验证错误。")
return None
print(f"✅ {message}\n")
skill_name = skill_path.name
if output_dir:
output_path = Path(output_dir).resolve()
output_path.mkdir(parents=True, exist_ok=True)
else:
output_path = Path.cwd()
skill_filename = output_path / f"{skill_name}.skill"
try:
with zipfile.ZipFile(skill_filename, 'w', zipfile.ZIP_DEFLATED) as zipf:
for file_path in skill_path.rglob('*'):
if file_path.is_file():
arcname = file_path.relative_to(skill_path.parent)
zipf.write(file_path, arcname)
print(f" 已添加: {arcname}")
print(f"\n✅ 技能已成功打包至: {skill_filename}")
return skill_filename
except Exception as e:
print(f"❌ 创建 .skill 文件时出错: {e}")
return None
def main():
if len(sys.argv) < 2:
print("用法: python utils/package_skill.py <path/to/skill-folder> [output-directory]")
sys.exit(1)
skill_path = sys.argv[1]
output_dir = sys.argv[2] if len(sys.argv) > 2 else None
print(f"📦 正在打包技能: {skill_path}")
if output_dir:
print(f" 输出目录: {output_dir}")
print()
result = package_skill(skill_path, output_dir)
sys.exit(0 if result else 1)
if __name__ == "__main__":
main()