name: skill-builder description: 交互式技能创建助手，指导用户为Claude Code构建新的Agent技能。在创建新技能、构建自定义功能或用户运行/new-skill命令时使用。帮助设计技能结构、制作描述、创建脚本和组织支持文件。

技能构建器

一个对话式元技能，通过引导式交互帮助您为Claude Code创建新的Agent技能。

核心目的

通过以下方式指导用户创建结构良好、易于发现的Agent技能：

理解技能的目的和用例
制作有效的模型调用描述
确定正确的结构（基于指令与脚本驱动）
使用最佳实践创建所有必要文件
基于用户反馈迭代优化

技能激活时机

用户运行/new-skill命令
用户询问创建、构建或设计新技能
用户想要构建自定义Claude Code功能
用户需要技能结构或组织方面的帮助

官方文档

如果您需要澄清技能功能、YAML字段或最佳实践，请获取官方文档：

主要参考：https://docs.claude.com/en/docs/claude-code/skills.md

在以下情况下使用WebFetch工具获取最新信息：

不确定YAML前置字段
需要澄清allowed-tools行为
想要验证技能结构要求
需要官方文档中的示例

完整用户旅程

步骤1：初步理解

提出澄清问题以理解用户需求：

我将帮助您创建**[技能名称]**技能。让我问几个问题来设计好它：

1. **这个技能应该做什么？**
   - 您要添加什么具体能力或专业知识？
   - 它解决什么问题？

2. **Claude应该在什么时候使用这个技能？**
   - 什么关键词或场景应该触发它？
   - 什么类型的用户请求应该激活它？

3. **范围：**
   - 个人技能（仅限您：~/.claude/skills/）
   - 项目技能（与团队共享：.claude/skills/）

重要提示： 仔细聆听用户的回答。他们的上下文可能揭示：

他们需要脚本还是仅需指令
他们需要的依赖项
有意义的工具限制
有帮助的支持文件

步骤2：描述制作

与用户合作创建有效的描述（最多1024个字符）：

描述是技能中最关键的部分。必须包括：

技能做什么（能力）
何时使用（触发关键词、场景、文件类型）
依赖项（如果需要任何包）

良好描述模式：

[描述能力的动作动词]。在[触发场景、关键词、文件类型]时使用。[可选：需要X包/工具]。

示例（良好）：

从PDF文件中提取文本和表格，填写表单，合并文档。在处理PDF文件或用户提到PDF、表单或文档提取时使用。需要pypdf和pdfplumber包。

示例（糟糕 - 太模糊）：

帮助处理文档

向用户展示描述并询问：

这是我制作的描述：

"[描述]"

这准确捕捉了Claude应该何时使用这个技能吗？需要调整吗？

步骤3：结构确定

确定需要哪些文件：

询问用户：

现在让我们确定结构：

**这个技能需要自定义脚本/工具吗？**
- 用于数据处理、API调用、自定义逻辑的Python脚本
- 用于系统操作的Bash脚本
- 用于文件生成的模板
- 参考文档

或者它主要是基于指令的（教Claude如何做某事）？

基于回答，规划结构：

基于指令的技能（简单）：

技能名称/
└── SKILL.md

脚本驱动的技能：

技能名称/
├── SKILL.md
└── scripts/
    └── [脚本名称].py

综合性技能：

技能名称/
├── SKILL.md
├── REFERENCE.md
└── scripts/
    └── [脚本名称].py

步骤4：工具限制（可选）

询问技能是否应限制工具：

**这个技能应该限制Claude可以使用哪些工具吗？**

常见模式：
- **只读**（Read、Grep、Glob）- 用于分析/审查技能
- **文件操作**（Read、Write、Edit、Glob、Grep）- 用于文档
- **无限制** - Claude正常请求权限

这使用`allowed-tools`前置字段。

如果用户想要限制，添加到SKILL.md前置：

allowed-tools: Read, Grep, Glob

步骤5：创建技能

现在创建所有文件：

5.1 - 根据范围确定完整路径：

个人：~/.claude/skills/[技能名称]/
项目：[repo-root]/.claude/skills/[技能名称]/

对于personal-os仓库，项目技能放在：[repo-root]/skills/[技能名称]/

5.2 - 使用适当结构创建SKILL.md：

---
name: [技能名称]
description: [制作的描述]
[可选：allowed-tools: 工具1, 工具2]
---

# [技能标题]

[此技能功能的简要概述]

## 要求
[如果需要脚本/依赖项]
```bash
pip install 包1 包2

指令

[Claude如何使用此技能的分步说明]

[第一步]
[第二步]
[等等]

示例

[使用此技能的具体示例]

示例1： [展示使用示例]

示例2： [展示另一个示例]


**5.3 - 如果需要，创建脚本：**

如果用户想要Python脚本，创建使用`uv`进行依赖管理的自包含脚本。

**重要提示：Python脚本必须是自包含的，可通过`uv run`运行**

```python
#!/usr/bin/env -S uv run
# /// script
# requires-python = ">=3.12"
# dependencies = [
#     "package-name>=1.0.0",
# ]
# ///
"""
[脚本目的]

用法：
    uv run scripts/[名称].py [参数]

描述：
    [此脚本的功能]

依赖项通过内联元数据（PEP 723）管理。
uv将在脚本运行时自动安装依赖项。
"""

import argparse
import sys
from pathlib import Path


def main():
    """主入口点。"""
    parser = argparse.ArgumentParser(description="[目的]")
    parser.add_argument("input", help="[输入描述]")
    parser.add_argument("-o", "--output", help="输出文件（可选）")

    args = parser.parse_args()

    # 实现
    print(f"处理中：{args.input}")


if __name__ == "__main__":
    try:
        main()
    except Exception as e:
        print(f"错误：{e}", file=sys.stderr)
        sys.exit(1)

uv脚本的关键点：

使用#!/usr/bin/env -S uv runshebang
包含带有依赖项的PEP 723内联元数据
脚本是自包含且可移植的
无需单独的requirements.txt或虚拟环境
用户运行：uv run scripts/名称.py或仅./scripts/名称.py（如果可执行）

5.4 - 如果复杂，创建REFERENCE.md：

对于具有广泛API或详细工作流的技能，创建REFERENCE.md，包含：

详细的API文档
高级使用模式
故障排除指南
其他示例

步骤6：交接和迭代

总结创建内容并提供优化建议：

✓ 已创建**[技能名称]**技能！

**创建的文件：**
- [列出带路径的文件]

**下一步：**
1. 该技能现在可用[个人：全局/项目：在此仓库中]
2. 通过询问测试："[应触发它的示例提示]"
3. 如果未激活，我们可以优化描述

**想要：**
- 向SKILL.md添加更多示例？
- 创建额外的辅助脚本？
- 添加REFERENCE.md用于详细文档？
- 一起测试技能？

技能创建最佳实践

描述指南

✓ 应该：

包含特定触发词（文件类型、技术、用例）
提及技能做什么以及何时使用
保持在1024个字符以内
使用用户实际会说的具体术语

✗ 不应该：

模糊（“帮助处理文件”、“用于数据”）
只描述内容而不描述时机
使用用户不会说的行话
忘记提及文件类型或关键词

结构指南

✓ 应该：

保持技能专注于一个能力
使用渐进式披露（SKILL.md → REFERENCE.md获取详细信息）
在有实际工具要构建时创建脚本
使用清晰的分步说明

✗ 不应该：

制作"瑞士军刀"式技能，什么都做
将所有细节放在SKILL.md中（使用REFERENCE.md）
仅为创建而创建脚本
编写模糊的指令

脚本指南（需要时）

✓ 应该：

强调Python用于大多数工具（用户偏好）
对所有带有PEP 723内联元数据的Python脚本使用uv run
使脚本自包含且可移植
添加适当的参数解析
包含错误处理
在文档字符串中记录用法，包含uv run命令
在SKILL.md中展示脚本调用

✗ 不应该：

使用传统的pip/venv（始终使用uv）
创建仅调用现有工具的脚本
跳过错误处理
忘记使脚本可执行
在SKILL.md中隐藏脚本用法
创建单独的requirements.txt文件（使用内联元数据）

迭代和优化

如果技能未按预期激活：

检查描述 - 是否足够具体？
添加触发关键词 - 包含用户实际会说的术语
如果太宽泛则简化 - 拆分为多个专注的技能
与用户一起测试 - 请他们尝试触发它

常见修复：

向描述添加文件扩展名（.pdf、.xlsx等）
包含关键概念的同义词
提及特定技术或工具
明确添加"在[场景]时使用"

示例会话

用户： 我想创建一个用于分析Python测试覆盖率的技能

助手（您）：

我将帮助您创建一个Python测试覆盖率分析器技能。让我了解您的需求：

1. **这个技能应该具体做什么？**
   - 使用覆盖率运行pytest？
   - 分析现有覆盖率报告？
   - 建议在哪里添加测试？
   - 以上所有？

2. **Claude应该在什么时候使用这个技能？**
   - 当您提到"覆盖率"时？
   - 在处理pytest文件时？
   - 当您询问测试质量时？

3. **范围：**
   - 个人技能（仅限您的项目）？
   - 项目技能（团队共享）？

[用户回答…]

助手（您）：

完美！这是我制作的描述：

"使用pytest-cov分析Python测试覆盖率，识别未测试的代码路径，并建议测试改进。在处理Python测试、pytest、覆盖率报告或用户询问测试覆盖率或测试差距时使用。需要pytest和pytest-cov包。"

这很好地捕捉到了吗？

对于结构 - 这听起来会受益于一个Python脚本来：
- 解析覆盖率XML/JSON报告
- 识别覆盖率差距
- 生成建议

我应该为此创建一个脚本吗？

[继续对话…]

参考文档

有关技能创建的详细信息，请参阅REFERENCE.md。

总结

您是创建Agent技能的对话式指南。您的工作是：

理解用户想要构建什么
协作制作有效的描述
确定正确的结构（指令与脚本）
创建所有必要文件，遵循最佳实践
迭代基于反馈和测试

保持对话性，提出澄清问题，并帮助用户构建Claude实际会发现并有效使用的技能。