1. Claude Code 读不懂我的 SKILL.md问题到底出在哪如果你写过 SKILL.md 并把它丢给 Claude Code 用大概率遇到过这种场景文件里明明写了「必须先检查环境变量」「遇到 X 类型错误立即退出」模型跑起来跟没看见一样该跳过的跳过该忽略的忽略。你花两小时写的规范它当参考书翻不是当契约执行。这不是 Claude Code 的 bug也不是你 skill 写得烂。根因在于 SKILL.md 本质是一段散文人类写给人类看的散文然后被塞进 system prompt让 LLM 在 runtime 自己猜这段话要求它干什么。一两个 skill 还行三个凑合五个以上就开始出事所有 skill 挤在同一个 context window 里互相污染文件整理 skill 的逻辑会嫁接到 git 操作上工具名拼错、参数缺失、指令歧义agent 一个都抓不到全留到 runtime 爆等爆的时候对话已经二十轮深了。我试过把 SKILL.md 拆得更细、写得更啰嗦没用。因为问题不在格式在于 SKILL.md 是 prompt engineering不是 software engineering。你在让 LLM 在 runtime 解读人类散文没有编译没有类型检查没有契约。这篇文章要解决的就是这条链路怎么把一份散文式的 SKILL.md编译成 6 个 Harness 协作产出的、能独立运行的 Agent。我会给你可复制的 SKILL.md 骨架、Harness 配置片段、本地验证步骤目标是让你跑通一次编译并确认生成的 Agent 能脱离 Claude Code 独立跑起来。适合谁Claude Code / Codex CLI 用户skill 超过 3 个就感觉不对劲的想把 skill 沉淀成可交付产物的智能体开发工程师以及想看 LLM 怎么被拆成专业化流水线的编译器爱好者。2. 前置准备TaoToken 接入与编译环境在动手编译之前先把两件事准备好一个能稳定调用的 LLM API以及本地 Python 环境。6 个 Harness 在 Phase 2 要反复调 LLM 做推理API 的稳定性和计费方式直接决定你编译一次的成本。2.1 为什么用 TaoToken 做 Harness 的推理后端TaoToken 是一个聚合多家大模型能力的 API 平台对做编译器这类「一次编译、多次调用」的场景比较友好同一套 OpenAI 兼容接口可以按 Harness 的档位切换不同模型——Harness A 这种确定性提取用便宜的小模型Harness C 这种接口推理用大模型成本能压下来。你不需要为每个 Harness 单独维护一套 SDK。官网入口在这里注册和文档都在里面https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 基址注意这个不带 UTM配置里直接填https://taotoken.net/api2.2 拿到 API Key登录后进控制台创建密钥路径是 API Keys 页面https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite创建完复制那串sk-开头的 key先存到环境变量里别硬编码进代码export TAOTOKEN_API_KEYsk-你的密钥注意这个 key 后面会写进生成包的runtime.toml所以别把它提交到 git。生成包默认会带.gitignore但你自己检查一遍更稳。2.3 本地环境编译器本身是 Python 包Python 3.10 以上python3 --version # 确认 3.10 pip install agenthatch agenthatch --version如果agenthatch命令找不到多半是 pip 的 bin 目录没进 PATH用python3 -m agenthatch --version先验证包装上了。3. 可复制配置SKILL.md 骨架与 6 个 Harness 的职责边界这一节是全文的核心。先给你一份能直接用的 SKILL.md 骨架再拆 6 个 Harness 各自干什么、怎么调度。3.1 一份能被编译的 SKILL.md 骨架编译器对 SKILL.md 的要求不复杂但结构要清晰。frontmatter 用 YAML正文分能力、工具、工作流程三块。下面这份可以直接复制改--- name: weather-advisor description: 查询全球任意城市天气支持多日预报和穿衣建议 version: 0.1.0 --- # Weather Advisor Agent ## 能力 - 查询指定城市的实时天气 - 查询未来 3 天天气预报 - 根据天气给出穿衣建议 ## 工具 - httpx 调用 OpenWeatherMap API - rich 彩色格式化输出 ## 工作流程 1. 接收用户输入的城市名 2. 调用 OpenWeatherMap API 获取天气数据 3. 解析 JSON 响应提取关键信息 4. 用 rich 格式化输出 5. 根据温度给出穿衣建议就这么个纯 markdown没有一行代码没有工具签名没有类型。全是散文。编译器要做的就是把它变成带类型签名和状态机的 Python 包。3.2 三阶段管线总览编译链路分三段SKILL.md → Parse → 6-Harness LLM Pipeline → Code Generation → Runnable Agent (输入) (Phase 1) (Phase 2: AI 推理) (Phase 3: Jinja2) (输出)Phase 1 是确定性解析零 AI把 frontmatter、正文、目录文件拆出来算 SHA-256做 YAML 解析。Phase 1.5 用 Python 内置ast模块解析脚本提取函数签名喂给后面的 Harness 做精确接口推理。Phase 2 是 6 个 AI Harness 推理这是心脏。Phase 3 用 Jinja2 把 spec 渲染成完整 Python 包还会让 LLM 生成真实的工具函数体生成后先compile()验证语法挂了就修修不好就 fallback。3.3 6 个 Harness 的职责与温度配置六个 Harness 各干一件事每个有自己的 persona 和温度。温度不是拍脑袋定的配置里带 reasonHARNESS_CONFIG { A: {thinking: True, temperature: 0.1, reason: Identity extraction is deterministic}, B: {thinking: True, temperature: 0.5, reason: Intent inference requires creativity}, C: {thinking: True, temperature: 0.5, reason: Interface inference is complex}, D: {thinking: True, temperature: 0.3, reason: Base detection needs precision}, E: {thinking: True, temperature: 0.2, reason: Assembly validation is structured}, F: {thinking: True, temperature: 0.3, reason: MCP config extraction needs exact matching}, }职责边界对照表Harness职责模型档位温度A — Identity从 frontmatter 提取 name/version/descriptionsmall0.1B — Intent推理触发词和用户意图small0.5C — Interface设计工具签名、参数、返回类型large0.5D — Base检测运行时基类和指令结构large0.3E — Assembly交叉校验其他五个输出产出 AHSSPECsmall0.2F — MCP检测并配置 MCP server 连接small0.3为什么拆六个我试过一个超大 prompt 全搞定输出跟抽奖似的。拆开之后每个只管一件事质量高很多。这跟编译器把前端拆成 lexer/parser/semantic 是一个道理单一职责。3.4 调度方式预飞分类决定模型档位Orchestrator 在派发 Harness 之前会先做预飞分类根据 skill 类型决定每个 Harness 用哪个模型档位def _classify(self, context): has_scripts any(Path(e.path).suffix.lower() in {.py, .sh, .js} for e in context.file_manifest.entries) body_lower context.body.lower() has_api any(ind in body_lower for ind in [api, oauth, token, http]) if has_scripts and has_api: return integration if has_scripts: return script_driven if len(entries) 2: return knowledge return pure_instruction四种类型对应四套档位组合。纯指令类 skill 的 Harness D 直接 skip省 token集成类 skill 全部上 large 模型。不是所有 skill 都值得烧大模型预飞分类帮你省钱。每个 Harness 跑一个 Analyze → Infer → Self-Validate → Correct 循环最多两次内部重试。校验不是 LLM 自己说的算是代码强制执行的。比如 Harness A 校验identity.id必须是 kebab-caseHarness B 校验 triggers 数量必须在 [5, 15]。LLM 输出不合规立刻打回去重做。Harness E 最关键它校验其他五个的输出生成统一的 AHSSPEC还会算一个结构性置信度——不是 LLM 自评是代码数字段def _compute_structural_confidence(self, ahs_dict): checks 0 passed 0 id_ ahs_dict.get(identity, {}) for f in (id, display_name, version): checks 1 if id_.get(f): passed 1 return round(passed / max(checks, 1), 2)LLM 自评的 confidence 我不信我信代码数出来的。4. 验证请求跑通一次编译并确认 Agent 独立运行配置讲完动手跑一遍。三步加 skill、编译、运行。4.1 添加并编译agenthatch init agenthatch skills add ./weather-advisor/SKILL.md agenthatch hatch weather-advisorhatch跑完你会得到一个完整的 Python 包weather-advisor-agent/ ├── pyproject.toml ├── runtime.toml ├── README.md ├── agenthatch.yaml └── src/weather_advisor/ ├── __init__.py ├── agent.py # 继承 AHCoreAgent带 PlanLayer ├── tools.py # get_weather(city: str) - WeatherResponse └── references.py注意tools.pyHarness C 推理出来的工具签名是带类型注解的 Python 函数不是散文描述。get_weather(city: str) - WeatherResponse参数类型、返回类型都有LLM 不用猜。4.2 配置 runtime.toml生成包里有个runtime.toml把 TaoToken 的 key 和基址填进去[llm] provider openai-compatible base_url https://taotoken.net/api api_key sk-你的密钥 model claude-3-5-sonnet [agent] max_consecutive_failures 3 verify_every_n_steps 5 tool_timeout 120base_url填 TaoToken 的 API 地址model按你账号里可用的模型填。这样生成的 Agent 就通过 TaoToken 调模型不依赖任何 host agent。4.3 运行并验证独立agenthatch run weather-advisor跑起来是个正经的交互式 agent带工具调用、上下文压缩、PlanLayer 驱动执行。它不依赖 Claude Code不依赖 Codex就是个独立的 Python 程序。验证独立性的方法把生成包拷到另一台没装 Claude Code 的机器上pip install -e .然后直接python -m weather_advisor能跑起来就说明它真的独立了。4.4 运行时状态机生成的 agent 跑起来不是裸的 ReAct 循环它带一个 PlanLayer 六状态机class AgentState(str, Enum): STARTING starting PLANNING planning EXECUTING executing VERIFYING verifying REPLANNING replanning DONE done状态转换由循环管不是 LLM 管。LLM 不可靠状态机可靠。连续 3 次工具失败就切 REPLANNING每完成 5 步建议 VERIFYING 一次。工具调用还有 120 秒超时保护shutdown(waitFalse)因为 Python 线程杀不掉卡在 I/O 里的工具线程不能阻塞整个对话。5. 本篇常见错排查编译和运行过程中下面这些坑我基本都踩过。5.1 Harness E 的 JSON 解析失败现象编译日志里出现Harness E chat_structured failed, falling back to raw chat。原因是 structured output 偶尔挂代码里有 fallback会切到 raw chat 手动抽 JSON。如果 fallback 也失败AHSSPEC 会缺字段生成的包不完整。排查看日志里有没有JSONDecodeError。有的话重跑一次hatch或者把 Harness E 的模型档位调高一级。5.2 工具实现是 stub现象生成的tools.py里函数体只有一行raise NotImplementedError。原因是 Phase 3 的 AI 代码生成返回的代码语法错误修不好fallback 成 stub。代码里有_check_tool_stubs()检测并打 CRITICAL warning。排查编译日志里搜CRITICAL看哪些工具是 stub。遇到 stub 自己手动实现一下或者重跑hatch。重跑时换个模型档位成功率会高一些。5.3 生成的代码混进 JavaScript 关键字现象tools.py里出现null、undefined、true、false。原因是 LLM 把 JS 习惯带进 Python。Phase 3 有_validate_generated_python()扫所有生成的.py文件检查语法能不能 parse。排查如果编译时报语法错误看是不是这类关键字。手动改成None、True、False即可。5.4 运行时 API 调用失败现象agent 跑起来报 401 或 404。检查runtime.toml里的base_url是不是https://taotoken.net/apiapi_key有没有过期。TaoToken 的接入文档在这里https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite5.5 Windows 路径问题现象Windows 上编译报路径错误。原因是路径处理没系统测过。建议在 WSL 里跑或者等后续版本。5.6 Harness 是串行不是并行README 里写「6 harnesses working in parallel」但实际是 A→B→C→D→F→E 顺序派发D 依赖 CE 依赖前面所有。这不是 bug是依赖关系决定的。文档描述有点夸张以实际代码为准。6. 下一步从编译到长期编码跑通一次编译之后你大概会想把它用到日常编码里。这里给两条路径。如果你只是想验证模型能力、试试不同 Harness 的推理效果可以直接在模型对话里对比不同档位的输出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 的 Anthropic 接口想把这套编译产物接进去参考这个接入页https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaude_code_anthropicutm_campaignrewrite最后再说一遍那个范式判断因为它值得skill 的最佳形态是 agent 化skill 是最完美的 agent 的孵化输入。你写 skill不是在写 prompt是在写 agent 的源码。编译器是它的 javac。这件事我认为会成立时间证明。