agent-skill-builder

Agent Skill Builder

快速搭建新的 Claude Code 技能，或将 ChatGPT 项目转换为 Claude Code 格式。此技能专注于快速创建和正确构建。对于迭代测试、基准测试和描述优化，请使用 Anthropic 官方的 skill-creator 插件。

两种模式

模式 1：创建新技能（/agent-skill-builder new [name]）

搭建全新的 Claude Code 技能，并采用恰当的结构和最佳实践。

模式 2：转换 ChatGPT 项目（/agent-skill-builder translate [name]）

将现有的 ChatGPT 项目转换为 Claude Code 技能。

---

创建新技能

步骤 1：了解意图

询问用户（上下文中已明确的内容可跳过）：

1. 技能名称：/slash-command 应该叫什么？
2. 用途：此技能能做什么？
3. 示例：实际使用此技能的方式有哪些？
4. 触发条件：用户说什么时应该调用此技能？

步骤 2：规划资源

分析每个示例，确定应包含哪些内容：

• 脚本（scripts/）：需要反复重写的代码，或需要确定性可靠性的代码。执行时不会加载到上下文中。
• 参考资料（references/）：Claude 工作时应查阅的文档。按需加载。
• 资源文件（assets/）：用于输出的文件（模板、图片、字体）。不会加载到上下文中。

步骤 3：创建目录和 SKILL.md

mkdir -p ~/.claude/skills/[skill-name]

按照此模板编写 SKILL.md：

---
name: skill-name
description: "Describes what the skill does and specific triggers for when to use it. Write in third person. Include keywords users would say. Max 1024 characters. This is the PRIMARY triggering mechanism."
---

# Skill Name

[1-2 sentence description]

## Instructions

[Step-by-step guidance — use imperative form]

## Output Format

[Expected output structure]

## Constraints

[Limitations and rules]

步骤 4：添加参考文件（如有需要）

对于包含多个领域或变体的技能，请保持 SKILL.md 精简，并将内容拆分到参考资料中：

skill-name/
├── SKILL.md (overview + navigation, under 500 lines)
└── references/
    ├── variant-a.md
    └── variant-b.md

在 SKILL.md 中清楚说明何时阅读每个文件。参考资料的嵌套层级保持为一层。

步骤 5：测试

1. 直接调用：/skill-name
2. 让 Claude 根据描述关键词自动调用
3. 检查技能是否在预期情况下触发，并在不相关时保持静默

---

将 ChatGPT 项目转换为 Claude 技能

步骤 1：提取 ChatGPT 组件

向用户索取：

• 系统提示词/指令
• 知识文件（PDF、文档）
• 对话开场白（可选）
• Actions/API 配置（如有）

步骤 2：映射组件

ChatGPT 组件	Claude Code 对应项	位置
名称	frontmatter 中的 name	SKILL.md
描述	frontmatter 中的 description	SKILL.md
指令	Markdown 正文	SKILL.md
知识文件	references/ 文件夹（转换为 .md）	子目录
对话开场白	记录在“示例”部分，或省略	SKILL.md
Actions（API）	MCP 服务	~/.claude/mcp.json
Code Interpreter	原生工具：Bash、Read、Write、Edit、Glob、Grep	内置
记忆	没有直接对应项。使用上下文文件或技能背景部分	多处

步骤 3：转换指令

ChatGPT 模式	Claude 对应项
“你是一名[角色]……”	角色部分，或整合到指令中
“你的任务是……”	指令部分
“始终/绝不……”	约束部分
“输出格式……”	输出格式部分
输入占位符 [text]	保持原样，或使用 $ARGUMENTS

步骤 4：转换知识文件

1. 将 PDF/文档转换为 Markdown，并放入 references/
2. 对于大型文件（>10k 词），在 SKILL.md 中加入 grep 搜索模式
3. 对于超过 100 行的文件，在顶部添加目录
4. 模板和资源文件放入 assets/

步骤 5：编写 Frontmatter

description 字段是主要的触发机制。使用第三人称撰写，并同时说明技能的功能和适用场景。触发条件可以稍微写得“积极”一些，以避免触发不足。

---

Frontmatter 参考

仅 name 和 description 为必填项。其他字段是 Claude Code 专属扩展：

字段	必填	说明
name	是	最多 64 个字符，只能包含小写字母、数字和连字符
description	是	最多 1024 个字符。说明做什么以及何时使用。使用第三人称。主要触发机制
argument-hint	否	在自动补全中显示的提示（例如 "[issue-number]"）
disable-model-invocation	否	true = 仅由用户调用（不会自动触发）
user-invocable	否	false = 仅限 Claude（在斜杠命令菜单中隐藏）
context	否	fork = 在隔离的子 Agent 中运行
agent	否	子 Agent 类型：Explore、Plan、general-purpose
allowed-tools	否	限制可用工具：Read, Grep, Glob
model	否	覆盖此技能使用的模型

字符串替换

变量	说明
$ARGUMENTS	/skill-name 之后的所有内容
${CLAUDE_SESSION_ID}	当前会话 ID
!`command`	动态注入（在技能加载前运行）

技能位置

位置	路径	范围
个人	~/.claude/skills/[name]/	所有项目
项目	.claude/skills/[name]/	仅此项目

编写最佳实践

这些建议来自 Anthropic 官方技能编写指南：

• 简洁是关键。 Claude 已经很聪明。只补充 Claude 尚不了解的上下文。优先使用简洁示例，而非冗长说明。
• 描述至关重要。 Claude 会根据描述，从可能超过 100 个可用技能中决定使用哪个技能。描述要具体，包含触发关键词，并使用第三人称。
• 渐进式披露。 将 SKILL.md 控制在 500 行以内。把详细参考内容移到单独的文件中。Claude 只会在需要时加载它们。
• 让自由度与脆弱性相匹配。 对灵活任务给予较高自由度（文本指令），对脆弱操作给予较低自由度（特定脚本）。
• 解释原因。 解释指令背后的理由，而不是过度使用 MUST 等强硬措辞。相比僵化规则，Claude 更能响应对动机的理解。
• 术语保持一致。 选定一个术语并在全文使用。不要混用“API 端点”／“URL”／“API 路由”／“路径”。
• 不要添加多余文件。 不要添加 README.md、CHANGELOG.md、INSTALLATION_GUIDE.md。技能只包含 AI Agent 完成工作所需的内容。
• 仅使用正斜杠。 使用 scripts/helper.py，不要使用 scripts\helper.py。

提示词框架（适用于每个技能和项目提示词）

每个技能提示词以及每个 ChatGPT 或 Claude 项目提示词都使用相同的五个部分，顺序如下：

1. 目标。 用一到两句话说明提示词会为谁生成什么内容。
2. 角色。 Agent 扮演什么角色，以及该角色如何看待工作。
3. 对话协议。 对话如何进行：每条消息只问一个问题；每条消息顶部都写上阶段名称；每个阶段开始前提供简短说明；以及如何在阶段结束后检查结果。
4. 阶段。 按编号列出各阶段。每个阶段结束时都设置一个停止点，等待用户批准（“go”）后再开始下一阶段。
5. 硬性规则。 写明 Agent 绝不会做的事情，使用简单明了的规则。

框架中还包含另外两条规则：

• 限制修改轮次。 每个阶段允许一到两轮修改，然后继续下一阶段。在阶段中注明轮次上限。
• 不得臆造。 Agent 绝不臆造事实、数据、名称或数字。缺少信息时，应标记缺口（例如 [MISSING: price]）并提出询问，而不是自行补充。

需要在阶段之间交接时，让每个阶段都编写一个由下一阶段读取的 Markdown 文件。

创建后的检查清单

• 已创建 SKILL.md，并在 frontmatter 中包含 name 和 description
• 描述包含内容和触发时机，使用第三人称撰写
• SKILL.md 少于 500 行
• 知识文件已转换为 Markdown，并放入 references/
• 引用文件与 SKILL.md 的目录层级相差一级
• 较大的引用文件（>100 行）包含目录
• 提示词遵循五块结构，包含停止点、设有上限的修订轮数和禁止编造规则
• 已使用 /skill-name 和自动调用测试技能
• 没有多余的文档文件