Claude Code 技能开发：用 SKILL.md 打造文字转音频 TTS 工具

1. 为什么要把 TTS 塞进 Claude Code 技能里文字转音频这件事单独写个 Python 脚本并不难难的是每次都要重复一套动作找脚本路径、确认虚拟环境、回忆参数名、手动拼输出文件名。写文章要配音、做视频要旁白、给播客剪一段片头每次都得回到终端里敲一遍命令时间全耗在“调用”而不是“创作”上。Claude Code 的技能系统Skill解决的正是这个断层。它允许你把一个能力写成SKILL.md加一个执行脚本之后用自然语言就能触发。你不再需要记住--voice还是-v也不用关心底层是哪个 TTS 服务只要说“把这段文字转成音频”Claude 会自己解析参数、调用脚本、把结果路径返回给你。这篇聚焦的是 Claude Code 技能开发流程落地场景选文字转音频 TTS。我会先讲清楚技能目录长什么样再给一份可以直接复制的SKILL.md骨架然后接上 TaoToken 的统一 Key/API 通道完成真实调用最后跑一次端到端验证把“技能定义 → 参数解析 → 音频输出”这条链路走通。适合已经在用 Claude Code、想把自己的小工具沉淀成技能的人也适合刚接触 Skill 机制、想找一个完整案例照着做的开发者。核心检索词先摆出来Claude Code 技能开发、SKILL.md 编写、文字转音频 TTS、TaoToken 统一 API 通道。下面所有步骤都可以跟做代码块直接复制即可。2. 前置准备TaoToken 统一 Key 与技能目录2.1 为什么用 TaoToken 做 TTS 通道TTS 服务如果每家都单独接Key 管理会变成灾难这个项目用 A 家的语音那个脚本用 B 家的接口环境变量里塞一堆XXX_API_KEY。TaoToken 提供的是 OpenAI 兼容的统一通道一个 Key 就能覆盖对话、语音等多种能力接口路径也统一在https://taotoken.net/api下。对技能开发来说这意味着tts.py里只需要维护一套请求逻辑换模型或换音色时改的是参数不是整套鉴权代码。官网入口在这里注册和查看文档都从这进https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 基址单独记一下脚本里会用到https://taotoken.net/api2.2 拿到 API Key登录后进入控制台在 API Keys 页面创建一个新 Key。建议按用途命名比如claude-code-tts方便以后排查是哪个技能在消耗额度。创建后立刻复制保存页面刷新后就看不到完整 Key 了。创建 Key 的直达入口https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content拿到 Key 之后不要写死在脚本里用环境变量注入。Linux/macOS 下可以写进~/.zshrc或~/.bashrcexport TAOTOKEN_API_KEYsk-你的Key export TAOTOKEN_BASE_URLhttps://taotoken.net/apiWindows PowerShell 用$env:TAOTOKEN_API_KEYsk-你的Key $env:TAOTOKEN_BASE_URLhttps://taotoken.net/api2.3 技能目录结构Claude Code 的技能放在用户级目录下每个技能一个文件夹。TTS 技能的目录长这样~/.claude/skills/tts-audio/ ├── SKILL.md # 技能描述告诉 Claude 这个技能能做什么、参数怎么传 └── tts.py # 执行脚本真正调用 TaoToken 接口并落盘音频SKILL.md是给 Claude 看的“说明书”tts.py是给机器执行的“手脚”。两者分工明确前者负责语义理解后者负责具体请求。很多人第一次写技能会把逻辑全塞进SKILL.md结果 Claude 解析得很吃力正确做法是把参数定义写清楚把执行细节留给脚本。3. 可复制配置SKILL.md 骨架与 tts.py 实现3.1 SKILL.md 完整骨架SKILL.md用 YAML front matter 定义元信息正文部分描述参数、示例和注意事项。下面这份可以直接复制改掉 name 和 description 就能用--- name: tts-audio description: 文字转音频技能 - 通过 TaoToken 统一通道调用 TTS将文本合成为 WAV 音频文件 --- # TTS 文字转音频 将输入文本合成为音频文件输出 WAV 格式采样率 24kHz。 ## 使用方式 /tts-audio 文本 [--voice 音色] [--output 文件名] [--file 输入文件] ## 参数说明 - 文本必填要转换的文字内容建议单段不超过 500 字 - --voice可选音色名称默认 alloy - --output可选输出文件名默认按时间戳生成 - --file可选从文本文件读取内容与直接传文本二选一 ## 示例 /tts-audio 你好欢迎使用文字转音频技能 /tts-audio 今天天气真好 --voice nova --output weather.wav /tts-audio --file chapter1.txt --output chapter1.wav ## 注意事项 - API Key 从环境变量 TAOTOKEN_API_KEY 读取不要写进脚本 - 接口基址为 https://taotoken.net/api - 长文本请分段处理每段控制在 500 字以内 - 输出目录默认为当前工作目录这份骨架的关键点在于description里写清楚“通过 TaoToken 统一通道”Claude 在匹配用户意图时能更准地命中参数说明逐项列出默认值避免 Claude 自己猜示例覆盖了直接传文本、指定音色、从文件读取三种常见场景。3.2 tts.py 执行逻辑脚本负责读取环境变量、构造 OpenAI 兼容请求、接收音频流并写入文件。TaoToken 的语音接口遵循 OpenAI 规范所以请求体结构和官方一致import os import sys import time import argparse import requests API_KEY os.environ.get(TAOTOKEN_API_KEY) BASE_URL os.environ.get(TAOTOKEN_BASE_URL, https://taotoken.net/api) def synthesize(text, voice, output): if not API_KEY: print(错误未设置 TAOTOKEN_API_KEY 环境变量) sys.exit(1) url f{BASE_URL}/v1/audio/speech headers { Authorization: fBearer {API_KEY}, Content-Type: application/json, } payload { model: tts-1, input: text, voice: voice, response_format: wav, } resp requests.post(url, headersheaders, jsonpayload, streamTrue, timeout120) if resp.status_code ! 200: print(f请求失败{resp.status_code} {resp.text}) sys.exit(1) with open(output, wb) as f: for chunk in resp.iter_content(chunk_size8192): if chunk: f.write(chunk) size os.path.getsize(output) print(f生成成功{output}{size} 字节) def main(): parser argparse.ArgumentParser() parser.add_argument(text, nargs?, default) parser.add_argument(--voice, defaultalloy) parser.add_argument(--output, default) parser.add_argument(--file, default) args parser.parse_args() text args.text if args.file: with open(args.file, r, encodingutf-8) as f: text f.read() if not text.strip(): print(错误没有可转换的文本) sys.exit(1) output args.output or ftts_{int(time.time())}.wav synthesize(text, args.voice, output) if __name__ __main__: main()脚本里几个设计点值得说明。streamTrue配合iter_content是为了处理较长音频避免一次性把整个响应读进内存。response_format设为wav落盘后可以直接播放不需要额外转码。默认输出文件名带时间戳防止多次调用互相覆盖。3.3 settings.json 配置片段如果你希望技能在特定项目里自动可用可以在项目的.claude/settings.json里声明技能路径。全局技能放在~/.claude/skills/下即可不需要额外配置。项目级配置片段如下{ skills: { paths: [ ~/.claude/skills/tts-audio ] } }这段配置的作用是告诉 Claude Code 去哪里加载技能。如果你把技能放在项目内的.claude/skills/目录把路径改成相对路径即可。配置完成后重启 Claude Code 会话技能才会被重新扫描。4. 验证请求跑通一次端到端调用4.1 先单独测脚本在接入 Claude Code 之前先确认脚本本身能跑通。这一步能帮你把环境变量、网络、Key 的问题提前排掉cd ~/.claude/skills/tts-audio python tts.py 你好这是一段测试音频 --voice alloy --output test.wav预期输出生成成功test.wav48210 字节如果看到文件大小说明请求链路是通的。用播放器打开test.wav能听到声音就说明 TTS 合成正常。这一步失败的话先检查TAOTOKEN_API_KEY是否生效可以用echo $TAOTOKEN_API_KEY确认。4.2 在 Claude Code 里触发技能脚本验证通过后回到 Claude Code 会话直接输入自然语言指令/tts-audio 欢迎来到本期节目今天我们聊聊技能开发Claude 会解析出文本内容调用tts.py并把生成的文件路径返回给你。如果你想指定音色和输出名/tts-audio 这是一段产品介绍旁白 --voice nova --output intro.wav从文件读取的用法/tts-audio --file article.txt --output narration.wav4.3 成功结果长什么样一次完整的调用Claude 返回的信息通常包含三部分识别到的参数、执行的命令、生成的文件路径。你会在会话里看到类似这样的反馈已调用 tts-audio 技能 参数voicealloy, outputintro.wav 结果生成成功文件位于 /Users/you/intro.wav128400 字节到这一步从技能定义到音频输出的完整链路就跑通了。你可以打开文件确认音质也可以把这段指令固化成一个常用命令下次直接复用。5. 本篇常见错排查5.1 技能没有被识别输入/tts-audio后 Claude 没有反应或者提示找不到技能。先确认目录名和SKILL.md里的name是否一致两者必须匹配。其次检查技能目录是否在~/.claude/skills/下路径层级不能多也不能少。最后重启一次 Claude Code 会话技能是在启动时扫描的新增技能不会热加载。5.2 请求返回 401401 基本是 Key 的问题。确认TAOTOKEN_API_KEY已经 export 到当前 shell并且 Claude Code 是从同一个 shell 启动的。如果你在 IDE 里启动 Claude Code环境变量可能没有继承需要在 IDE 的终端配置里补上。另外检查 Key 是否被删除或过期去控制台确认一下状态。5.3 返回 404 或路径错误404 通常是接口路径拼错了。TaoToken 的语音接口路径是/v1/audio/speech基址是https://taotoken.net/api拼起来就是https://taotoken.net/api/v1/audio/speech。如果你在BASE_URL里多写了/v1就会变成/v1/v1/...直接 404。检查环境变量里有没有多余的路径段。5.4 音频文件为空或无法播放文件大小为 0说明响应体没有正确写入。先看resp.status_code是不是 200非 200 时脚本会打印错误信息。如果状态码正常但文件为空检查iter_content的 chunk 是否被正确写入以及文件是否以二进制模式打开。另一个常见原因是输出路径的目录不存在open会直接报错确认目标目录已经创建。5.5 长文本合成失败或截断单次请求文本过长时部分服务会返回错误或只合成前半段。建议在技能层面做分段每段控制在 500 字以内。你可以在tts.py里加一个简单的分段逻辑按句号或换行切分逐段请求后拼接音频。如果不想改脚本也可以在 Claude Code 里手动分段调用Claude 会记住上下文保持音色一致。6. 把技能沉淀成可复用资产技能开发的价值不在于写一次脚本而在于把重复动作变成一句话就能触发的能力。TTS 只是一个例子同样的结构可以套到图片处理、文档转换、数据抓取上SKILL.md负责语义层执行脚本负责动作层TaoToken 负责统一通道。如果你后续想把这个技能接到更长的编码或 Agent 工作流里比如让 Claude 自动为生成的文档配音、再合成视频可以考虑用 Coding Plan 来管理长期的调用额度入口在这里https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content想先验证模型对话和语音能力是否正常可以直接在模型对话页测试https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content接入文档里有完整的接口说明和参数列表写新技能时对照着看https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content如果你在用 Claude Code 的 Anthropic 兼容模式配置方式参考这份说明https://taotoken.net/ClaudeCodeAnthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content技能写完只是开始真正省时间的是把它用起来。下次要配音时别再翻脚本了直接一句话交给 Claude。