【手把手】用 agenthatch 把你的 skill 一键编译成独立 Python Agent读完这篇文章，你将学会：

读完这篇文章，你将学会：

用一条命令把 skill 编译成独立 Python 包
理解 agenthatch 的 3 阶段编译流水线
自定义 Agent 的运行时行为

写这个是因为我自己踩了太多坑，整理出来让别人少走弯路。

环境准备

pip install agenthatch
agenthatch init

选 DeepSeek（国内最方便）、OpenAI 或 Anthropic，填 API key。

Step 1：准备一个 skill

---
name: code-reviewer
description: Review code changes for bugs, style, and best practices
---

# Code Reviewer Agent

## Trigger Phrases
- "review this code", "code review", "check my code"

## Tools
- review_file(path: str) -> ReviewResult
- check_style(code: str) -> list[StyleIssue]
- suggest_fix(issue: str) -> str

Step 2：孵化

agenthatch hatch code-reviewer

终端输出：

▸ Phase 1/3  Context Assembly
✓  15 files indexed · 4.2 KB · 0.1 seconds
▸ Phase 2/3  Agentic Inference
✓  6 harnesses completed · 12.3 seconds
▸ Phase 3/3  Agent Generation
✓  18 files generated in 1.2 seconds

Step 3：看看生成了什么

code-reviewer-agent/
├── pyproject.toml
├── README.md
├── src/
│   └── code_reviewer/
│       ├── __init__.py
│       ├── __main__.py
│       ├── agent.py
│       ├── cli.py
│       ├── tools.py
│       └── config.py
└── skill

Step 4：运行

agenthatch run code-reviewer

交互式 TUI：输入 "review this file: src/main.py"，Agent 自动分析返回结果。

原理解析

agenthatch 的三阶段流水线：

Parse（不用 AI） ：提取 frontmatter、正文、文件清单。确定性，不引入 AI 随机性。
6-Harness LLM（asyncio 并发） ：6 个专门的 AI 模型并行工作——身份提取、意图推理、接口设计、基座检测、交叉校验、MCP 集成。每个只用做好一件事。试过一个超大 prompt 全搞定，输出不稳定。拆成 6 个后质量高了不止一个档次。
Jinja2 代码生成：把统一规约渲染成完整 Python 包。

PlanLayer 运行时：STARTING → PLANNING → EXECUTING → VERIFYING → REPLANNING → DONE。不是简单的 prompt wrapper，是真实运行时。

进阶技巧

# 预览不写入
agenthatch hatch my-skill --dry-run

![image.png](https://p9-xtjj-sign.byteimg.com/tos-cn-i-73owjymdk6/da2046585a0f443f89b5434df071d6cf~tplv-73owjymdk6-jj-mark-v1:0:0:0:0:5o6Y6YeR5oqA5pyv56S-5Yy6IEAgRXRlcm5hbFJpZ2h0cw==:q75.awebp?rk3s=f64ab15b&x-expires=1782310607&x-signature=o28rbMyDzaFAmr91Mzv6%2F4FAxcc%3D)
# 只生成 AHSSPEC（审查模式）
agenthatch hatch my-skill --no-generate

# 查看 Harness 推理过程
agenthatch hatch my-skill --trace

# 指定输出目录
agenthatch hatch my-skill -o ~/my-agents/

# 多 skill 管理
agenthatch search my-skill

我踩过的坑

"No API key configured"——忘了先跑 agenthatch init。这个错误信息不够友好，下个版本改。
输出目录冲突——第二次 hatch 同一个 skill 报 directory exists。加 --force 或换 -o。
DeepSeek 配置——选 custom provider，填 OpenAI-compatible endpoint。
生成的 tools.py 是空壳——没配 API key 就 hatch 的话，AI 工具实现会被跳过。配好 key 重跑。

⭐ GitHub: github.com/agenthatch/…
📦 pip install agenthatch
💬 欢迎提 issue 和 PR

项目还在早期（v0.9.16）。故事的起点是四月份滴滴推 skill，我写了一个巨详细的测试 skill 当工作交付——然后眼看着 Claude Code 把它当参考书随便翻。那个落差驱动了 agenthatch 的诞生。沈农大三，滴滴实习，下班和周末写的。第一次从零到一的开源项目。如果你也有类似的经历，试试这个工具，GitHub 见。