Meta提示词

---
name: skill-creator
description: 创建有效技能的指南。当用户想要创建新技能（或更新现有技能）以通过专业知识、工作流或工具集成扩展 Claude 的能力时，应使用此技能。
license: 完整条款见 LICENSE.txt
---

# 技能创建器

此技能为创建有效技能提供指导。

## 关于技能

技能是模块化、自包含的包，通过提供专业知识、工作流和工具来扩展 Claude 的能力。可以将它们视为特定领域或任务的“入门指南”——它们将 Claude 从通用代理转变为具备任何模型都无法完全拥有的程序性知识的专业代理。

### 技能提供的内容

1. 专业工作流 - 针对特定领域的多步骤流程
2. 工具集成 - 使用特定文件格式或 API 的说明
3. 领域专业知识 - 公司特定知识、模式、业务逻辑
4. 捆绑资源 - 用于复杂和重复任务的脚本、参考资料和资产

## 核心原则

### 简洁是关键

上下文窗口是一种公共资源。技能与 Claude 所需的其他所有内容共享上下文窗口：系统提示、对话历史、其他技能的元数据以及实际用户请求。

**默认假设：Claude 已经非常聪明。** 只添加 Claude 尚未拥有的上下文。对每条信息提出质疑：“Claude 真的需要这个解释吗？”以及“这段文字是否值得其 token 成本？”

优先使用简洁的示例而非冗长的解释。

### 设置适当的自由度

将具体程度与任务的脆弱性和可变性相匹配：

**高自由度（基于文本的指令）**：当多种方法都有效、决策取决于上下文或启发式方法指导方法时使用。

**中等自由度（伪代码或带参数的脚本）**：当存在首选模式、某些变化可接受或配置影响行为时使用。

**低自由度（特定脚本、少量参数）**：当操作脆弱且容易出错、一致性至关重要或必须遵循特定顺序时使用。

将 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 用来确定技能何时被使用的唯一字段，因此清晰全面地描述技能是什么以及何时应使用它非常重要。
- **正文** (Markdown)：使用技能的说明和指导。仅在技能触发后加载（如果有的话）。

#### 捆绑资源 (可选)

##### 脚本 (`scripts/`)

用于需要确定性可靠性或反复重写的任务的可执行代码 (Python/Bash 等)。

- **何时包含**：当同一代码被反复重写或需要确定性可靠性时
- **示例**：`scripts/rotate_pdf.py` 用于 PDF 旋转任务
- **优点**：token 高效、确定性、无需加载到上下文中即可执行
- **注意**：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 或 references 文件中，而不是两者中。

##### 资产 (`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. 编辑工作流：[步骤]
```
FILE:references/output-patterns.md
# 输出模式

当技能需要产生一致、高质量的输出时，使用这些模式。

## 模板模式

为输出格式提供模板。根据你的需求匹配严格程度。

**对于严格要求（如 API 响应或数据格式）：**

```markdown
## 报告结构

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

# [分析标题]

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

## 关键发现
- 发现 1 及支持数据
- 发现 2 及支持数据
- 发现 3 及支持数据

## 建议
1. 具体的可操作建议
2. 具体的可操作建议
```

**对于灵活指导（当适应有用时）：**

```markdown
## 报告结构

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

# [分析标题]

## 执行摘要
[概述]

## 关键发现
[根据你的发现调整章节]

## 建议
[针对具体上下文定制]

根据需要为特定分析类型调整章节。
```

## 示例模式

对于输出质量取决于查看示例的技能，提供输入/输出对：

```markdown
## 提交信息格式

按照这些示例生成提交信息：

**示例 1：**
输入：使用 JWT 令牌添加了用户身份验证
输出：
```
feat(auth): 实现基于 JWT 的身份验证

添加登录端点和令牌验证中间件
```

**示例 2：**
输入：修复了报告中日期显示不正确的错误
输出：
```
fix(reports): 修正时区转换中的日期格式

在报告生成中一致使用 UTC 时间戳
```

遵循此风格：类型(范围): 简要描述，然后详细说明。
```

示例比仅描述更能帮助 Claude 理解所需的风格和详细程度。
FILE: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"

    # 读取并验证 frontmatter
    content = skill_md.read_text()
    if not content.startswith('---'):
        return False, "未找到 YAML frontmatter"

    # 提取 frontmatter
    match = re.match(r'^---\n(.*?)\n---', content, re.DOTALL)
    if not match:
        return False, "无效的 frontmatter 格式"

    frontmatter_text = match.group(1)

    # 解析 YAML frontmatter
    try:
        frontmatter = yaml.safe_load(frontmatter_text)
        if not isinstance(frontmatter, dict):
            return False, "Frontmatter 必须是 YAML 字典"
    except yaml.YAMLError as e:
        return False, f"Frontmatter 中的 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 <skill_directory>")
        sys.exit(1)
    
    valid, message = validate_skill(sys.argv[1])
    print(message)
    sys.exit(0 if valid else 1)
FILE:scripts/init_skill.py
#!/usr/bin/env python3
"""
技能初始化器 - 从模板创建新技能

用法：
    init_skill.py <skill-name> --path <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 <skill-name> --path <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()
FILE:scripts/package_skill.py
#!/usr/bin/env python3
"""
技能打包器 - 为技能文件夹创建可分发的 .skill 文件

用法：
    python utils/package_skill.py <path/to/skill-folder> [output-directory]

示例：
    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()