什么是 SKILL.md 文件？

SKILL.md 是一种机器可读的指令文档，告诉 AI 编程代理（Claude Code、OpenClaw、Codex）如何执行特定任务。它定义了输入、执行步骤和预期输出。

使用 AI 代理技能需要编程经验吗？

有基本的命令行工具使用经验会有帮助，但许多技能可以用简单的自然语言命令调用。代理会处理技术执行细节。

代理能调用外部 API 吗？

可以。代理技能可以包含对 Seedance、ElevenLabs、YouTube 等服务的 API 调用。代理处理认证、请求格式和响应解析。

代理技能免费吗？

代理工具本身可能有免费版（如 Claude Code 免费版）。但调用付费 API 的技能（视频生成、语音合成）会产生相应的 API 费用。

能和别人分享技能吗？

可以。SKILL.md 文件是纯文本，可通过 Git 仓库、npm 包或直接文件分享。GitHub 上有许多社区技能可用。

AI 代理技能：自动化你的整个视频制作流水线

Q: 哪些 AI 代理支持 SKILL.md？

Claude Code（Anthropic）、OpenClaw 和 GitHub Codex 支持 SKILL.md 格式的技能定义。该格式设计为与代理无关。

Q: 如何调试失败的技能？

检查代理输出日志中的错误信息，验证环境变量（API 密钥），独立测试 API 端点，确保输入参数匹配技能规格。

AI 视频制作涉及数十个重复步骤：编写脚本、生成图片、创建视频片段、合成音频、添加元数据、上传到平台。每个步骤都有自己的工具、API 和配置。AI 代理技能将这些步骤转化为可执行、可重复的指令，让编码代理只需一个命令就能代替你完成全部工作。

本指南介绍代理技能的概念、工作原理，以及如何使用 Claude Code 和 OpenClaw 搭建自动化视频流水线。

什么是 AI 代理技能？

AI 代理技能是一种机器可读的指令文件（通常命名为 SKILL.md），它告诉 AI 编码代理如何执行特定任务。你可以把它理解为一份配方：它声明所需的输入、要遵循的步骤、要调用的工具以及预期的输出。代理读取该文件，解析指令，然后自主完成工作。

技能文件和传统脚本或 Shell 命令有本质区别。Shell 脚本执行固定的操作序列，而技能文件由 AI 代理解释执行——代理能够自适应、处理边缘情况、在你定义的边界内做出决策，并将 API 调用、文件操作和 CLI 命令串联起来，无需你编写胶水代码。代理本身就是运行时。

SKILL.md 格式被多个 AI 编码代理支持，包括 Claude Code、OpenClaw 和 Codex CLI。每个代理都读取相同的文件格式，这意味着技能可以跨工具移植。你只需编写一次技能，就能在任何安装了兼容代理的环境中运行。

代理技能的工作原理

代理技能的执行流程遵循一个可预测的模式：

用户触发技能。 你通过名称调用技能——在 Claude Code 中使用斜杠命令（如 /seedance-video-generator），或在 OpenClaw 的平台界面中操作。
代理读取 SKILL.md 文件。 代理在配置的技能目录中定位技能文件，解析前置元数据，并读取指令正文。
代理规划执行。 根据指令内容，代理确定需要哪些工具（API 调用、文件读写、CLI 命令、浏览器操作）以及执行顺序。如果缺少必要输入，代理会提示你补充。
代理执行步骤。 代理逐步完成工作：调用 API、将文件写入磁盘、运行 Shell 命令、处理数据，并按技能文件中的规定处理错误。
代理返回结果。 所有步骤完成后，代理呈现输出结果（生成的视频文件、元数据 JSON、一组缩略图），并报告执行过程中遇到的问题。

关键优势在于可组合性。你可以将技能串联起来，让一个技能的输出成为下一个技能的输入。脚本转分镜技能生成镜头列表，镜头列表传入视频生成技能，生成的片段传入剪辑技能，剪辑完成的视频传入元数据和上传技能。每个技能都是独立的单元，代理负责编排整个链条。

可用的视频制作技能

以下技能覆盖了 AI 视频制作流水线的核心阶段。你可以单独使用它们，也可以串联使用实现端到端自动化。

技能名称	描述	输入	输出	复杂度
`seedance-video-generator`	使用 Seedance 2.0 API 从文本或图片提示词生成视频片段	提示词文本或图片路径、宽高比、时长	MP4 视频文件、生成元数据	中等
`youtube-metadata-generator`	为 YouTube 上传创建优化的标题、描述、标签和缩略图	视频文件或主题摘要、目标关键词	JSON 元数据文件、缩略图图片	低
`batch-thumbnail-processor`	批量生成和调整多个视频的缩略图	视频文件目录、模板配置	每个视频对应的缩略图图片（PNG/JPG）	低
`script-to-storyboard`	将书面脚本转换为包含视觉描述的结构化镜头列表	脚本文本（纯文本或 MDX）	JSON 镜头列表，含场景描述、机位角度、时长	中等
`audio-narration-generator`	使用文本转语音 API 从脚本文本生成配音旁白	脚本文本、语音选择、节奏配置	MP3/WAV 音频文件、SRT 字幕文件	中等
`video-review-checklist`	对成品视频在发布前运行自动化质量检查	视频文件路径	质量报告（分辨率、音频电平、时长、格式验证）	低
`social-media-repurposer`	将长视频重新裁剪为适合 Shorts、Reels 和 TikTok 的短片	源视频文件、目标平台	每个平台对应的裁剪/截取片段	高
`seo-description-writer`	为视频页面和博客文章撰写 SEO 优化描述	视频主题、目标关键词、语调	Markdown 描述及结构化数据建议	低

每个技能都是独立的 SKILL.md 文件。你可以只安装需要的技能，并随着工作流的演进逐步添加更多技能。

使用 Claude Code 开始

Claude Code 是 Anthropic 推出的 CLI 工具，用于在终端中运行 AI 代理。以下是设置视频制作技能的步骤。

第一步：安装 Claude Code。

如果你还没有安装 Claude Code，可以通过 npm 全局安装：

npm install -g @anthropic-ai/claude-code

在终端中运行 claude --version 验证安装是否成功。

第二步：创建技能目录。

Claude Code 在项目或主目录的 .claude/skills/ 目录中查找技能文件。如果该目录不存在，请创建：

mkdir -p .claude/skills

第三步：添加 SKILL.md 文件。

将每个技能文件放入技能目录。例如，添加视频生成技能：

.claude/skills/
  seedance-video-generator/
    SKILL.md
  youtube-metadata-generator/
    SKILL.md
  script-to-storyboard/
    SKILL.md

每个子目录包含一个 SKILL.md 文件，内含该技能的完整指令。

第四步：配置环境变量。

大多数视频制作技能需要 API 密钥。在 Shell 配置文件或 .env 文件中设置：

export SEEDANCE_API_KEY="your-seedance-api-key"
export ELEVENLABS_API_KEY="your-elevenlabs-api-key"
export YOUTUBE_API_KEY="your-youtube-api-key"

第五步：调用技能。

启动 Claude Code 并按名称触发技能：

claude
> /seedance-video-generator

Claude Code 读取 SKILL.md，询问所需输入（提示词文本、宽高比），然后执行流水线。生成的视频保存到配置的输出目录。

使用 OpenClaw 开始

OpenClaw 是一个开源平台，通过 Web 界面和 CLI 管理和运行 AI 代理技能。它提供技能注册表、执行历史和团队协作功能。

第一步：安装 OpenClaw CLI。

npm install -g openclaw

第二步：初始化工作空间。

openclaw init

这会在项目中创建 openclaw.config.json 文件和 skills/ 目录。

第三步：从注册表导入技能。

OpenClaw 维护了一个公共注册表，包含社区贡献的技能。可以直接导入视频制作技能：

openclaw install seedance-video-generator
openclaw install youtube-metadata-generator
openclaw install script-to-storyboard

第四步：运行技能。

openclaw run seedance-video-generator --prompt "无人机俯拍金色夕阳下的海滨城市"

OpenClaw 还支持在流水线配置文件中串联技能，让你以声明式方式定义多步骤工作流。

创建自定义技能

每个 SKILL.md 文件遵循一致的格式，包含前置元数据和指令正文。以下是具体结构。

前置元数据：

---
name: my-custom-skill
description: 简要说明此技能的功能
version: 1.0.0
inputs:
  - name: prompt
    type: string
    required: true
    description: 视频生成的文本提示词
  - name: aspect_ratio
    type: string
    required: false
    default: "16:9"
    description: 输出宽高比
outputs:
  - name: video_file
    type: file
    description: 生成的 MP4 视频
---

指令正文：

在前置元数据之后，用纯 Markdown 编写执行步骤。代理会按顺序解析这些指令并执行。

## 执行步骤

1. 验证 `prompt` 输入至少包含 10 个字符。如果不足，请用户提供更详细的提示词。

2. 调用 Seedance 2.0 API 文生视频端点：
   - 端点：`POST https://api.seedance.ai/v2/generate/text`
   - 在请求体中包含 prompt、aspect_ratio 和 duration（默认 4 秒）。
   - 使用 SEEDANCE_API_KEY 环境变量进行身份验证。

3. 每 5 秒轮询一次任务状态端点，直到状态为 "completed" 或 "failed"。

4. 如果生成成功，从 `video_url` 字段下载视频并保存到 `./output/{timestamp}-generated.mp4`。

5. 向用户返回文件路径和生成元数据（任务 ID、时长、分辨率）。

## 错误处理

- 如果 API 返回 429 限速错误，等待 30 秒后重试，最多重试 3 次。
- 如果生成失败，报告错误信息并建议用户简化提示词。

## 参考资料

- [Seedance 2.0 API 文档](/blog/seedance-2-0-api)
- [提示词编写指南](/blog/seedance-prompt-guide)

核心原则是清晰。编写指令时，要像向一位能力强但从未接触过你代码库的开发者解释任务一样。明确写出 API 端点、文件路径、错误处理规则和预期输出。

实际自动化案例

独立创作者：每日 YouTube Shorts 自动化

一位独立创作者每天制作一条 YouTube Short。流水线涉及编写脚本、生成视频片段、添加配音、创建缩略图和上传优化后的元数据。

没有技能自动化时，每个视频需要 2-3 小时的手动工作。使用技能链后，创作者只需运行一条命令：

claude
> 运行我的 daily-short 流水线，今天的主题是："3 个提升 AI 提示词质量的技巧"

代理执行技能链：script-to-storyboard 生成镜头列表，seedance-video-generator 创建视频片段，audio-narration-generator 添加配音，youtube-metadata-generator 生成标题和标签，创作者在最终上传前审核输出。实际操作时间缩短到约 15 分钟的审核和确认。

代理机构：为客户批量制作视频

一家视频营销机构每周为多个客户制作 20-30 条短视频。每个客户都有品牌规范、偏好风格和目标平台。

机构为每个客户创建专属技能配置，包含品牌色、Logo 叠加层、语调设置和平台目标。项目经理触发批量生成：

openclaw run batch-pipeline --config clients/acme-corp.json --count 5

代理按照 ACME Corp 的品牌规范生成五个视频，创建不同平台的裁剪版本（16:9 用于 YouTube，9:16 用于 Shorts 和 Reels），并为每个平台生成元数据。团队在 OpenClaw 仪表板中审核输出，确认后交付客户。

开发者：API 驱动的流水线与 Webhook 触发

一位开发者将视频生成集成到 SaaS 产品中。当用户通过 Web 应用提交提示词时，Webhook 触发视频流水线。

开发者编写一个技能，监听传入的 Webhook 请求、验证数据、通过 Seedance API 生成视频、将结果上传到云存储，并向用户发送通知。技能作为代理管理的后台任务运行，错误处理和重试逻辑在 SKILL.md 文件中定义。

Webhook 接收 → 验证请求 → 生成视频 → 上传到 S3 → 通知用户

这种方式将流水线逻辑保存在可读、可维护的技能文件中，而不是埋藏在应用代码里。

局限性与最佳实践

代理无法做到的事情

AI 代理是强大的执行者，但在视频制作场景中存在真实的局限：

主观创意判断。 代理可以根据提示词生成视频，但无法判断结果在审美上是否优秀。创意质量仍然需要人工审核。
实时监控。 代理执行任务并返回结果，不会实时观察渲染过程。长时间运行的任务依赖轮询或回调机制。
复杂剪辑决策。 将 10 分钟的视频剪辑为 60 秒的精华片段需要编辑判断力，代理无法可靠地提供。使用代理处理机械性剪辑任务（裁剪、缩放、格式转换），而非创意性剪辑。
平台特定细节。 每个社交媒体平台对内容、格式和元数据都有不断变化的规则。代理按照技能文件中的指令执行，因此你需要随着平台变化更新技能。

最佳实践

版本控制你的技能。 将 SKILL.md 文件纳入版本控制。当你更新 API 端点或修改工作流步骤时，变更可追踪且可回滚。
增量测试。 在串联技能之前，先单独运行每个技能。验证相连技能之间的输入和输出是否匹配。
保持技能专注。 单个技能应该做好一件事。三个专注的技能串联优于一个试图处理整个流水线的臃肿技能。
定义清晰的错误处理。 明确说明 API 调用失败、文件缺失或输入无效时应该怎么做。代理会严格按照你的错误处理指令执行。
使用环境变量管理密钥。 永远不要在 SKILL.md 文件中硬编码 API 密钥。引用环境变量并记录每个技能需要哪些密钥。
记录你的输入和输出。 清晰的前置元数据让技能具有自文档性。其他团队成员（或未来的你）应该仅通过前置元数据就能理解技能的功能。
发布前审核代理输出。 自动化生成和准备工作，但在最终发布步骤保留人工审核。这能发现质量问题并防止意外上传。

常见问题

SKILL.md 文件是什么？

SKILL.md 文件是一个 Markdown 文档，包含 AI 编码代理可读的指令。它声明了技能名称、描述、所需输入、预期输出和逐步执行指令。代理读取该文件并执行其中描述的工作。

我需要编程经验吗？

具备命令行和环境变量的基本知识会有帮助，但你不需要成为程序员。SKILL.md 文件用纯 Markdown 编写，指令清晰明了。如果你能看懂一份食谱，就能编写和使用技能。对于更高级的定制（自定义 API 集成、Webhook 处理），一些开发经验会比较有用。

哪些 AI 代理支持 SKILL.md？

Claude Code（Anthropic 出品）、OpenClaw 和 Codex CLI 都支持 SKILL.md 格式。核心文件结构在各代理间一致，但每个代理可能有额外的功能或配置选项。为一个代理编写的技能通常只需少量调整即可在其他代理中使用。

代理可以调用外部 API 吗？

可以。代理可以向你配置的任何 API 发送 HTTP 请求，包括 Seedance、ElevenLabs、YouTube Data API、云存储服务等。你在 SKILL.md 文件中指定 API 端点和认证方式，代理负责处理请求。

如何调试失败的技能？

首先检查代理的输出日志中的错误信息。常见问题包括缺少环境变量（API 密钥未设置）、API 端点不正确以及输入数据格式错误。将失败的步骤单独运行以缩小问题范围。大多数代理支持详细日志模式，会显示每个步骤的执行过程。

使用代理技能需要付费吗？

代理工具本身有不同的定价方案。Claude Code 需要 Anthropic API 订阅。OpenClaw 为个人用户提供免费层级。技能文件本身只是指令文件，不需要费用。但技能调用的底层服务（Seedance API、ElevenLabs、YouTube API）有各自的定价。总费用取决于你的技能调用了哪些 API 以及调用频率。

我可以和别人共享技能吗？

可以。技能是纯 Markdown 文件，你可以通过 Git 仓库、OpenClaw 公共注册表或任何文件共享方式分享。共享的技能应该记录所需的环境变量和 API 依赖，以便其他人正确配置。

继续构建你的 AI 视频制作流水线，参考以下资源：

Seedance 2.0 API：完整集成指南 — Seedance 视频生成 API 的技术参考
Seedance 2.0 教程：完全指南 — 从零开始学习 AI 视频生成
Seedance 提示词指南 — 编写更好的提示词以获得更高质量的视频输出
Seedance 定价详解 — 规划基于 API 的视频生成预算

收藏 AIVidPipeline 获取最新的 AI 视频制作工具、代理技能和自动化工作流资讯。