如何为 Claude Code 创建 Skill：以 youtube-pro 为例

前言

如果你使用过 Claude Code 或 Claude.ai，你可能知道 Skill 是一个强大的功能 —— 它可以让 AI 学习你的工作流程，在特定场景下自动执行复杂的任务序列。

本文将以我开源的 youtube-pro 项目为例，详细讲解如何从零开始创建一个功能完整的 Skill。

什么是 Skill？

Skill 是 Claude Code 和 Claude.ai 中的一种扩展机制，允许用户定义自定义的工作流程。当用户输入特定短语或执行特定任务时，Claude 会自动加载对应的 Skill，按照预定义的指令执行操作。

Skill 能做什么？

• 📝 文档处理：自动生成 Word、PDF、PPT 文档
• 📊 数据分析：Excel 处理、图表生成、数据可视化
• 🎬 多媒体处理：YouTube 视频转录、字幕提取、视频摘要
• 💬 沟通协作：内部通讯、FAQ 回答、新闻稿撰写
• 🎨 设计创作：Canvas 设计、主题生成、算法艺术
• 🔧 开发工具：MCP 服务器构建、Web 应用测试

Skill 项目结构

一个标准的 Skill 项目结构如下：

skill-name/
├── SKILL.md              # 核心文件：Skill 定义和指令
├── _meta.json            # 元数据：版本、触发词、依赖等
├── README.md             # 用户文档（可选）
├── scripts/              # 可执行脚本（可选）
│   ├── fetch_transcript.py
│   ├── detect_languages.py
│   └── summarize.py
├── references/           # 参考文档（可选）
│   └── language_codes.md
├── templates/            # 输出模板（可选）
│   └── markdown_template.md
└── assets/               # 资源文件（可选）
    └── icons/

核心文件说明

实战：创建 youtube-pro Skill

第一步：定义 Skill 元数据

创建 _meta.json 文件：

{
  "name": "youtube-pro",
  "version": "1.0.0",
  "description": "Advanced YouTube transcript extraction with multi-language support, timestamp options, AI summarization, batch processing, and export capabilities.",
  "author": "",
  "license": "MIT",
  "emoji": "🎬",
  "triggers": [
    "youtube transcript",
    "video summary",
    "download subtitles",
    "youtube playlist",
    "video timestamp",
    "extract quotes",
    "youtube search",
    "anki cards from video",
    "summarize youtube",
    "youtube chapters"
  ],
  "requirements": {
    "binaries": ["yt-dlp"],
    "python": ">=3.8"
  },
  "install": {
    "pip": {
      "package": "yt-dlp",
      "command": "pip install yt-dlp"
    },
    "brew": {
      "formula": "yt-dlp",
      "command": "brew install yt-dlp"
    }
  },
  "scripts": {
    "fetch_transcript.py": {
      "description": "Core transcript fetching with format options",
      "usage": "python scripts/fetch_transcript.py URL [options]"
    },
    "detect_languages.py": {
      "description": "List available subtitle languages",
      "usage": "python scripts/detect_languages.py URL"
    },
    "summarize.py": {
      "description": "AI-powered section summarization",
      "usage": "python scripts/summarize.py URL [options]"
    },
    "search_keywords.py": {
      "description": "Search keywords in transcript",
      "usage": "python scripts/search_keywords.py URL --keywords keyword1 keyword2"
    },
    "batch_process.py": {
      "description": "Process multiple videos/playlists",
      "usage": "python scripts/batch_process.py --playlist URL --output-dir ./output/"
    }
  },
  "created_at": "2026-03-15",
  "repository": "https://github.com/HAxiaoyu/youtube-pro"
}

第二步：编写 SKILL.md

SKILL.md 是 Skill 的核心，包含两部分：

1. YAML Front Matter：定义 Skill 名称、描述和触发条件
2. Markdown 正文：详细的执行指令

---
name: youtube-pro
description: Advanced YouTube transcript extraction with multi-language support, timestamp options, AI summarization, batch processing, and export capabilities. Use for any YouTube video analysis task requiring more than basic transcript fetching. Triggers on: youtube transcript, video summary, download subtitles, youtube playlist, video timestamp, extract quotes, youtube search, anki cards from video.
version: 1.0.0
triggers:
  - "youtube transcript"
  - "video summary"
  - "download subtitles"
  - "youtube playlist"
  - "video timestamp"
  - "extract quotes"
  - "youtube search"
  - "anki cards from video"
  - "summarize youtube"
  - "youtube chapters"
metadata: {"clawdbot":{"emoji":"🎬","requires":{"bins":["yt-dlp"]},"install":[{"id":"pip","kind":"pip","package":"yt-dlp","bins":["yt-dlp"],"label":"Install yt-dlp (pip)"},{"id":"brew","kind":"brew","formula":"yt-dlp","bins":["yt-dlp"],"label":"Install yt-dlp (brew)"}]}}
---

# YouTube Pro

Advanced YouTube transcript processing with multi-language support, flexible output formats, AI summarization, and batch processing capabilities.

## Quick Start

### Basic Usage
```bash
python scripts/fetch_transcript.py "https://youtube.com/watch?v=VIDEO_ID"

Specify Language

python scripts/fetch_transcript.py "URL" --lang zh-Hans    # 简体中文
python scripts/fetch_transcript.py "URL" --lang en        # English
python scripts/fetch_transcript.py "URL" --lang ja        # 日本語

With Timestamps

python scripts/fetch_transcript.py "URL" --format timestamped

AI Summary

python scripts/summarize.py "URL" --lang zh-Hans --sections 5

Core Features

1. Multi-Language Support

• Auto-detect available subtitle languages
• Specify preferred language with --lang
• Support for auto-generated and manual subtitles
• Auto-translate to target language (optional)

2. Output Formats

• text - Clean plain text (default)
• timestamped - With clickable timestamps [HH:MM:SS]
• json - Structured data for programmatic use
• srt - Standard subtitle format
• markdown - Formatted document with sections

3. Language Detection

python scripts/detect_languages.py "URL"
# Returns available languages with codes

4. AI Summarization

python scripts/summarize.py "URL" --sections 5 --lang zh-Hans
# Generates section-by-section summary

5. Keyword Search

python scripts/search_keywords.py "URL" --keywords "machine learning" "AI"
# Returns matches with timestamps

6. Batch Processing

python scripts/batch_process.py --playlist "PLAYLIST_URL" --output-dir ./output/
python scripts/batch_process.py --urls-file urls.txt --output-dir ./output/

Scripts Reference

Output Format Examples

Text Format (default)

Welcome to this video on machine learning.
Today we'll cover the fundamentals of neural networks.
First, let's understand what a perceptron is.

Timestamped Format

[00:00:15] Welcome to this video on machine learning.
[00:00:23] Today we'll cover the fundamentals of neural networks.
[00:00:31] First, let's understand what a perceptron is.

JSON Format

{
  "video_id": "VIDEO_ID",
  "title": "Video Title",
  "language": "en",
  "subtitles": [
    {"start": 15.0, "end": 20.0, "text": "Welcome to this video..."},
    {"start": 23.0, "end": 28.0, "text": "Today we'll cover..."}
  ]
}

Language Codes

Common language codes:

• en - English
• zh-Hans - 简体中文 (Simplified Chinese)
• zh-Hant - 繁體中文 (Traditional Chinese)
• ja - 日本語 (Japanese)
• ko - 한국어 (Korean)
• es - Español (Spanish)
• fr - Français (French)
• de - Deutsch (German)
• pt - Português (Portuguese)
• ru - Русский (Russian)

See references/language_codes.md for complete list.

Requirements

• Python 3.8+
• yt-dlp (installed via pip or brew)
• Internet connection

Error Handling

Notes

• Works with videos that have closed captions (CC) or auto-generated subtitles
• Auto-generated subtitles may have lower accuracy
• If a video has no subtitles, the script will fail with an error message
• For best results, use videos with manually created captions

### 第三步：编写脚本文件

创建 `scripts/fetch_transcript.py`：

```python
#!/usr/bin/env python3
"""
Fetch YouTube transcript with multi-language support.
"""

import argparse
import json
import subprocess
import sys
from pathlib import Path


def check_yt_dlp():
    """Check if yt-dlp is installed."""
    try:
        subprocess.run(['yt-dlp', '--version'], capture_output=True, check=True)
        return True
    except (subprocess.CalledProcessError, FileNotFoundError):
        return False


def detect_languages(video_url):
    """Detect available subtitle languages for a video."""
    cmd = [
        'yt-dlp',
        '--list-subs',
        '--skip-download',
        video_url
    ]
    result = subprocess.run(cmd, capture_output=True, text=True)
    return result.stdout


def fetch_transcript(video_url, lang='en', format_type='text', output_file=None):
    """Fetch transcript from YouTube video."""
    
    if not check_yt_dlp():
        print("Error: yt-dlp not found. Install with: pip install yt-dlp")
        sys.exit(1)
    
    # Build yt-dlp command
    cmd = [
        'yt-dlp',
        '--skip-download',
        '--write-subs',
        '--sub-lang', lang,
        '--sub-format', 'json3',
        '--output', '%(title)s.%(ext)s',
        video_url
    ]
    
    try:
        result = subprocess.run(cmd, capture_output=True, text=True, check=True)
        # Process and format output
        transcript = process_transcript(result.stdout, format_type)
        
        if output_file:
            with open(output_file, 'w', encoding='utf-8') as f:
                f.write(transcript)
            print(f"Transcript saved to {output_file}")
        else:
            print(transcript)
            
    except subprocess.CalledProcessError as e:
        print(f"Error fetching transcript: {e}")
        sys.exit(1)


def process_transcript(raw_data, format_type):
    """Process raw transcript data into desired format."""
    # Implementation depends on your specific needs
    pass


def main():
    parser = argparse.ArgumentParser(
        description='Fetch YouTube transcript with multi-language support'
    )
    parser.add_argument('url', help='YouTube video URL')
    parser.add_argument(
        '--lang', '-l',
        default='en',
        help='Subtitle language (default: en)'
    )
    parser.add_argument(
        '--format', '-f',
        choices=['text', 'timestamped', 'json', 'srt', 'markdown'],
        default='text',
        help='Output format (default: text)'
    )
    parser.add_argument(
        '--output', '-o',
        help='Output file path'
    )
    
    args = parser.parse_args()
    fetch_transcript(args.url, args.lang, args.format, args.output)


if __name__ == '__main__':
    main()

第四步：创建参考文档

创建 references/language_codes.md：

# Language Codes Reference

Complete list of supported language codes for YouTube subtitles.

## Common Languages

| Code | Language | Native Name |
|------|----------|-------------|
| `en` | English | English |
| `zh-Hans` | Chinese (Simplified) | 简体中文 |
| `zh-Hant` | Chinese (Traditional) | 繁體中文 |
| `ja` | Japanese | 日本語 |
| `ko` | Korean | 한국어 |
| `es` | Spanish | Español |
| `fr` | French | Français |
| `de` | German | Deutsch |
| `pt` | Portuguese | Português |
| `ru` | Russian | Русский |

## All Supported Languages

[Complete list of 50+ languages...]

第五步：编写用户文档

创建 README.md：

# YouTube Pro

> Advanced YouTube transcript extraction and processing toolkit with multi-language support, flexible output formats, AI summarization, and batch processing capabilities.

![Version](https://img.shields.io/badge/version-1.0.0-blue)
![Python](https://img.shields.io/badge/python-3.8+-green)
![License](https://img.shields.io/badge/license-MIT-blue)

## Features

| Feature | Description |
|---------|-------------|
| 🌍 **Multi-language** | Support 50+ languages with auto-translate capability |
| 📝 **Multiple Formats** | Text, JSON, SRT, Markdown, with optional timestamps |
| 🔍 **Keyword Search** | Search transcripts with context and timestamp results |
| 📊 **AI Summarization** | Generate section-by-section summaries |
| 📦 **Batch Processing** | Process entire playlists or video lists |

## Installation

```bash
# Install dependency
pip install yt-dlp

# Clone repository
git clone https://github.com/HAxiaoyu/youtube-pro.git
cd youtube-pro

Quick Start

# Fetch transcript
python scripts/fetch_transcript.py "https://youtube.com/watch?v=VIDEO_ID"

# Specify language
python scripts/fetch_transcript.py "URL" --lang zh-Hans

# With timestamps
python scripts/fetch_transcript.py "URL" --format timestamped

[More documentation…]

## Skill 编写最佳实践

### 1. 触发词设计

触发词是 Skill 被调用的关键。设计原则：

- **具体明确**：避免过于宽泛的词
- **覆盖场景**：包含用户可能使用的各种表达方式
- **避免冲突**：不要与其他 Skill 的触发词重叠

**youtube-pro 的触发词示例：**

```json
"triggers": [
  "youtube transcript",
  "video summary",
  "download subtitles",
  "youtube playlist",
  "video timestamp",
  "extract quotes",
  "youtube search",
  "anki cards from video"
]

2. 描述撰写技巧

description 字段是 Skill 触发的主要机制。要点：

• 说明功能：清晰描述 Skill 能做什么
• 指定场景：说明在什么情况下使用
• 适度"激进"：Claude 倾向于少用 Skill，描述可以稍微"pushy"一些

好例子：

Advanced YouTube transcript extraction with multi-language support. 
Use for any YouTube video analysis task requiring more than basic 
transcript fetching. Triggers on: youtube transcript, video summary...

差例子：

YouTube transcript tool.

3. 渐进式披露

Skill 使用三层加载系统：

1. 元数据（~100 词）：始终在上下文中
2. SKILL.md 正文（<500 行）：Skill 触发时加载
3. 捆绑资源：按需加载

建议：

• 保持 SKILL.md 在 500 行以内
• 大文件拆分成参考文档
• 脚本可以执行而不加载到上下文

4. 脚本化重复任务

如果多个测试用例都涉及相同的操作，将其脚本化：

# scripts/create_docx.py
# 自动生成 Word 文档的脚本

# scripts/build_chart.py  
# 自动生成图表的脚本

在 SKILL.md 中引用：

### Generate Report

Use the bundled script:

```bash
python scripts/create_docx.py --input data.json --output report.docx

### 5. 错误处理说明

在 SKILL.md 中包含常见错误和解决方案：

```markdown
## Error Handling

| Error | Cause | Solution |
|-------|-------|----------|
| "No subtitles found" | Video has no captions | Try `--auto-translate` |
| "yt-dlp not found" | Missing dependency | Run `pip install yt-dlp` |
| "Invalid URL" | Malformed YouTube URL | Check URL format |

测试和优化 Skill

创建测试用例

创建 evals/evals.json：

{
  "skill_name": "youtube-pro",
  "evals": [
    {
      "id": 1,
      "prompt": "帮我下载这个 YouTube 视频的中文字幕：https://youtube.com/watch?v=xxx",
      "expected_output": "包含完整字幕的文本文件",
      "files": []
    },
    {
      "id": 2,
      "prompt": "总结这个视频的主要内容，分成 5 个部分",
      "expected_output": "包含 5 个部分摘要的 Markdown 文档",
      "files": []
    },
    {
      "id": 3,
      "prompt": "搜索视频中提到 'machine learning' 的所有片段，带时间戳",
      "expected_output": "包含时间戳和上下文的搜索结果",
      "files": []
    }
  ]
}

运行测试

使用 skill-creator 技能运行测试：

1. 为每个测试用例创建子代理运行
2. 一个有 Skill 访问权限，一个没有（基线对比）
3. 收集输出结果
4. 用户审查并给出反馈
5. 根据反馈迭代优化

优化描述

使用描述优化循环：

1. 生成 20 个测试查询（应该触发和不应该触发的混合）
2. 运行优化循环，自动调整描述
3. 选择在测试集上表现最好的描述
4. 更新 SKILL.md 的 frontmatter

Skill 目录

当前项目中已有的 Skill：

总结

创建 Skill 的核心步骤：

1. 定义意图：明确 Skill 要解决的问题
2. 设计结构：规划项目结构和文件组织
3. 编写 SKILL.md：核心指令和触发条件
4. 创建脚本：自动化重复任务
5. 编写文档：用户指南和参考文档
6. 测试优化：运行测试用例，迭代改进

一个好的 Skill 应该：

• ✅ 触发准确：在正确的场景下被调用
• ✅ 指令清晰：Claude 能准确理解要做什么
• ✅ 输出稳定：多次运行结果一致
• ✅ 文档完善：用户知道如何使用

通过 youtube-pro 这个实际案例，你应该已经掌握了创建 Skill 的完整流程。现在，开始打造属于你自己的 AI 工作流吧！

参考链接

• youtube-pro GitHub 仓库
• OpenClaw 官方文档
• skill-creator Skill 源码

本文由 OpenClaw 协助编写 🤖