qe-skill-builder

Skill Builder

此 Skill 的作用

创建可用于生产环境的 Claude Code Skills，包含规范的 YAML frontmatter、渐进式披露架构以及完整的文件/文件夹结构。此 Skill 将引导你构建 Claude 可在所有使用场景（Claude.ai、Claude Code、SDK、API）中自主发现和使用的 Skills。

前提条件

• Claude Code 2.0+，或支持 Skills 的 Claude.ai
• 对 Markdown 和 YAML 有基本了解
• 文本编辑器或 IDE

快速开始

创建你的第一个 Skill

# 1. Create skill directory (MUST be at top level, NOT in subdirectories!)
mkdir -p ~/.claude/skills/my-first-skill

# 2. Create SKILL.md with proper format
cat > ~/.claude/skills/my-first-skill/SKILL.md << 'EOF'
---
name: "My First Skill"
description: "Brief description of what this skill does and when Claude should use it. Maximum 1024 characters."
---

# My First Skill

## What This Skill Does
[Your instructions here]

## Quick Start
[Basic usage]
EOF

# 3. Verify skill is detected
# Restart Claude Code or refresh Claude.ai

---

完整规范

📋 YAML Frontmatter（必需）

每个 SKILL.md 必须以 YAML frontmatter 开头，且恰好包含两个必需字段：

---
name: "Skill Name"                    # REQUIRED: Max 64 chars
description: "What this skill does    # REQUIRED: Max 1024 chars
and when Claude should use it."       # Include BOTH what & when
---

字段要求

name（必需）：

• 类型：字符串
• 最大长度：64 个字符
• 格式：便于用户理解的显示名称
• 用途：显示在 Skill 列表和 UI 中，并加载到 Claude 的系统提示词中
• 最佳实践：使用标题式大小写，保持简洁且具有描述性
• 示例：
  • ✅“API 文档生成器”
  • ✅“React 组件构建器”
  • ✅“数据库架构设计器”
  • ❌“skill-1”（缺乏描述性）
  • ❌“这是一个非常长、超过六十四个字符的 Skill 名称”（太长）

description（必需）：

• 类型：字符串
• 最大长度：1024 个字符
• 格式：纯文本或简洁的 Markdown
• 内容：必须包含：
  1. Skill 能做什么（功能）
  2. Claude 应在何时调用它（触发条件）
• 用途：加载到 Claude 的系统提示词中，以便自主匹配
• 最佳实践：将关键触发词放在开头，明确说明使用场景
• 示例：
  • ✅“根据 Express.js 路由生成 OpenAPI 3.0 文档。用于创建 API 文档、记录端点或编写 API 规范。”
  • ✅“使用 TypeScript、hooks 和测试创建 React 函数组件。用于搭建新组件或转换类组件。”
  • ❌“API 文档综合指南”（没有说明何时使用）
  • ❌“文档工具”（过于笼统）

YAML 格式规则

---
# ✅ CORRECT: Simple string
name: "API Builder"
description: "Creates REST APIs with Express and TypeScript."

# ✅ CORRECT: Multi-line description
name: "Full-Stack Generator"
description: "Generates full-stack applications with React frontend and Node.js backend. Use when starting new projects or scaffolding applications."

# ✅ CORRECT: Special characters quoted
name: "JSON:API Builder"
description: "Creates JSON:API compliant endpoints: pagination, filtering, relationships."

# ❌ WRONG: Missing quotes with special chars
name: API:Builder  # YAML parse error!

# ❌ WRONG: Extra fields (ignored but discouraged)
name: "My Skill"
description: "My description"
version: "1.0.0"       # NOT part of spec
author: "Me"           # NOT part of spec
tags: ["dev", "api"]   # NOT part of spec
---

重要：Claude 只会使用 name 和 description。其他字段会被忽略。

---

📂 目录结构

最简 Skill（必需）

~/.claude/skills/                    # Personal skills location
└── my-skill/                        # Skill directory (MUST be at top level!)
    └── SKILL.md                     # REQUIRED: Main skill file

重要：Skills 必须直接放在 ~/.claude/skills/[skill-name]/ 下。 Claude Code 不支持嵌套子目录或命名空间！

功能完整的 Skill（推荐）

~/.claude/skills/
└── my-skill/                        # Top-level skill directory
        ├── SKILL.md                 # REQUIRED: Main skill file
        ├── README.md                # Optional: Human-readable docs
        ├── scripts/                 # Optional: Executable scripts
        │   ├── setup.sh
        │   ├── validate.js
        │   └── deploy.py
        ├── resources/               # Optional: Supporting files
        │   ├── templates/
        │   │   ├── api-template.js
        │   │   └── component.tsx
        │   ├── examples/
        │   │   └── sample-output.json
        │   └── schemas/
        │       └── config-schema.json
        └── docs/                    # Optional: Additional documentation
            ├── ADVANCED.md
            ├── TROUBLESHOOTING.md
            └── API_REFERENCE.md

Skills 的存放位置

个人 Skills（可在所有项目中使用）：

~/.claude/skills/
└── [your-skills]/

• 路径：~/.claude/skills/ 或 $HOME/.claude/skills/
• 范围：此用户可在所有项目中使用
• 版本控制：不会提交到 git（位于仓库之外）
• 使用场景：个人效率工具、自定义工作流

项目 Skills（团队共享，受版本控制）：

<project-root>/.claude/skills/
└── [team-skills]/

• 路径：项目根目录下的 .claude/skills/
• 范围：仅在此项目中可用
• 版本控制：应提交到 git
• 使用场景：团队工作流、项目专用工具、共享知识

---

🎯 渐进式披露架构

Claude Code 使用三级渐进式披露系统，让你可以扩展到 100+ 个 Skills，而不会增加上下文负担：

第 1 级：元数据（名称 + 描述）

加载时机：Claude Code 启动时，始终加载 大小：每个 Skill 约 200 个字符 目的：支持自主匹配 Skill 上下文：所有 Skills 的元数据都会加载到系统提示词中

---
name: "API Builder"                   # 11 chars
description: "Creates REST APIs..."   # ~50 chars
---
# Total: ~61 chars per skill
# 100 skills = ~6KB context (minimal!)

第 2 级：SKILL.md 正文

加载时机：Skill 触发或匹配时 大小：通常约 1-10KB 目的：提供主要指令和操作步骤 上下文：仅为已激活的 Skills 加载

# API Builder

## What This Skill Does
[Main instructions - loaded only when skill is active]

## Quick Start
[Basic procedures]

## Step-by-Step Guide
[Detailed instructions]

第 3 级及以上：引用文件

加载时机：Claude 浏览时按需加载 大小：不定（KB 到 MB） 目的：提供深入参考资料、示例和架构 上下文：仅在 Claude 访问特定文件时加载

# In SKILL.md
See [Advanced Configuration](docs/ADVANCED.md) for complex scenarios.
See [API Reference](docs/API_REFERENCE.md) for complete documentation.
Use template: `resources/templates/api-template.js`

# Claude will load these files ONLY if needed

优势：安装 100+ 个 Skills，只需约 6KB 上下文。只有已激活 Skill 的内容（1-10KB）会进入上下文。

---

📝 SKILL.md 内容结构

推荐的 4 层结构

---
name: "Your Skill Name"
description: "What it does and when to use it"
---

# Your Skill Name

## Level 1: Overview (Always Read First)
Brief 2-3 sentence description of the skill.

## Prerequisites
- Requirement 1
- Requirement 2

## What This Skill Does
1. Primary function
2. Secondary function
3. Key benefit

---

## Level 2: Quick Start (For Fast Onboarding)

### Basic Usage
```bash
# Simplest use case
command --option value

常见场景

1. 场景 1：如何……
2. 场景 2：如何……

---

第 3 层：详细说明（用于深入工作）

分步指南

步骤 1：初始设置

# Commands

预期输出：

Success message

步骤 2：配置

• 配置选项 1
• 配置选项 2

步骤 3：执行

• 运行主要命令
• 验证结果

高级选项

选项 1：自定义配置

# Advanced usage

选项 2：集成

# Integration steps

---

第 4 层：参考（很少需要）

故障排查

问题：常见问题

症状：你看到的情况 原因：问题发生的原因 解决方案：如何修复

# Fix command

问题：另一个问题

解决方案：解决步骤

完整 API 参考

参见 API_REFERENCE.md

示例

参见 examples/

相关技能

• 相关技能 1
• 相关技能 2

资源

• 外部链接 1
• 文档

---

### 🎨 Content Best Practices

#### Writing Effective Descriptions

**Front-Load Keywords**:
```yaml
# ✅ GOOD: Keywords first
description: "Generate TypeScript interfaces from JSON schema. Use when converting schemas, creating types, or building API clients."

# ❌ BAD: Keywords buried
description: "This skill helps developers who need to work with JSON schemas by providing a way to generate TypeScript interfaces."

包含触发条件：

# ✅ GOOD: Clear "when" clause
description: "Debug React performance issues using Chrome DevTools. Use when components re-render unnecessarily, investigating slow updates, or optimizing bundle size."

# ❌ BAD: No trigger conditions
description: "Helps with React performance debugging."

明确具体：

# ✅ GOOD: Specific technologies
description: "Create Express.js REST endpoints with Joi validation, Swagger docs, and Jest tests. Use when building new APIs or adding endpoints."

# ❌ BAD: Too generic
description: "Build API endpoints with proper validation and testing."

渐进式披露写作

第 1 层保持简洁（概述）：

## What This Skill Does
Creates production-ready React components with TypeScript, hooks, and tests in 3 steps.

第 2 层用于常见路径（快速入门）：

## Quick Start
```bash
# Most common use case (80% of users)
generate-component MyComponent

**Level 3 for Details** (Step-by-Step):
```markdown
## Step-by-Step Guide

### Creating a Basic Component
1. Run generator
2. Choose template
3. Customize options
[Detailed explanations]

第 4 层用于边缘情况（参考）：

## Advanced Configuration
For complex scenarios like HOCs, render props, or custom hooks, see [ADVANCED.md](docs/ADVANCED.md).

---

🛠️ 添加脚本和资源

Scripts 目录

用途：Claude 可以运行的可执行脚本 位置：技能目录中的 scripts/ 用法：在 SKILL.md 中引用

示例：

# In skill directory
scripts/
├── setup.sh          # Initialization script
├── validate.js       # Validation logic
├── generate.py       # Code generation
└── deploy.sh         # Deployment script

在 SKILL.md 中引用：

## Setup
Run the setup script:
```bash
./scripts/setup.sh

验证

验证你的配置：

node scripts/validate.js config.json

#### Resources Directory

**Purpose**: Templates, examples, schemas, static files
**Location**: `resources/` in skill directory
**Usage**: Referenced or copied by scripts

Example:
```bash
resources/
├── templates/
│   ├── component.tsx.template
│   ├── test.spec.ts.template
│   └── story.stories.tsx.template
├── examples/
│   ├── basic-example/
│   ├── advanced-example/
│   └── integration-example/
└── schemas/
    ├── config.schema.json
    └── output.schema.json

在 SKILL.md 中引用：

## Templates
Use the component template:
```bash
cp resources/templates/component.tsx.template src/components/MyComponent.tsx

示例

参见 resources/examples/ 中可运行的示例：

• basic-example/ - 简单组件
• advanced-example/ - 包含 hooks 和 context

---

### 🔗 File References and Navigation

Claude can navigate to referenced files automatically. Use these patterns:

#### Markdown Links
```markdown
See [Advanced Configuration](docs/ADVANCED.md) for complex scenarios.
See [Troubleshooting Guide](docs/TROUBLESHOOTING.md) if you encounter errors.

相对文件路径

Use the template located at `resources/templates/api-template.js`
See examples in `resources/examples/basic-usage/`

内联文件内容

## Example Configuration
See `resources/examples/config.json`:
```json
{
  "option": "value"
}

**Best Practice**: Keep SKILL.md lean (~2-5KB). Move lengthy content to separate files and reference them. Claude will load only what's needed.

---

### ✅ Validation Checklist

Before publishing a skill, verify:

**YAML Frontmatter**:
- [ ] Starts with `---`
- [ ] Contains `name` field (max 64 chars)
- [ ] Contains `description` field (max 1024 chars)
- [ ] Description includes "what" and "when"
- [ ] Ends with `---`
- [ ] No YAML syntax errors

**File Structure**:
- [ ] SKILL.md exists in skill directory
- [ ] Directory is DIRECTLY in `~/.claude/skills/[skill-name]/` or `.claude/skills/[skill-name]/`
- [ ] Uses clear, descriptive directory name
- [ ] **NO nested subdirectories** (Claude Code requires top-level structure)

**Content Quality**:
- [ ] Level 1 (Overview) is brief and clear
- [ ] Level 2 (Quick Start) shows common use case
- [ ] Level 3 (Details) provides step-by-step guide
- [ ] Level 4 (Reference) links to advanced content
- [ ] Examples are concrete and runnable
- [ ] Troubleshooting section addresses common issues

**Progressive Disclosure**:
- [ ] Core instructions in SKILL.md (~2-5KB)
- [ ] Advanced content in separate docs/
- [ ] Large resources in resources/ directory
- [ ] Clear navigation between levels

**Testing**:
- [ ] Skill appears in Claude's skill list
- [ ] Description triggers on relevant queries
- [ ] Instructions are clear and actionable
- [ ] Scripts execute successfully (if included)
- [ ] Examples work as documented

---

## Skill Builder Templates

### Template 1: Basic Skill (Minimal)

```markdown
---
name: "My Basic Skill"
description: "One sentence what. One sentence when to use."
---

# My Basic Skill

## What This Skill Does
[2-3 sentences describing functionality]

## Quick Start
```bash
# Single command to get started

分步指南

步骤 1：设置

[说明]

步骤 2：使用

[说明]

步骤 3：验证

[说明]

故障排查

• 问题：问题描述
  • 解决方案：修复说明

### Template 2: Intermediate Skill (With Scripts)

```markdown
---
name: "My Intermediate Skill"
description: "Detailed what with key features. When to use with specific triggers: scaffolding, generating, building."
---

# My Intermediate Skill

## Prerequisites
- Requirement 1
- Requirement 2

## What This Skill Does
1. Primary function
2. Secondary function
3. Integration capability

## Quick Start
```bash
./scripts/setup.sh
./scripts/generate.sh my-project

配置

编辑 config.json：

{
  "option1": "value1",
  "option2": "value2"
}

分步指南

基本用法

[适用于 80% 使用场景的步骤]

高级用法

[适用于复杂场景的步骤]

可用脚本

• scripts/setup.sh - 初始设置
• scripts/generate.sh - 代码生成
• scripts/validate.sh - 验证

资源

• 模板：resources/templates/
• 示例：resources/examples/

故障排查

[常见问题和解决方案]

### Template 3: Advanced Skill (Full-Featured)

```markdown
---
name: "My Advanced Skill"
description: "Comprehensive what with all features and integrations. Use when [trigger 1], [trigger 2], or [trigger 3]. Supports [technology stack]."
---

# My Advanced Skill

## Overview
[Brief 2-3 sentence description]

## Prerequisites
- Technology 1 (version X+)
- Technology 2 (version Y+)
- API keys or credentials

## What This Skill Does
1. **Core Feature**: Description
2. **Integration**: Description
3. **Automation**: Description

---

## Quick Start (60 seconds)

### Installation
```bash
./scripts/install.sh

首次使用

./scripts/quickstart.sh

预期输出：

✓ Setup complete
✓ Configuration validated
→ Ready to use

---

配置

基本配置

编辑 config.json：

{
  "mode": "production",
  "features": ["feature1", "feature2"]
}

高级配置

参见 配置指南

---

分步指南

1. 初始设置

[详细步骤]

2. 核心工作流

[主要流程]

3. 集成

[集成步骤]

---

高级功能

功能 1：自定义模板

./scripts/generate.sh --template custom

功能 2：批处理

./scripts/batch.sh --input data.json

功能 3：CI/CD 集成

参见 CI/CD 指南

---

脚本参考

脚本	用途	用法
install.sh	安装依赖项	./scripts/install.sh
generate.sh	生成代码	./scripts/generate.sh [name]
validate.sh	验证输出	./scripts/validate.sh
deploy.sh	部署到环境	./scripts/deploy.sh [env]

---

资源

模板

• resources/templates/basic.template - 基本模板
• resources/templates/advanced.template - 高级模板

示例

• resources/examples/basic/ - 简单示例
• resources/examples/advanced/ - 复杂示例
• resources/examples/integration/ - 集成示例

架构

• resources/schemas/config.schema.json - 配置架构
• resources/schemas/output.schema.json - 输出验证

---

故障排查

问题：安装失败

症状：运行 install.sh 时出错 原因：缺少依赖项 解决方案：

# Install prerequisites
npm install -g required-package
./scripts/install.sh --force

问题：验证错误

症状：验证脚本失败 解决方案：请参阅故障排除指南

---

API 参考

完整的 API 文档：API_REFERENCE.md

相关技能

• 相关技能 1
• 相关技能 2

资源

• 官方文档
• GitHub 仓库
• 社区论坛

---

创建日期：2025-10-19 类别：高级 难度：中级 预计用时：15-30 分钟

---

## Examples from the Wild

### Example 1: Simple Documentation Skill

```markdown
---
name: "README Generator"
description: "Generate comprehensive README.md files for GitHub repositories. Use when starting new projects, documenting code, or improving existing READMEs."
---

# README Generator

## What This Skill Does
Creates well-structured README.md files with badges, installation, usage, and contribution sections.

## Quick Start
```bash
# Answer a few questions
./scripts/generate-readme.sh

# README.md created with:
# - Project title and description
# - Installation instructions
# - Usage examples
# - Contribution guidelines

自定义

生成前，请编辑 resources/templates/sections/ 中的章节。

### Example 2: Code Generation Skill

```markdown
---
name: "React Component Generator"
description: "Generate React functional components with TypeScript, hooks, tests, and Storybook stories. Use when creating new components, scaffolding UI, or following component architecture patterns."
---

# React Component Generator

## Prerequisites
- Node.js 18+
- React 18+
- TypeScript 5+

## Quick Start
```bash
./scripts/generate-component.sh MyComponent

# Creates:
# - src/components/MyComponent/MyComponent.tsx
# - src/components/MyComponent/MyComponent.test.tsx
# - src/components/MyComponent/MyComponent.stories.tsx
# - src/components/MyComponent/index.ts

分步指南

1. 运行生成器

./scripts/generate-component.sh ComponentName

2. 选择模板

• 基础：简单的功能组件
• 带状态：useState 钩子
• 带上下文：useContext 集成
• 带 API：数据获取组件

3. 自定义

编辑 src/components/ComponentName/ 中生成的文件

模板

请参阅 resources/templates/，了解可用的组件模板。

---

## Learn More

### Official Resources
- [Anthropic Agent Skills Documentation](https://docs.claude.com/en/docs/agents-and-tools/agent-skills)
- [GitHub Skills Repository](https://github.com/anthropics/skills)
- [Claude Code Documentation](https://docs.claude.com/en/docs/claude-code)

### Community
- [Skills Marketplace](https://github.com/anthropics/skills) - Browse community skills
- [Anthropic Discord](https://discord.gg/anthropic) - Get help from community

### Advanced Topics
- Multi-file skills with complex navigation
- Skills that spawn other skills
- Integration with MCP tools
- Dynamic skill generation

---

**Created**: 2025-10-19
**Version**: 1.0.0
**Maintained By**: agentic-flow team
**License**: MIT