Back to Details

agent-skill-builder

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Agent Skill Builder

Agent技能构建器

Quickly scaffolds new Claude Code skills or translates ChatGPT projects into Claude Code format. This skill focuses on fast creation and correct structure. For iterative testing, benchmarking, and description optimization, use 
/skill-creator
.
快速搭建新的Claude Code技能，或将ChatGPT项目转换为Claude Code格式。本技能专注于快速创建与正确结构搭建。如需迭代测试、基准测试和描述优化，请使用
/skill-creator
。

Two Modes

两种模式

Mode 1: Create New Skill (
/agent-skill-builder new [name]
)

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

Scaffolds a fresh Claude Code skill with proper structure and best practices.
按照规范结构与最佳实践搭建全新的Claude Code技能。

Mode 2: Translate ChatGPT Project (
/agent-skill-builder translate [name]
)

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

Converts an existing ChatGPT project into a Claude Code skill.
将现有ChatGPT项目转换为Claude Code技能格式。

Create New Skill

创建新技能

Step 1: Gather Intent

步骤1：收集需求

Ask the user (skip what's already clear from context):
  1. Skill name: What should the 
    /slash-command
    be called?
  2. Purpose: What does this skill do?
  3. Examples: How would this skill be used in practice?
  4. Triggers: What would a user say that should invoke this skill?
询问用户（上下文已明确的内容可跳过）：
  1. 技能名称：斜杠命令
    /slash-command
    的名称是什么？
  2. 用途：该技能的功能是什么？
  3. 示例：该技能在实际场景中如何使用？
  4. 触发条件：用户说出哪些内容时应触发此技能？

Step 2: Plan Resources

步骤2：规划资源

Analyze each example to identify what should be bundled:
  • Scripts (
    scripts/
    ): Code rewritten repeatedly or needing deterministic reliability. Execute without loading into context.
  • References (
    references/
    ): Documentation Claude should consult while working. Loaded on demand.
  • Assets (
    assets/
    ): Files used in output (templates, images, fonts). Not loaded into context.
分析每个示例，确定需要打包的资源类型：
  • 脚本（
    scripts/
    ）：需要重复编写或要求确定性可靠性的代码。无需加载到上下文即可执行。
  • 参考资料（
    references/
    ）：Claude工作时需要查阅的文档。按需加载。
  • 资源文件（
    assets/
    ）：输出中使用的文件（模板、图片、字体）。无需加载到上下文。

Step 3: Create Directory and SKILL.md

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

bash
mkdir -p ~/.claude/skills/[skill-name]
Write SKILL.md following this template:
markdown
---
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."
---
bash
mkdir -p ~/.claude/skills/[skill-name]
按照以下模板编写SKILL.md：
markdown
---
name: skill-name
description: "描述该技能的功能及触发场景，使用第三人称撰写。包含用户可能使用的关键词，最多1024字符。这是主要的触发机制。"
---

Skill Name

技能名称

[1-2 sentence description]
[1-2句话描述]

Instructions

操作说明

[Step-by-step guidance — use imperative form]
[分步指导——使用祈使语气]

Output Format

输出格式

[Expected output structure]
[预期的输出结构]

Constraints

约束条件

[Limitations and rules]
undefined
[限制规则]
undefined

Step 4: Add Reference Files (if needed)

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

For skills with multiple domains or variants, keep SKILL.md lean and split into references:
skill-name/
├── SKILL.md (overview + navigation, under 500 lines)
└── references/
    ├── variant-a.md
    └── variant-b.md
Reference from SKILL.md with clear guidance on when to read each file. Keep references one level deep.
对于涉及多个领域或变体的技能，保持SKILL.md简洁，将详细内容拆分到参考文件中：
skill-name/
├── SKILL.md（概述与导航，不超过500行）
└── references/
    ├── variant-a.md
    └── variant-b.md
在SKILL.md中添加清晰指引，说明何时读取每个参考文件。参考文件仅保留一级目录结构。

Step 5: Test

步骤5：测试

  1. Invoke directly: 
    /skill-name
  2. Let Claude auto-invoke by matching description keywords
  3. Check that the skill triggers when expected and stays silent when not relevant
  1. 直接调用：
    /skill-name
  2. 通过匹配描述关键词让Claude自动触发
  3. 验证技能在预期场景下触发，在无关场景下保持静默

Translate ChatGPT Project to Claude Skill

将ChatGPT项目转换为Claude技能

Step 1: Extract ChatGPT Components

步骤1：提取ChatGPT组件

Request from user:
  • System prompt/instructions
  • Knowledge files (PDFs, docs)
  • Conversation starters (optional)
  • Actions/API configurations (if any)
向用户获取：
  • 系统提示词/操作说明
  • 知识库文件（PDF、文档）
  • 对话起始语（可选）
  • 动作/API配置（如有）

Step 2: Map Components

步骤2：组件映射

ChatGPT ComponentClaude Code EquivalentLocation
Name
name
in frontmatter		SKILL.md
Description
description
in frontmatter		SKILL.md
InstructionsMain markdown bodySKILL.md
Knowledge files
references/
folder (convert to .md)		Subdirectory
Conversation startersDocument in Examples section or omitSKILL.md
Actions (APIs)MCP servers
~/.claude/mcp.json
Code InterpreterNative tools: 
Bash
, 
Read
, 
Write
, 
Edit
, 
Glob
, 
Grep
Built-in
MemoryNo direct equivalent. Use context files or skill background sectionsVarious
ChatGPT组件Claude Code等效项存放位置
名称frontmatter中的
name
字段		SKILL.md
描述frontmatter中的
description
字段		SKILL.md
操作说明Markdown主体内容SKILL.md
知识库文件
references/
文件夹（转换为.md格式）		子目录
对话起始语记录在示例部分或省略SKILL.md
动作（API）MCP服务器
~/.claude/mcp.json
代码解释器原生工具：
Bash
, 
Read
, 
Write
, 
Edit
, 
Glob
, 
Grep
内置功能
记忆功能无直接等效项。使用上下文文件或技能背景章节实现多个位置

Step 3: Convert Instructions

步骤3：转换操作说明

ChatGPT PatternClaude Equivalent
"You are a [role]..."Role section or integrate into instructions
"Your task is to..."Instructions section
"Always/Never..."Constraints section
"Output format..."Output Format section
Input placeholders 
[text]
Keep as-is or use 
$ARGUMENTS
ChatGPT模式Claude等效写法
"你是一个[角色]..."角色章节或整合到操作说明中
"你的任务是..."操作说明章节
"始终/绝不..."约束条件章节
"输出格式..."输出格式章节
输入占位符
[text]
保留原样或使用
$ARGUMENTS

Step 4: Convert Knowledge Files

步骤4：转换知识库文件

  1. Convert PDFs/docs to Markdown and place in 
    references/
  2. For large files (>10k words), include grep search patterns in SKILL.md
  3. For files >100 lines, add a table of contents at the top
  4. Templates and assets go in 
    assets/
  1. 将PDF/文档转换为Markdown格式并存放在
    references/
    中
  2. 对于大文件（>10000词），在SKILL.md中添加grep搜索规则
  3. 对于超过100行的文件，在顶部添加目录
  4. 模板与资源文件放入
    assets/

Step 5: Write Frontmatter

步骤5：编写前置元数据（frontmatter）

The 
description
field is the primary triggering mechanism. Write in third person and include both what the skill does and when to use it. Be slightly "pushy" with triggers to combat undertriggering.
description
字段是主要触发机制。使用第三人称撰写，同时说明技能功能与触发场景。可适当强化触发关键词以避免触发不足。

Frontmatter Reference

Frontmatter参考

Only 
name
and 
description
are required. Additional fields are Claude Code-specific extensions:
FieldRequiredDescription
name
YesMax 64 chars, lowercase letters/numbers/hyphens only
description
YesMax 1024 chars. What + When. Third person. Primary trigger mechanism
argument-hint
NoHint shown in autocomplete (e.g., 
"[issue-number]"
)
disable-model-invocation
No
true
= user-only invocation (no auto-trigger)
user-invocable
No
false
= Claude-only (hidden from slash command menu)
context
No
fork
= run in isolated subagent
agent
NoSubagent type: 
Explore
, 
Plan
, 
general-purpose
allowed-tools
NoRestrict available tools: 
Read, Grep, Glob
model
NoOverride model for this skill
仅
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
否为此技能覆盖默认模型

String Substitutions

字符串替换

VariableDescription
$ARGUMENTS
Everything after 
/skill-name
${CLAUDE_SESSION_ID}
Current session ID
!`command`
Dynamic injection (runs before skill loads)
变量描述
$ARGUMENTS
/skill-name
之后的所有内容
${CLAUDE_SESSION_ID}
当前会话ID
!`command`
动态注入（技能加载前执行）

Skill Locations

技能存放位置

LocationPathScope
Personal
~/.claude/skills/[name]/
All projects
Project
.claude/skills/[name]/
This project only
位置路径作用范围
个人技能
~/.claude/skills/[name]/
所有项目
项目技能
.claude/skills/[name]/
仅当前项目

Writing Best Practices

写作最佳实践

These come from Anthropic's official skill authoring guide:
  • Concise is key. Claude is already smart. Only add context Claude doesn't already have. Prefer concise examples over verbose explanations.
  • Description is everything. Claude reads descriptions to decide which skill to use from potentially 100+ available skills. Be specific, include trigger keywords, write in third person.
  • Progressive disclosure. Keep SKILL.md under 500 lines. Move detailed references to separate files. Claude loads them only when needed.
  • Match freedom to fragility. High freedom (text instructions) for flexible tasks, low freedom (specific scripts) for fragile operations.
  • Explain the why. Explain reasoning behind instructions rather than using heavy-handed MUSTs. Claude responds better to understanding motivation than rigid rules.
  • Consistent terminology. Pick one term and use it throughout. Don't mix "API endpoint" / "URL" / "API route" / "path".
  • No extraneous files. No README.md, CHANGELOG.md, INSTALLATION_GUIDE.md. Skills contain only what an AI agent needs to do the job.
  • Forward slashes only. Use 
    scripts/helper.py
    , never 
    scripts\helper.py
    .
这些来自Anthropic官方技能创作指南：
  • 简洁为上：Claude本身已具备智能。仅添加Claude未知的上下文。优先使用简洁示例而非冗长解释。
  • 描述决定一切：Claude会从100+可用技能中读取描述来决定使用哪一个。描述要具体，包含触发关键词，使用第三人称。
  • 渐进式披露：保持SKILL.md不超过500行。将详细参考内容移至单独文件。Claude仅在需要时加载这些文件。
  • 自由度与稳定性匹配：灵活任务使用高自由度（文本指令），易出错操作使用低自由度（特定脚本）。
  • 解释原因：解释指令背后的逻辑，而非使用强硬的“必须”要求。Claude对动机的理解优于刚性规则。
  • 术语一致：选择一个术语并全程使用。不要混用“API端点”/“URL”/“API路由”/“路径”。
  • 无冗余文件：不要包含README.md、CHANGELOG.md、INSTALLATION_GUIDE.md。技能仅包含AI Agent完成工作所需的内容。
  • 仅使用正斜杠：使用
    scripts/helper.py
    ，切勿使用
    scripts\helper.py
    。

After Creation Checklist

创建后检查清单

  • SKILL.md created with 
    name
    and 
    description
    in frontmatter
  • Description includes what AND when (triggers), written in third person
  • SKILL.md under 500 lines
  • Knowledge files converted to Markdown in 
    references/
  • References are one level deep from SKILL.md
  • Large reference files (>100 lines) have table of contents
  • Skill tested with 
    /skill-name
    and auto-invocation
  • No extraneous documentation files
  • 已创建包含frontmatter中
    name
    和
    description
    字段的SKILL.md
  • 描述包含功能与触发场景，使用第三人称撰写
  • SKILL.md不超过500行
  • 知识库文件已转换为Markdown并存放在
    references/
    中
  • 参考文件仅为SKILL.md的一级子目录
  • 大型参考文件（>100行）已添加目录
  • 已通过
    /skill-name
    和自动触发测试技能
  • 无冗余文档文件