1. 凌晨两点那次 Skill 翻车让我重新理解 Rigid 与 Flexible同一个 Skill 调用前三次返回规整 JSON第四次突然吐出一段 Markdown 废话第五次又正常了——这种薛定谔的输出在生产环境里最要命。排查半小时后定位到根因某个 Flexible Skill 的 prompt 模板里写了句你可以自由发挥模型就真的自由发挥了。这件事让我意识到Skill 类型与执行策略的选择不是风格偏好而是直接决定系统稳定性的架构决策。Skill 本质上是给大模型套的一层行为契约Rigid 型 Skill 把模型当机器用输入严格匹配 schema、输出严格匹配格式、中间过程由代码逻辑控制Flexible 型 Skill 则给模型留出推理与组织空间只约束要什么而不约束怎么做。前者适合下游强依赖格式、需要幂等、审计合规的场景后者适合信息提取、代码生成、自然语言回复这类边界模糊的任务。这篇内容会给出可复制的 Skill 配置骨架含 config.toml 示例、Rigid 与 Flexible 的选型边界、组合编排思路以及如何通过 TaoToken 统一 Key/API 通道完成调用验证。适合正在用 Claude Code、Agent 框架或自建 Skill 系统的开发者跟做。2. 前置准备用 TaoToken 统一 Key 与 API 通道在写 Skill 配置之前先把调用通道理顺。Skill 系统通常需要频繁调用模型接口做验证如果每个 Skill 各自维护一套 Key排障时会非常痛苦。我的做法是统一走 TaoToken 的 API 通道一个 Key 覆盖模型对话、Coding Plan、控制台管理三类入口。TaoToken 官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址为 https://taotoken.net/api 不加 UTM。你需要先在控制台创建 API Key然后把它写进 Skill 的运行时环境变量而不是硬编码在 config.toml 里。具体操作路径打开控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 登录后进入 API Keys 页面点击创建新 Key命名建议带上用途比如skill-rigid-test、skill-flex-prod方便后续按 Skill 类型区分额度与排障复制生成的 Key写入本地.env或系统环境变量TAOTOKEN_API_KEY如果要做模型对话验证可以直接用模型对话入口 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 先手动跑一轮确认 Key 有效长期跑编码类 Skill 或 Agent 任务建议看 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 按调用量规划额度更划算注意API Key 只放在环境变量或密钥管理服务里不要提交到 Git。Skill 配置文件中用${TAOTOKEN_API_KEY}这种占位符引用。3. 可复制的 Skill 配置骨架config.toml 与 Rigid/Flexible 双模式下面这份 config.toml 是我实际在用的骨架把 Rigid 与 Flexible 两类 Skill 放在同一个配置文件里通过mode字段区分执行策略。你可以直接复制后改字段名。# skill-config.toml [provider] base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY default_model claude-sonnet timeout_seconds 60 max_retries 3 # Rigid Skill严格 schema禁止额外字段 [skills.search_database] mode rigid description 执行数据库搜索返回严格格式化的结果列表 input_schema { query string } output_schema { type array, items { type object, required [ id, title, score, source ], additionalProperties false } } on_schema_mismatch retry_with_error_feedback fallback return_error_code # Flexible Skill宽松输入允许模型组织输出 [skills.extract_meeting_notes] mode flexible description 从会议记录中提取关键信息格式自由但需人类可读 input_schema { text string } output_guidance 包含日期、参会人、决策事项、待办任务不要编造 max_tokens 1200 content_filter regex:endpoint|参数|日期 fallback downgrade_to_rigid # 组合编排Rigid 做骨架Flexible 做血肉 [pipeline.customer_service] steps [ { skill intent_recognize, mode flexible }, { skill extract_info, mode flexible }, { skill clean_data, mode rigid }, { skill create_ticket, mode rigid }, { skill generate_reply, mode flexible } ] context_isolation true几个关键字段说明on_schema_mismatch控制 Rigid Skill 校验失败后的行为retry_with_error_feedback会把上次错误作为负面示例喂回模型默认重试 3 次。fallback是逃生门Rigid 失败返回明确错误码Flexible 失败降级到 Rigid 重试。context_isolation true解决上下文污染问题——Flexible 输出的非结构化内容不能直接喂给 Rigid中间必须加一层数据清洗。对应的 Python 侧 Skill 注册代码import os import toml from typing import List, Dict, Any config toml.load(skill-config.toml) os.environ[TAOTOKEN_API_KEY] os.getenv(TAOTOKEN_API_KEY) def register_skill(name: str, mode: str): def decorator(func): func._skill_name name func._skill_mode mode return func return decorator register_skill(search_database, moderigid) def search_database(query: str) - List[Dict[str, Any]]: 执行数据库搜索返回严格格式化的结果列表 return execute_search(query, output_schema{ type: array, items: { type: object, required: [id, title, score, source], additionalProperties: False } }) register_skill(extract_meeting_notes, modeflexible) def extract_meeting_notes(text: str) - dict: 从会议记录中提取关键信息格式自由但人类可读 return model_extract(text, guidance提取结构化信息但不要编造)Rigid 的底层机制是调用前注入系统级约束告诉模型只能输出规定格式Flexible 则只给 guidance让模型自己决定字段组织方式。两者在同一个 pipeline 里协作时Rigid 环节作为阀门确保数据进入下游系统时干净Flexible 环节作为漏斗尽可能多捕获信息。4. 验证请求跑通一次 Rigid 与 Flexible 的调用配置写完后必须验证否则上线就是盲盒。我习惯用 curl 先打一次 API确认 Key 和通道没问题再跑 Skill 层。curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: claude-sonnet, messages: [ {role: system, content: 你只能输出 JSON 数组每个元素包含 id,title,score,source 四个字段禁止额外字段。}, {role: user, content: 搜索关键词skill 执行策略} ], temperature: 0 }预期返回是严格 JSON 数组字段与 schema 完全一致。如果返回里出现 Markdown 代码块包裹或额外字段说明 Rigid 约束没生效检查 system prompt 是否被 Skill 框架覆盖。Flexible 的验证请求curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: claude-sonnet, messages: [ {role: system, content: 从会议记录中提取关键信息包含日期、参会人、决策事项、待办任务不要编造。}, {role: user, content: 下午三点左右开会张三李四参加决定下周上线王五负责测试。} ], max_tokens: 1200 }Flexible 的返回允许格式灵活但必须包含关键信息。我实测下来如果强制要求 JSON模型反而会编造精确时间给点自由度后它会输出15:00大约这种更真实的表述。Skill 层验证脚本def verify_skill(skill_name: str, payload: dict): skill SKILL_REGISTRY[skill_name] result skill(**payload) if skill._skill_mode rigid: assert validate_schema(result, skill.output_schema), Rigid schema 校验失败 else: assert len(result) 0, Flexible 返回为空 print(f[OK] {skill_name} mode{skill._skill_mode}) return result verify_skill(search_database, {query: skill 执行策略}) verify_skill(extract_meeting_notes, {text: 下午三点左右开会...})成功结果应该看到两行[OK]Rigid 通过 schema 校验Flexible 返回非空且包含关键信息。如果 Rigid 报 schema 失败先看日志里模型实际输出了什么再决定是收紧 prompt 还是加参数补全预处理。5. 本篇常见错排查错误一Rigid Skill 报additionalProperties校验失败模型输出了 schema 之外的字段。原因通常是 system prompt 里没明确禁止额外字段或者 Skill 框架在注入约束时被其他 prompt 覆盖。解决在 config.toml 的output_schema里显式写additionalProperties false并在 system prompt 里重复一遍约束。错误二Flexible Skill 输出被下游 Rigid 拒绝这是上下文污染。Flexible 输出的非结构化内容直接喂给 Rigidschema 校验必然失败。解决中间加DataCleaner.clean(flex_result, schemarigid_schema)只传递必要字段。flex_result flexible_skill.extract_info(user_input) cleaned_data DataCleaner.clean(flex_result, schemacreate_ticket_schema) rigid_result rigid_skill.create_ticket(cleaned_data)错误三异步 Skill 回调时上下文错乱异步执行时模型可能已处理其他请求回调回来时上下文变了。解决在 callback 里显式传递上下文快照不要依赖全局状态。错误四API 返回 401 或 403Key 没读到或额度不足。检查TAOTOKEN_API_KEY环境变量是否生效echo $TAOTOKEN_API_KEY确认非空。如果 Key 有效但报权限错误去控制台 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 确认 Key 状态和额度。错误五Flexible Skill 失败率突然升高大概率是模型版本更新导致行为变化。定期 review Skill 调用统计Flexible 失败率升高时先对比模型版本再调整 guidance。Rigid 调用量突然下降通常是上游输入格式变了检查参数补全逻辑。错误六Rigid 重试 3 次仍失败输入参数偏离 schema 太远。解决方案不是放宽约束而是设计参数补全预处理 Skill在进入 Rigid 调用前把缺失字段补上。我见过把用户姓名设为必填、结果模型只拿到用户ID导致 30% 请求失败的案例加一层补全后降到 2%。6. 组合编排与接入验证把 Rigid 和 Flexible 串成 pipeline单一类型 Skill 很难应对复杂场景。我的架构原则是Rigid 搭框架Flexible 填内容。以智能客服为例流程是意图识别Flexible→ 信息提取Flexible→ 数据清洗Rigid→ 工单创建Rigid→ 回复生成Flexible。Rigid 环节作为阀门确保数据干净Flexible 环节作为漏斗多捕获信息。组合时最容易踩的坑是先 Flexible 后 Rigid直接串联。正确做法是中间加数据清洗层并且开启context_isolation。每个 Skill 调用之间显式清理上下文只传递必要数据。执行策略层面Claude Code 的 Skill 支持同步、异步、流式、条件四种模式。同步适合大多数场景异步适合耗时操作但要注意 callback 里的上下文快照流式适合大文件处理条件执行适合决策树。我按使用频率排序新手先把同步跑通再上异步。接入验证的完整链路先在模型对话入口 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 手动跑一轮确认 Key 有效再用 curl 打 API 确认通道最后跑 Skill 层验证脚本。三步都过才算接入完成。长期跑编码类或 Agent 任务建议用 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 规划额度避免临时 Key 额度耗尽导致 Skill 批量失败。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有完整的 API 参数说明和错误码对照。Claude Code 相关的 Anthropic 兼容接入说明在 https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecode-anthropicutm_campaignrewrite 如果你用的是 Claude Code 生态这份文档能省不少排障时间。最后给几条实在建议新手先全用 Rigid踩够模型不听话的坑再放开到 Flexible每个 Skill 都要有逃生门输入不合理就返回明确错误码而不是让模型硬撑日志里记录 Skill 类型Rigid 失败通常是 schema 不匹配Flexible 失败通常是模型理解偏差排查方向完全不同涉及金钱、法律、医疗的场景宁可返回无法处理转人工也不要让 Flexible 自由发挥。Rigid 保护系统Flexible 保护用户体验比例根据业务场景动态调整。