skill-builder

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill Builder

技能构建工具

This skill helps you create well-structured Claude Code Skills. Use it when the user wants to build a new skill for Claude Code.

本技能可帮助你创建结构规范的Claude Code Skills。当用户想要为Claude Code构建新技能时，即可使用本工具。

When to Use This Skill

何时使用本技能

Invoke this skill when users:

Want to create a new Claude Code Skill
Ask how to build or structure a skill
Need help with skill frontmatter or organization
Want to validate an existing skill structure

当用户有以下需求时，调用本技能：

想要创建新的Claude Code Skill
询问如何构建或设计技能结构
需要技能前置配置或组织架构相关帮助
需要验证现有技能的结构是否合规

Skill Creation Workflow

技能创建工作流

Step 1: Understand the Requirements

步骤1：明确需求

Ask the user these questions (use AskUserQuestion tool when appropriate):

What will the skill do? - Get a clear description of the skill's purpose
When should it trigger? - Understand what user requests should activate it
What's the scope? - Is it project-specific or personal/general-purpose?
What resources are needed? - Templates, scripts, reference data, etc.

向用户询问以下问题（适当时使用AskUserQuestion工具）：

该技能的功能是什么？ - 明确技能的核心用途
何时触发该技能？ - 了解哪些用户请求会激活它
技能的适用范围是什么？ - 是项目专属还是个人/通用型？
需要哪些资源？ - 模板、脚本、参考数据等

Step 2: Determine Skill Location

步骤2：确定技能存储位置

Based on scope, choose the directory:

Project-specific:
```
.claude/skills/[skill-name]/
```
(within project root)
Personal/general:
```
~/.claude/skills/[skill-name]/
```
(available everywhere)

根据适用范围选择目录：

项目专属：
```
.claude/skills/[skill-name]/
```
（位于项目根目录下）
个人/通用型：
```
~/.claude/skills/[skill-name]/
```
（全局可用）

Step 3: Create Directory Structure

步骤3：创建目录结构

Use this pattern:

skill-name/
├── SKILL.md           (required: main instructions)
├── REFERENCE.md       (optional: detailed reference info)
├── FORMS.md           (optional: templates and forms)
├── scripts/           (optional: executable code)
│   ├── script1.py
│   └── script2.sh
└── resources/         (optional: templates, data files)
    └── template.txt

遵循以下目录模式：

skill-name/
├── SKILL.md           (必填：主说明文档)
├── REFERENCE.md       (可选：详细参考信息)
├── FORMS.md           (可选：模板和表单)
├── scripts/           (可选：可执行代码)
│   ├── script1.py
│   └── script2.sh
└── resources/         (可选：模板、数据文件)
    └── template.txt

Step 4: Write SKILL.md

步骤4：编写SKILL.md

The SKILL.md must follow this structure:

markdown

---
name: skill-name
description: Clear description of what this skill does and when to use it
---

SKILL.md必须遵循以下结构：

markdown

---
name: skill-name
description: Clear description of what this skill does and when to use it
---

Skill Name

Main instructions for Claude go here.

When to Use

Describe scenarios where this skill should be invoked.

How It Works

Step-by-step instructions for Claude to follow.

Examples

Provide examples of usage.


**Frontmatter Requirements:**
- `name`: Max 64 chars, lowercase letters/numbers/hyphens only (e.g., "excel-automation")
- `description`: Non-empty, max 1024 chars, should clearly indicate when to use the skill
  - **IMPORTANT:** Include BOTH natural language AND technical keywords
  - Natural language: How non-technical users would describe it ("fix broken code", "save data", "put online")
  - Technical terms: Jargon that developers use ("debug", "database schema", "deploy")
  - Example: "Auto-invoked when user wants to fix broken code, not working, or crashed. Also triggers on debug, stack trace, error analysis."

**Best Practices for Instructions:**
- Write like an "onboarding guide for a new team member"
- Use clear, step-by-step procedures
- Include contextual examples
- Reference supporting files instead of embedding everything
- Keep instructions under 5k tokens for efficient loading
- Use progressive disclosure: reference detailed info in REFERENCE.md

Provide examples of usage.


**前置配置要求：**
- `name`：最多64个字符，仅允许小写字母/数字/连字符（例如："excel-automation"）
- `description`：非空，最多1024个字符，需明确说明技能的功能及触发场景
  - **重要提示：** 需同时包含自然语言描述和技术关键词
  - 自然语言：非技术用户的描述方式（如"修复损坏的代码"、"保存数据"、"上线部署"）
  - 技术术语：开发者常用的行话（如"debug"、"database schema"、"deploy"）
  - 示例："当用户想要修复损坏的代码、解决程序故障或崩溃问题时自动触发。同时在debug、堆栈跟踪、错误分析场景下也会激活。"

**说明文档最佳实践：**
- 撰写风格如同“新团队成员入职指南”
- 使用清晰的分步流程
- 包含上下文示例
- 引用支持文件而非嵌入所有内容
- 说明内容的token数控制在5000以内以保证加载效率
- 采用渐进式披露策略：将详细信息放在REFERENCE.md中供参考

Step 5: Add Supporting Files (Optional)

步骤5：添加支持文件（可选）

REFERENCE.md: Detailed technical information that Claude can read when needed

API documentation
Detailed specifications
Comprehensive examples
Technical constraints

FORMS.md: Templates and structured formats

Form templates
Output format examples
Structured data patterns

scripts/: Executable code for complex operations

Python scripts for data processing
Shell scripts for automation
Utilities that Claude can invoke via bash

resources/: Static files and templates

Document templates
Sample data
Reference materials

REFERENCE.md：Claude需要时可查阅的详细技术信息

API文档
详细规格说明
完整示例
技术约束条件

FORMS.md：模板和结构化格式

表单模板
输出格式示例
结构化数据模式

scripts/：用于复杂操作的可执行代码

数据处理用Python脚本
自动化用Shell脚本
Claude可通过bash调用的工具

resources/：静态文件和模板

文档模板
示例数据
参考资料

Step 6: Validate the Skill

步骤6：验证技能

Check these requirements:

```
SKILL.md
```
exists with valid YAML frontmatter
```
name
```
is lowercase, alphanumeric with hyphens, max 64 chars
```
description
```
is clear, non-empty, max 1024 chars
Description includes natural language keywords (not just technical jargon)
Instructions are clear and actionable
File references are correct
No internet/API dependencies (Claude Code constraint)
Only uses pre-installed packages

Run automated validation:

bash

python .validation/validate-skills.py

Validation Scoring (29 points total):

SKILL.md exists: 1 point
Valid frontmatter: 3 points
Name validation: 2 points
Description validation: 3 points
Content structure: 5 points
Token count <5000: 2 points
Supporting files: 3 points
Scripts directory: 2 points
Industry standards: 3 points
Examples: 2 points
Natural language keywords: 3 points (NEW)

Passing threshold: 80% (24/29 points)

检查以下要求：

存在包含有效YAML前置配置的
```
SKILL.md
```
```
name
```
为小写字母、数字加连字符，长度不超过64字符
```
description
```
清晰、非空，长度不超过1024字符
描述包含自然语言关键词（而非仅技术术语）
说明内容清晰且可执行
文件引用路径正确
无网络/API依赖（Claude Code限制）
仅使用预安装的包

运行自动化验证：

bash

python .validation/validate-skills.py

验证评分（总分29分）：

存在SKILL.md：1分
前置配置有效：3分
名称合规：2分
描述合规：3分
内容结构：5分
Token数<5000：2分
支持文件：3分
Scripts目录：2分
行业标准：3分
示例：2分
自然语言关键词：3分（新增）

通过阈值：80%（24/29分）

Step 7: Test the Skill

步骤7：测试技能

After creation:

Verify the skill is discoverable (Claude should see it in metadata)
Test with a sample task that should trigger it
Ensure resources load correctly when referenced
Check that instructions are clear and complete

创建完成后：

验证技能可被发现（Claude应能在元数据中找到它）
使用应触发该技能的示例任务进行测试
确保引用的资源可正确加载
检查说明内容是否清晰完整

Progressive Disclosure Strategy

渐进式披露策略

Design skills to minimize token usage:

Always Loaded (Metadata): ~100 tokens
- Just the YAML frontmatter
Loaded When Triggered (Instructions): <5k tokens
- Core procedures from SKILL.md body
Loaded As Needed (Resources): No token cost
- Files Claude reads via bash commands
- Scripts Claude executes when required
- Templates Claude accesses on demand

设计技能时尽量减少token使用：

始终加载（元数据）：约100个token
- 仅包含YAML前置配置
触发时加载（说明内容）：<5000个token
- SKILL.md主体中的核心流程
按需加载（资源）：无token消耗
- Claude可通过bash命令读取的文件
- Claude在需要时执行的脚本
- Claude可按需访问的模板

Common Skill Patterns

常见技能模式

Document Generation Skill

文档生成技能

doc-generator/
├── SKILL.md          (generation instructions)
├── templates/        (document templates)
└── scripts/          (formatting scripts)

doc-generator/
├── SKILL.md          (生成说明)
├── templates/        (文档模板)
└── scripts/          (格式化脚本)

Code Analysis Skill

代码分析技能

code-analyzer/
├── SKILL.md          (analysis procedures)
├── REFERENCE.md      (pattern definitions)
└── scripts/          (analysis tools)

code-analyzer/
├── SKILL.md          (分析流程)
├── REFERENCE.md      (模式定义)
└── scripts/          (分析工具)

Automation Skill

自动化技能

automation-helper/
├── SKILL.md          (automation workflows)
├── FORMS.md          (configuration templates)
└── scripts/          (automation scripts)

automation-helper/
├── SKILL.md          (自动化工作流)
├── FORMS.md          (配置模板)
└── scripts/          (自动化脚本)

Implementation Steps

实施步骤

When helping users build a skill:

Gather Information: Use AskUserQuestion to understand requirements
Plan Structure: Determine files needed based on complexity
Create Directory: Make the skill directory in appropriate location
Write SKILL.md: Create with proper frontmatter and instructions
Add Supporting Files: Create REFERENCE.md, FORMS.md, scripts as needed
Validate: Check all requirements are met
Document: Explain to user how to test and use the skill
Show Location: Provide the full path to the created skill

帮助用户构建技能时：

收集信息：使用AskUserQuestion工具了解需求
规划结构：根据复杂度确定所需文件
创建目录：在合适的位置创建技能目录
编写SKILL.md：创建包含正确前置配置和说明的文档
添加支持文件：按需创建REFERENCE.md、FORMS.md、脚本等
验证：检查所有要求是否满足
文档说明：向用户解释如何测试和使用该技能
展示位置：提供创建完成的技能的完整路径

Validation Checklist

验证检查表

Tips for Great Skills

优秀技能设计技巧

Clear Descriptions: Make it obvious when Claude should use the skill
Step-by-Step: Write procedures as numbered steps
Examples First: Show examples before explaining
Minimize Context: Use progressive disclosure extensively
Self-Contained: Don't assume external resources are available
Tested Procedures: Ensure instructions actually work
Helpful Metadata: Write descriptions that help with discovery

清晰描述：明确说明Claude应何时使用该技能
分步流程：将流程编写为编号步骤
示例优先：先展示示例再进行解释
最小化上下文：大量使用渐进式披露策略
自包含：不要假设外部资源可用
经过测试的流程：确保说明内容切实可行
有用的元数据：编写有助于技能发现的描述

Common Mistakes to Avoid

需避免的常见错误

Using uppercase or special characters in skill name
Making descriptions too vague or too long
Embedding all content in SKILL.md instead of using supporting files
Referencing non-existent files
Assuming internet access or external APIs
Creating overly complex skills that should be split
Forgetting to include "when to use" guidance

技能名称使用大写字母或特殊字符
描述过于模糊或冗长
将所有内容嵌入SKILL.md而非使用支持文件
引用不存在的文件
假设具备网络访问权限或外部API可用
创建过于复杂、应拆分的技能
遗漏“何时使用”的指导说明

Reference Files

参考文件

See the templates directory for:

Basic skill template
Advanced skill template with supporting files
Example skills for common use cases

可查看templates目录获取：

基础技能模板
包含支持文件的高级技能模板
常见场景的示例技能