1. 为什么你的 Claude Skill 总是“差点意思”如果你正在用 Cline、CC Switch 或者 Claude Code 写代码大概率已经接触过 Skill 这个概念。简单说Skill 就是给 Claude 装上一套“可复用的操作手册”——比如“把 PDF 转成 Markdown”“审查 PR 里的安全漏洞”“按团队规范生成 commit message”。它和普通提示词最大的区别是Skill 有目录结构、有元数据、有可执行脚本、有测试用例是一个能被版本管理和迭代的工程产物。但问题也出在这里。很多人第一次写 Skill就是把一段提示词塞进SKILL.md然后发现三个典型症状一是触发不稳定明明该用的时候 Claude 不加载二是输出质量飘忽同一份输入两次结果差很多三是改了一版之后不知道是变好了还是变差了全靠感觉。这三点本质上不是“提示词写得不够好”而是缺少一套从创建、评测到优化的工程化闭环。skill-creator这个插件解决的正是这件事。它把 Skill 的开发过程拆成需求访谈、结构设计、自动化评测、迭代优化、触发调优几个阶段并且用多 Agent 协作的方式把“评分”“分析”“版本对比”这些原本靠人肉判断的环节自动化。我试过用它把一个内部代码审查 Skill 从 58% 的断言通过率拉到 89%整个过程大概跑了四轮迭代每轮都有明确的 benchmark 数据支撑。这篇文章面向的是已经在用 Cline / CC Switch / Claude Code 的开发者目标很具体交付一套可复制的settings.json和config.toml配置骨架演示如何通过 TaoToken 统一 Key 和 API 通道接入然后把“创建 → 评测 → 优化”这条链路完整跑通。你不需要是提示词专家但需要能看懂基本的 Python 和 JSON。2. TaoToken 前置统一 Key 与 API 通道在讲 Skill 工程化之前先把接入层理清楚。skill-creator 在评测阶段会频繁调用模型——并行跑 with_skill 和 baseline 两组任务、生成改进方案、做触发测试这些都会消耗大量请求。如果每个工具各配一套 Key管理成本会很高而且不同工具之间的模型版本容易不一致导致 benchmark 数据不可比。TaoToken 在这里的角色是统一入口一个 Key、一个 API 地址同时服务 Cline、CC Switch、Claude Code 以及 skill-creator 的评测脚本。这样做的直接好处是评测时用的模型和日常编码时用的模型是同一个通道数据不会因为供应商差异而漂移。官网入口在这里https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基地址是 https://taotoken.net/api 注意这个地址不加 UTM 参数直接用于配置。你需要先拿到一个 API Key。进入控制台创建即可https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。创建完成后Key 的管理页面在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 建议给 skill-creator 单独建一个 Key方便后续按项目统计用量。注意Key 只显示一次创建后立刻复制保存。如果丢失只能重新生成旧的会失效。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面列出了不同工具的配置字段对照。下面我直接给出 Cline 和 CC Switch 两套骨架你可以按自己用的工具选一套。3. 可复制配置settings.json 与 config.toml 骨架3.1 Cline 的 settings.jsonCline 的配置走 VS Code 的 settings.json。核心是把 API Provider 指向 TaoToken 的兼容端点并把模型名写成你实际要用的版本。下面这份骨架可以直接粘贴把YOUR_TAOTOKEN_KEY替换成你自己的 Key{ cline.apiProvider: openai, cline.openAiApiKey: YOUR_TAOTOKEN_KEY, cline.openAiBaseUrl: https://taotoken.net/api, cline.openAiModelId: claude-sonnet-4-20250514, cline.openAiModelInfo: { maxTokens: 8192, contextWindow: 200000, supportsImages: true, supportsPromptCache: true }, cline.customInstructions: When creating or modifying Claude Skills, always validate SKILL.md frontmatter before running evals., cline.autoApprovalSettings: { enabled: true, actions: { readFiles: true, editFiles: false, runCommands: false } } }几个字段说明一下。cline.openAiBaseUrl填https://taotoken.net/api不要带尾部斜杠。cline.openAiModelId按你实际订阅的模型填上面写的是 Sonnet 4 的示例。supportsPromptCache建议开skill-creator 的评测脚本会反复读同一份 SKILL.md缓存能省不少 token。autoApprovalSettings里我把editFiles和runCommands关掉了因为 skill-creator 会生成脚本文件自动批准有风险手动确认更稳。3.2 CC Switch 的 config.tomlCC Switch 用 TOML 配置结构更清晰。下面这份骨架覆盖了 provider、模型和 skill-creator 需要的环境变量[provider] name taotoken base_url https://taotoken.net/api api_key YOUR_TAOTOKEN_KEY api_style openai [model] default claude-sonnet-4-20250514 fast claude-haiku-4-20250514 max_tokens 8192 temperature 0.2 [skill_creator] enabled true workspace ./skill-workspace parallel_evals 6 runs_per_query 5 trigger_threshold 0.8 baseline_enabled true [skill_creator.grading] model claude-sonnet-4-20250514 max_thinking_tokens 2000 [env] ANTHROPIC_BASE_URL https://taotoken.net/api ANTHROPIC_API_KEY YOUR_TAOTOKEN_KEY这里有几个参数值得展开。parallel_evals 6对应 skill-creator 的并行评测机制——每个测试用例同时跑 with_skill 和 baseline 两个变体3 个用例就是 6 个并行任务。runs_per_query 5是触发测试的重复次数因为触发有随机性跑 5 次取触发率更可靠。trigger_threshold 0.8表示触发率超过 80% 才算通过低于 20% 才算“不该触发时没触发”。[env]段是关键。skill-creator 的评测脚本底层调用的是 Anthropic SDK它读的是ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY这两个环境变量。把它们指向 TaoToken脚本就能走统一通道不需要改任何代码。3.3 验证配置是否生效配置写完后先做一次最小验证。用 curl 打一个 chat completions 请求curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer YOUR_TAOTOKEN_KEY \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: reply with the single word: ok}], max_tokens: 10 }如果返回的 JSON 里choices[0].message.content是ok说明 Key 和通道都通了。如果返回 401检查 Key 是否复制完整如果返回 404检查 base_url 是不是多写了/v1——TaoToken 的基地址是https://taotoken.net/apiSDK 会自动补/v1curl 手动测的时候要写全。4. 从创建到优化跑通完整技能工程化链路4.1 创建阶段SKILL.md 的结构设计skill-creator 的创建流程从需求访谈开始。它会问你四个核心问题技能用途、触发条件、输出格式、是否需要测试用例。这四个问题决定了 SKILL.md 的骨架。一个规范的 SKILL.md 由 YAML frontmatter 和正文组成。frontmatter 里的name和description是触发层始终加载正文是执行层触发后才加载。下面是一个 PDF 转 Markdown 的示例--- name: pdf-to-markdown description: Convert PDF documents to Markdown while preserving structure. Use when the user wants to extract text from PDFs, convert documentation, make PDFs editable, or parse tables. Trigger keywords: convert PDF, PDF to markdown, extract from PDF, parse PDF, or when user provides .pdf files. compatibility: tools: - Read - Write - Bash dependencies: python: 3.8 packages: [pdfplumber0.7.0, markdown-it-py2.0.0] --- # PDF to Markdown Converter ## Overview Converts PDF documents to clean Markdown, preserving heading hierarchy, tables, code blocks, and bold/italic formatting. ## When to Use - User explicitly asks to convert PDF to Markdown - User provides a .pdf file and wants editable format - Keywords: convert, extract, PDF to text, make editable ## Workflow 1. Validate input is a .pdf file 2. Extract text and tables with pdfplumber 3. Detect headings by font size and weight 4. Convert tables to Markdown table syntax 5. Wrap code blocks in triple backticks with language identifier 6. Save to {original_name}.md with UTF-8 encoding ## Error Handling - Encrypted PDFs: ask user for password - Scanned PDFs: recommend OCR tools, this skill handles text PDFs only - Large files (50 pages): process in chunks, show progress这里有个容易踩的坑description写得太短会导致触发率低。skill-creator 的触发优化算法会专门针对这一点做迭代——它拿失败的查询去反推 description 缺了哪些关键词。上面这份 description 里同时包含了“做什么”Convert PDF to Markdown和“什么时候用”Use when...还列了触发关键词这是触发率能到 90% 以上的关键。4.2 评测阶段evals.json 与断言设计Skill 创建完不能靠感觉判断好坏要写测试用例。skill-creator 用evals/evals.json定义用例每个用例包含 prompt、期望输出和断言列表{ skill_name: pdf-to-markdown, evals: [ { id: 1, prompt: Convert this technical PDF to Markdown: evals/files/simple_doc.pdf, files: [evals/files/simple_doc.pdf], expectations: [ Output is a valid .md file, All headings are converted to # ## ### syntax, No extraction errors logged, File size is less than 2x input text content ] }, { id: 2, prompt: Extract tables from this report: evals/files/table_heavy.pdf, files: [evals/files/table_heavy.pdf], expectations: [ At least 3 tables present in output, Tables use |---|---| separator syntax, Column counts match source PDF, Numeric values are preserved accurately ] } ] }断言的设计原则是客观、可验证、有明确标准。像“输出看起来不错”“质量很高”这种主观描述没法自动化必须转成可编程检查的指标。比如“输出可读性强”可以拆成“通过 Markdown linter”“标题层级一致”“无断链”三条。评测执行时skill-creator 会并行启动 6 个子任务3 个用例 × 2 个变体with_skill 组加载技能baseline 组不加载然后对比两组的断言通过率。这个过程会生成timing.json记录 token 消耗和耗时{ total_tokens: 84852, duration_ms: 23332, total_duration_seconds: 23.3, tokens_per_second: 3636 }注意性能数据只在任务完成通知里出现一次必须立刻捕获保存否则会丢失。skill-creator 的脚本里专门有个capture_timing_data()回调处理这件事。4.3 优化阶段迭代循环与版本管理评测跑完会生成benchmark.json里面是 with_skill 和 baseline 的对比数据。下面是一个真实跑出来的结果{ skill_name: pdf-to-markdown, configurations: [ { name: with_skill, pass_rate: {mean: 0.89, stddev: 0.05}, duration_seconds: {mean: 23.5, stddev: 3.2}, tokens: {mean: 85000, stddev: 12000} }, { name: baseline, pass_rate: {mean: 0.45, stddev: 0.12}, duration_seconds: {mean: 45.2, stddev: 8.1}, tokens: {mean: 120000, stddev: 18000} } ], delta: { pass_rate_improvement: 0.44, time_saved_percent: 48, token_reduction_percent: 29 } }这组数据说明技能把通过率从 45% 拉到 89%同时耗时减少 48%、token 减少 29%。但这不是一次就达到的中间经历了版本迭代。skill-creator 用history.json记录每个版本的变化和结果{ skill_name: pdf-to-markdown, current_best: v3, iterations: [ {version: v0, parent: null, expectation_pass_rate: 0.45, grading_result: baseline, changes: Initial baseline (no skill)}, {version: v1, parent: v0, expectation_pass_rate: 0.73, grading_result: won, changes: Added basic heading detection}, {version: v2, parent: v1, expectation_pass_rate: 0.68, grading_result: lost, changes: Tried complex table parser - regressed}, {version: v3, parent: v1, expectation_pass_rate: 0.89, grading_result: won, is_current_best: true, changes: Improved code block detection table alignment} ] }注意 v2 是“lost”——它从 v1 的 73% 掉到 68%系统自动回滚到 v1 再尝试新方向才有了 v3 的 89%。这个回滚机制很重要它避免了“越改越差还继续改”的情况。迭代停止条件有三个连续 3 次改进幅度小于 3%、通过率达到 95%、或者超过 10 轮。4.4 触发优化description 的迭代触发优化是单独一条链路。skill-creator 会拿一组测试查询包含应该触发和不应该触发的每个查询跑 5 次统计触发率。初始 description 的触发率往往只有 60% 左右优化后能到 90% 以上。优化的核心逻辑是把失败的查询关键词补进 description。比如初始版本是Convert PDF documents to Markdown format while preserving structure.失败的查询有“Extract text from this PDF”“Make this PDF editable”“Parse tables from PDF”。优化后的版本变成Convert PDF documents to Markdown format while preserving structure. Use when the user wants to extract text from PDFs, convert documentation, make PDFs editable, or parse tables. Handles technical docs, reports, and papers. Trigger keywords: convert PDF, PDF to markdown, extract from PDF, parse PDF, make PDF editable, or when user provides .pdf files.关键改动是加了明确的“Use when”场景描述并把失败查询里的关键词直接列进去。这个优化过程可以手动做也可以用 skill-creator 的improve_description.py脚本自动生成——它会把失败查询和之前的尝试历史一起喂给模型要求生成一个“结构上不同”的新描述避免重复无效方向。5. 本篇常见错排查5.1 配置类错误症状curl 返回 401 Unauthorized。最常见的原因是 Key 复制时带了空格或者用了错误的 Key。检查Authorization: Bearer后面的字符串是否完整前后无空格。另外确认 Key 没有过期或被禁用。症状curl 返回 404 Not Found。检查 base_url。TaoToken 的基地址是https://taotoken.net/api如果你在 curl 里写成了https://taotoken.net/api/v1/chat/completions是对的但如果 SDK 配置里 base_url 写成了https://taotoken.net/api/v1SDK 再补/v1就会变成/api/v1/v1导致 404。SDK 配置里 base_url 只写到/api。症状Cline 里模型列表为空。检查cline.openAiModelId是否填了实际可用的模型名。有些模型需要特定权限如果 Key 没有开通对应模型列表会为空。先用 curl 测一下目标模型是否可用。5.2 评测类错误症状断言全部失败但输出文件明明存在。大概率是输出路径不对。skill-creator 期望输出在outputs/目录下文件名和输入对应。检查evals.json里的files路径是否相对于 workspace 根目录以及脚本是否真的把文件写到了outputs/。症状评分 Agent 超时。通常是输出文件太大评分 Agent 读全文导致超时。解决办法是限制输出大小或者在断言里只检查关键片段而不是全文。skill-creator 的check_assertion函数支持只读文件的前 N 行或匹配特定模式。症状性能数据丢失。前面提过timing 数据只在任务完成通知里出现一次。如果你在脚本里没有注册capture_timing_data()回调数据就丢了。检查run_eval.py里是否有这个回调注册。5.3 触发类错误症状技能该触发时不触发。先看 description 是否太短或太泛。用触发测试跑一遍看哪些查询没触发把那些查询的关键词补进 description。另外注意 Claude 倾向于“欠触发”description 可以写得稍微“主动”一点明确列出触发场景。症状技能不该触发时乱触发。这是反向问题通常是 description 里的关键词太宽泛。比如只写了“convert”没限定“PDF”那用户说“convert this image”也会触发。解决办法是在 description 里加限定条件比如“when user provides .pdf files”。症状触发率波动大同一查询有时触发有时不触发。这是正常现象模型有随机性。所以触发测试要跑多次取平均值runs_per_query 5是经验值要求严格的话可以调到 10。6. 把链路固化下来跑通一次完整链路之后建议把配置和脚本固化到项目里而不是每次手动配。具体做法是在项目根目录建一个.claude/目录把settings.json或config.toml放进去再把 skill-creator 的 workspace 路径固定为./skill-workspace。这样团队成员拉下代码就能直接用不需要各自配 Key。如果你还在选模型阶段想先对比不同模型在 Skill 评测里的表现可以用模型对话页面快速试https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 。如果是要长期跑编码和 Agent 任务Coding Plan 更适合https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。Claude Code 的接入配置在 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite 里面有针对 skill-creator 场景的推荐参数。最后说一个实操细节skill-creator 的评测脚本在并行跑 6 个任务时如果 Key 的并发限制较低会出现部分任务 429。解决办法是在config.toml里把parallel_evals从 6 降到 3或者给 skill-creator 单独申请一个并发更高的 Key。这个坑我在第一次跑大规模评测时踩过表现为 benchmark 数据里 with_skill 组的样本数比预期少原因是部分任务被限流后静默失败了。加上重试逻辑或者降低并发就能解决。 Claude skill-creator插件深度解析：从创建到优化的完整技能工程化体系与TaoToken配置实践
1. 为什么你的 Claude Skill 总是“差点意思”如果你正在用 Cline、CC Switch 或者 Claude Code 写代码大概率已经接触过 Skill 这个概念。简单说Skill 就是给 Claude 装上一套“可复用的操作手册”——比如“把 PDF 转成 Markdown”“审查 PR 里的安全漏洞”“按团队规范生成 commit message”。它和普通提示词最大的区别是Skill 有目录结构、有元数据、有可执行脚本、有测试用例是一个能被版本管理和迭代的工程产物。但问题也出在这里。很多人第一次写 Skill就是把一段提示词塞进SKILL.md然后发现三个典型症状一是触发不稳定明明该用的时候 Claude 不加载二是输出质量飘忽同一份输入两次结果差很多三是改了一版之后不知道是变好了还是变差了全靠感觉。这三点本质上不是“提示词写得不够好”而是缺少一套从创建、评测到优化的工程化闭环。skill-creator这个插件解决的正是这件事。它把 Skill 的开发过程拆成需求访谈、结构设计、自动化评测、迭代优化、触发调优几个阶段并且用多 Agent 协作的方式把“评分”“分析”“版本对比”这些原本靠人肉判断的环节自动化。我试过用它把一个内部代码审查 Skill 从 58% 的断言通过率拉到 89%整个过程大概跑了四轮迭代每轮都有明确的 benchmark 数据支撑。这篇文章面向的是已经在用 Cline / CC Switch / Claude Code 的开发者目标很具体交付一套可复制的settings.json和config.toml配置骨架演示如何通过 TaoToken 统一 Key 和 API 通道接入然后把“创建 → 评测 → 优化”这条链路完整跑通。你不需要是提示词专家但需要能看懂基本的 Python 和 JSON。2. TaoToken 前置统一 Key 与 API 通道在讲 Skill 工程化之前先把接入层理清楚。skill-creator 在评测阶段会频繁调用模型——并行跑 with_skill 和 baseline 两组任务、生成改进方案、做触发测试这些都会消耗大量请求。如果每个工具各配一套 Key管理成本会很高而且不同工具之间的模型版本容易不一致导致 benchmark 数据不可比。TaoToken 在这里的角色是统一入口一个 Key、一个 API 地址同时服务 Cline、CC Switch、Claude Code 以及 skill-creator 的评测脚本。这样做的直接好处是评测时用的模型和日常编码时用的模型是同一个通道数据不会因为供应商差异而漂移。官网入口在这里https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基地址是 https://taotoken.net/api 注意这个地址不加 UTM 参数直接用于配置。你需要先拿到一个 API Key。进入控制台创建即可https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。创建完成后Key 的管理页面在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 建议给 skill-creator 单独建一个 Key方便后续按项目统计用量。注意Key 只显示一次创建后立刻复制保存。如果丢失只能重新生成旧的会失效。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面列出了不同工具的配置字段对照。下面我直接给出 Cline 和 CC Switch 两套骨架你可以按自己用的工具选一套。3. 可复制配置settings.json 与 config.toml 骨架3.1 Cline 的 settings.jsonCline 的配置走 VS Code 的 settings.json。核心是把 API Provider 指向 TaoToken 的兼容端点并把模型名写成你实际要用的版本。下面这份骨架可以直接粘贴把YOUR_TAOTOKEN_KEY替换成你自己的 Key{ cline.apiProvider: openai, cline.openAiApiKey: YOUR_TAOTOKEN_KEY, cline.openAiBaseUrl: https://taotoken.net/api, cline.openAiModelId: claude-sonnet-4-20250514, cline.openAiModelInfo: { maxTokens: 8192, contextWindow: 200000, supportsImages: true, supportsPromptCache: true }, cline.customInstructions: When creating or modifying Claude Skills, always validate SKILL.md frontmatter before running evals., cline.autoApprovalSettings: { enabled: true, actions: { readFiles: true, editFiles: false, runCommands: false } } }几个字段说明一下。cline.openAiBaseUrl填https://taotoken.net/api不要带尾部斜杠。cline.openAiModelId按你实际订阅的模型填上面写的是 Sonnet 4 的示例。supportsPromptCache建议开skill-creator 的评测脚本会反复读同一份 SKILL.md缓存能省不少 token。autoApprovalSettings里我把editFiles和runCommands关掉了因为 skill-creator 会生成脚本文件自动批准有风险手动确认更稳。3.2 CC Switch 的 config.tomlCC Switch 用 TOML 配置结构更清晰。下面这份骨架覆盖了 provider、模型和 skill-creator 需要的环境变量[provider] name taotoken base_url https://taotoken.net/api api_key YOUR_TAOTOKEN_KEY api_style openai [model] default claude-sonnet-4-20250514 fast claude-haiku-4-20250514 max_tokens 8192 temperature 0.2 [skill_creator] enabled true workspace ./skill-workspace parallel_evals 6 runs_per_query 5 trigger_threshold 0.8 baseline_enabled true [skill_creator.grading] model claude-sonnet-4-20250514 max_thinking_tokens 2000 [env] ANTHROPIC_BASE_URL https://taotoken.net/api ANTHROPIC_API_KEY YOUR_TAOTOKEN_KEY这里有几个参数值得展开。parallel_evals 6对应 skill-creator 的并行评测机制——每个测试用例同时跑 with_skill 和 baseline 两个变体3 个用例就是 6 个并行任务。runs_per_query 5是触发测试的重复次数因为触发有随机性跑 5 次取触发率更可靠。trigger_threshold 0.8表示触发率超过 80% 才算通过低于 20% 才算“不该触发时没触发”。[env]段是关键。skill-creator 的评测脚本底层调用的是 Anthropic SDK它读的是ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY这两个环境变量。把它们指向 TaoToken脚本就能走统一通道不需要改任何代码。3.3 验证配置是否生效配置写完后先做一次最小验证。用 curl 打一个 chat completions 请求curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer YOUR_TAOTOKEN_KEY \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: reply with the single word: ok}], max_tokens: 10 }如果返回的 JSON 里choices[0].message.content是ok说明 Key 和通道都通了。如果返回 401检查 Key 是否复制完整如果返回 404检查 base_url 是不是多写了/v1——TaoToken 的基地址是https://taotoken.net/apiSDK 会自动补/v1curl 手动测的时候要写全。4. 从创建到优化跑通完整技能工程化链路4.1 创建阶段SKILL.md 的结构设计skill-creator 的创建流程从需求访谈开始。它会问你四个核心问题技能用途、触发条件、输出格式、是否需要测试用例。这四个问题决定了 SKILL.md 的骨架。一个规范的 SKILL.md 由 YAML frontmatter 和正文组成。frontmatter 里的name和description是触发层始终加载正文是执行层触发后才加载。下面是一个 PDF 转 Markdown 的示例--- name: pdf-to-markdown description: Convert PDF documents to Markdown while preserving structure. Use when the user wants to extract text from PDFs, convert documentation, make PDFs editable, or parse tables. Trigger keywords: convert PDF, PDF to markdown, extract from PDF, parse PDF, or when user provides .pdf files. compatibility: tools: - Read - Write - Bash dependencies: python: 3.8 packages: [pdfplumber0.7.0, markdown-it-py2.0.0] --- # PDF to Markdown Converter ## Overview Converts PDF documents to clean Markdown, preserving heading hierarchy, tables, code blocks, and bold/italic formatting. ## When to Use - User explicitly asks to convert PDF to Markdown - User provides a .pdf file and wants editable format - Keywords: convert, extract, PDF to text, make editable ## Workflow 1. Validate input is a .pdf file 2. Extract text and tables with pdfplumber 3. Detect headings by font size and weight 4. Convert tables to Markdown table syntax 5. Wrap code blocks in triple backticks with language identifier 6. Save to {original_name}.md with UTF-8 encoding ## Error Handling - Encrypted PDFs: ask user for password - Scanned PDFs: recommend OCR tools, this skill handles text PDFs only - Large files (50 pages): process in chunks, show progress这里有个容易踩的坑description写得太短会导致触发率低。skill-creator 的触发优化算法会专门针对这一点做迭代——它拿失败的查询去反推 description 缺了哪些关键词。上面这份 description 里同时包含了“做什么”Convert PDF to Markdown和“什么时候用”Use when...还列了触发关键词这是触发率能到 90% 以上的关键。4.2 评测阶段evals.json 与断言设计Skill 创建完不能靠感觉判断好坏要写测试用例。skill-creator 用evals/evals.json定义用例每个用例包含 prompt、期望输出和断言列表{ skill_name: pdf-to-markdown, evals: [ { id: 1, prompt: Convert this technical PDF to Markdown: evals/files/simple_doc.pdf, files: [evals/files/simple_doc.pdf], expectations: [ Output is a valid .md file, All headings are converted to # ## ### syntax, No extraction errors logged, File size is less than 2x input text content ] }, { id: 2, prompt: Extract tables from this report: evals/files/table_heavy.pdf, files: [evals/files/table_heavy.pdf], expectations: [ At least 3 tables present in output, Tables use |---|---| separator syntax, Column counts match source PDF, Numeric values are preserved accurately ] } ] }断言的设计原则是客观、可验证、有明确标准。像“输出看起来不错”“质量很高”这种主观描述没法自动化必须转成可编程检查的指标。比如“输出可读性强”可以拆成“通过 Markdown linter”“标题层级一致”“无断链”三条。评测执行时skill-creator 会并行启动 6 个子任务3 个用例 × 2 个变体with_skill 组加载技能baseline 组不加载然后对比两组的断言通过率。这个过程会生成timing.json记录 token 消耗和耗时{ total_tokens: 84852, duration_ms: 23332, total_duration_seconds: 23.3, tokens_per_second: 3636 }注意性能数据只在任务完成通知里出现一次必须立刻捕获保存否则会丢失。skill-creator 的脚本里专门有个capture_timing_data()回调处理这件事。4.3 优化阶段迭代循环与版本管理评测跑完会生成benchmark.json里面是 with_skill 和 baseline 的对比数据。下面是一个真实跑出来的结果{ skill_name: pdf-to-markdown, configurations: [ { name: with_skill, pass_rate: {mean: 0.89, stddev: 0.05}, duration_seconds: {mean: 23.5, stddev: 3.2}, tokens: {mean: 85000, stddev: 12000} }, { name: baseline, pass_rate: {mean: 0.45, stddev: 0.12}, duration_seconds: {mean: 45.2, stddev: 8.1}, tokens: {mean: 120000, stddev: 18000} } ], delta: { pass_rate_improvement: 0.44, time_saved_percent: 48, token_reduction_percent: 29 } }这组数据说明技能把通过率从 45% 拉到 89%同时耗时减少 48%、token 减少 29%。但这不是一次就达到的中间经历了版本迭代。skill-creator 用history.json记录每个版本的变化和结果{ skill_name: pdf-to-markdown, current_best: v3, iterations: [ {version: v0, parent: null, expectation_pass_rate: 0.45, grading_result: baseline, changes: Initial baseline (no skill)}, {version: v1, parent: v0, expectation_pass_rate: 0.73, grading_result: won, changes: Added basic heading detection}, {version: v2, parent: v1, expectation_pass_rate: 0.68, grading_result: lost, changes: Tried complex table parser - regressed}, {version: v3, parent: v1, expectation_pass_rate: 0.89, grading_result: won, is_current_best: true, changes: Improved code block detection table alignment} ] }注意 v2 是“lost”——它从 v1 的 73% 掉到 68%系统自动回滚到 v1 再尝试新方向才有了 v3 的 89%。这个回滚机制很重要它避免了“越改越差还继续改”的情况。迭代停止条件有三个连续 3 次改进幅度小于 3%、通过率达到 95%、或者超过 10 轮。4.4 触发优化description 的迭代触发优化是单独一条链路。skill-creator 会拿一组测试查询包含应该触发和不应该触发的每个查询跑 5 次统计触发率。初始 description 的触发率往往只有 60% 左右优化后能到 90% 以上。优化的核心逻辑是把失败的查询关键词补进 description。比如初始版本是Convert PDF documents to Markdown format while preserving structure.失败的查询有“Extract text from this PDF”“Make this PDF editable”“Parse tables from PDF”。优化后的版本变成Convert PDF documents to Markdown format while preserving structure. Use when the user wants to extract text from PDFs, convert documentation, make PDFs editable, or parse tables. Handles technical docs, reports, and papers. Trigger keywords: convert PDF, PDF to markdown, extract from PDF, parse PDF, make PDF editable, or when user provides .pdf files.关键改动是加了明确的“Use when”场景描述并把失败查询里的关键词直接列进去。这个优化过程可以手动做也可以用 skill-creator 的improve_description.py脚本自动生成——它会把失败查询和之前的尝试历史一起喂给模型要求生成一个“结构上不同”的新描述避免重复无效方向。5. 本篇常见错排查5.1 配置类错误症状curl 返回 401 Unauthorized。最常见的原因是 Key 复制时带了空格或者用了错误的 Key。检查Authorization: Bearer后面的字符串是否完整前后无空格。另外确认 Key 没有过期或被禁用。症状curl 返回 404 Not Found。检查 base_url。TaoToken 的基地址是https://taotoken.net/api如果你在 curl 里写成了https://taotoken.net/api/v1/chat/completions是对的但如果 SDK 配置里 base_url 写成了https://taotoken.net/api/v1SDK 再补/v1就会变成/api/v1/v1导致 404。SDK 配置里 base_url 只写到/api。症状Cline 里模型列表为空。检查cline.openAiModelId是否填了实际可用的模型名。有些模型需要特定权限如果 Key 没有开通对应模型列表会为空。先用 curl 测一下目标模型是否可用。5.2 评测类错误症状断言全部失败但输出文件明明存在。大概率是输出路径不对。skill-creator 期望输出在outputs/目录下文件名和输入对应。检查evals.json里的files路径是否相对于 workspace 根目录以及脚本是否真的把文件写到了outputs/。症状评分 Agent 超时。通常是输出文件太大评分 Agent 读全文导致超时。解决办法是限制输出大小或者在断言里只检查关键片段而不是全文。skill-creator 的check_assertion函数支持只读文件的前 N 行或匹配特定模式。症状性能数据丢失。前面提过timing 数据只在任务完成通知里出现一次。如果你在脚本里没有注册capture_timing_data()回调数据就丢了。检查run_eval.py里是否有这个回调注册。5.3 触发类错误症状技能该触发时不触发。先看 description 是否太短或太泛。用触发测试跑一遍看哪些查询没触发把那些查询的关键词补进 description。另外注意 Claude 倾向于“欠触发”description 可以写得稍微“主动”一点明确列出触发场景。症状技能不该触发时乱触发。这是反向问题通常是 description 里的关键词太宽泛。比如只写了“convert”没限定“PDF”那用户说“convert this image”也会触发。解决办法是在 description 里加限定条件比如“when user provides .pdf files”。症状触发率波动大同一查询有时触发有时不触发。这是正常现象模型有随机性。所以触发测试要跑多次取平均值runs_per_query 5是经验值要求严格的话可以调到 10。6. 把链路固化下来跑通一次完整链路之后建议把配置和脚本固化到项目里而不是每次手动配。具体做法是在项目根目录建一个.claude/目录把settings.json或config.toml放进去再把 skill-creator 的 workspace 路径固定为./skill-workspace。这样团队成员拉下代码就能直接用不需要各自配 Key。如果你还在选模型阶段想先对比不同模型在 Skill 评测里的表现可以用模型对话页面快速试https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 。如果是要长期跑编码和 Agent 任务Coding Plan 更适合https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。Claude Code 的接入配置在 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite 里面有针对 skill-creator 场景的推荐参数。最后说一个实操细节skill-creator 的评测脚本在并行跑 6 个任务时如果 Key 的并发限制较低会出现部分任务 429。解决办法是在config.toml里把parallel_evals从 6 降到 3或者给 skill-creator 单独申请一个并发更高的 Key。这个坑我在第一次跑大规模评测时踩过表现为 benchmark 数据里 with_skill 组的样本数比预期少原因是部分任务被限流后静默失败了。加上重试逻辑或者降低并发就能解决。