Skill Builder

Skill Builder

此 Skill 的作用

创建可用于生产环境的 Claude Code Skills，包含规范的 YAML 前置元数据、渐进式披露架构，以及完整的文件$文件夹结构。此 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 前置元数据（必需）

每个 SKILL.md 必须以 YAML 前置元数据开头，且恰好包含两个必需字段：

---
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 Documentation Generator”
  • ✅ “React Component Builder”
  • ✅ “Database Schema Designer”
  • ❌ “skill-1”（缺乏描述性）
  • ❌ “This is a very long skill name that exceeds sixty-four characters”（太长）

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).

---

🛠️ 添加脚本和资源

脚本目录

用途：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/ - 包含钩子和上下文

---

### 🔗 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"]
}

高级配置

参见 Configuration Guide

---

分步指南

1. 初始设置

[详细步骤]

2. 核心工作流

[主要流程]

3. 集成

[集成步骤]

---

高级功能

功能 1：自定义模板

.$scripts$generate.sh --template custom

功能 2：批量处理

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

功能 3：CI/CD 集成

参见 CI/CD Guide

---

脚本参考

脚本	用途	用法
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