SKILL.md 这套范式过去一年在 Claude Code、Codex CLI、OpenClaw 上铺开了。写一份 Markdown 描述任务，agent 自动加载执行。听上去很美，但凡用过三个以上 skill 的人都知道实际摩擦有多大。agenthatch 的定位就是把 SKILL.md 当源码而不是 prompt，通过确定性管线编译成可独立运行的 Python agent。
SKILL.md 真实痛点
agenthatch 列了五个常见痛点：skill 之间没有隔离，文件整理 skill 和 git 操作 skill 共享同一个上下文窗口，agent 把两者的指令搞混；agent 把 SKILL.md 当参考而不是契约，长 skill 只读一部分；每个 SKILL.md 都塞在 system prompt 里，五个 skill 每个 3KB 就烧掉 15KB 上下文；tool 名拼错、参数缺失这类问题运行时才暴露；skill 数量到十个以上就没法管，没有依赖图也没有冲突检测。
核心问题不是格式，是 SKILL.md 本质上是 prompt engineering 而不是 software engineering。让 LLM 每次运行时解释自然语言，没有编译、没有类型检查、没有契约。
三阶段编译管线
agenthatch 的解法是把 SKILL.md 当源码，跑一条三阶段管线产出独立的 Python 包。
第一阶段是确定性解析，没有任何 AI 参与。把 SKILL.md 的 frontmatter、body、目录文件读出来，产出 ContextPack，不做语义变换。这一步保证可重现，同一份输入永远得到相同的中间表示。
第二阶段是 6 个并行 LLM harness。每个 harness 有自己的角色和温度配置：A 提取身份信息（temp 0.1）、B 推断触发短语（0.5）、C 设计工具签名（0.5）、D 检测运行时基类（0.3）、E 跨校验其他五个输出产出 AHSSPEC（0.2）、F 检测和配置 MCP server（0.3）。每个 harness 跑 Analyze → Infer → Self-Validate → Correct 循环，最多两次内部重试。低温度是关键，确保同一份 SKILL.md 每次编译出的结构稳定。
第三阶段用 Jinja2 模板把 AHSSPEC 渲染成完整 Python 包：pyproject.toml、runtime.toml、agent.py、tools.py、references.py，类型注解齐全、MCP 自动配置、CLI 入口就绪。生成的 agent 不依赖任何特定 agent 平台，可以当 CLI 跑、当库导入、当 MCP server 包一层。
PlanLayer 状态机和自检
生成的 agent 用 PlanLayer 状态机管理执行：STARTING → PLANNING → EXECUTING → VERIFYING → REPLANNING → DONE，能合并已完成步骤、失败时分支、工具超时时优雅降级。
代码生成后还有 Phase 3.5 自检：agent 用 mock 参数跑一遍自己的 tools.py，抓未定义变量、None 属性崩溃、语义占位符。发现 bug 就让 LLM 重新生成函数体再检查，最多三轮。结果在 --report 里给出 READY 或 WARN 标签。
用法
pip install agenthatchagenthatch initagenthatch skills add ./my-skill/SKILL.mdagenthatch hatch my-skillagenthatch run my-skill
要求 Python 3.11+。三步从 Markdown 走到可运行 agent，生成的包可重跑、可版本化、可调试。和原始 SKILL.md 相比，运行时上下文从"全文塞 system prompt"压缩到约 150 字节的 runtime config。
如果手上维护超过三个 SKILL.md，可以花十分钟做一件事：把其中一个最复杂的 skill 用 agenthatch 跑一次 --dry-run，看看产出的 AHSSPEC 长什么样，再对比原始 Markdown 看看哪些隐式约定被显式化了。这一步能直接判断这套编译范式对自己工作流的收益是否值得引入。
