agenthatch

Turn any SKILL.md into a standalone, runnable AI Agent.

The problem with SKILL.md

SKILL.md promised a lot. Write a markdown file, tell your agent what to do, and it works. In practice, anyone who has used more than three skills across Claude Code, Codex CLI, or OpenClaw knows the friction:

The core issue isn't the format. It's that SKILL.md is prompt engineering, not software engineering. You're asking an LLM to interpret human prose at runtime, every time, with no compilation, no type checking, no contract.

What agenthatch does

agenthatch treats a SKILL.md as source code — not a prompt. It compiles it through a deterministic pipeline into a standalone Python agent that you can import, ship, and run anywhere.

SKILL.md  →  Parse  →  6-Harness LLM Pipeline  →  Code Generation  →  Runnable Agent
   (input)   (Phase 1)    (Phase 2: AI inference)     (Phase 3: Jinja2)     (output)

The result is a self-contained Python package with its own pyproject.toml, a CLI entry point, typed tool definitions, MCP integration, and a runtime configuration. It's not a wrapper around your skill — it is the skill, compiled into code.

Quick Start

# Install
pip install agenthatch

# Initialize with your LLM provider
agenthatch init

# Add a SKILL.md
agenthatch skill add ./my-skill/SKILL.md

# Hatch it into an agent
agenthatch hatch my-skill

# Run it
agenthatch run my-skill

Three steps from markdown to running agent. The hatched agent lives in your skillhouse and can be re-run anytime.

SKILL.md vs agenthatch

Architecture

agenthatch runs a 3-phase pipeline with 6 AI harnesses working in parallel:

Phase 1: Deterministic Parse (no AI)

The SKILL.md is parsed for frontmatter, body, and directory files. No AI involved. A pure file-system operation. The output is a ContextPack with zero semantic transformation.

Phase 2: 6-Harness LLM Inference

Six specialized AI harnesses process the skill, each with its own persona and temperature profile:

Each harness runs an Analyze → Infer → Self-Validate → Correct loop with up to 2 internal retries. Harness E cross-validates the other five outputs and produces a unified AHSSPEC (Agent Hatch Standard Specification).

Phase 3: Code Generation

Jinja2 templates render the AHSSPEC into a complete Python agent package:

hatched-agent/
├── pyproject.toml          # pip-installable package
├── runtime.toml            # LLM provider, model, API keys
├── README.md               # Generated usage docs
├── agenthatch.yaml         # AHSSPEC manifest
├── skills/                 # Original SKILL.md + bundled resources
├── knowledge/              # KB index (knowledge-base agents only)
└── src/{package_name}/
    ├── __init__.py
    ├── agent.py            # Agent class (extends AHCoreAgent)
    ├── tools.py            # Type-annotated tool implementations
    └── references.py       # AI-extracted structured data

Phase 3.5: Post-generation self-review

After generation, the agent inspects its own tools.py for undefined variables, None-attribute crashes, and semantic stubs. Each tool runs once with mock parameters to catch runtime errors. When bugs are found, the LLM regenerates the broken function body and re-inspects (up to 3 rounds). The verdict (READY / WARN) shows up in --report and --json. Use --no-postgen-review to skip.

Runtime: PlanLayer

Generated agents use the PlanLayer state machine — a 6-state planning engine that runs STARTING → PLANNING → EXECUTING → VERIFYING → REPLANNING → DONE. It adapts mid-task: merges completed steps, branches on failure, and degrades gracefully when tools time out.

Knowledge-base agents (RAG-native)

Pass a second positional — a directory of reference files — and the pipeline gains a Phase 2.5 KB stage: the corpus is indexed into a local SQLite FTS database, retrieval rules are inferred from the skill, and the generated agent gets a wired-in retrieve() tool (the knowledge-base archetype):

agenthatch hatch my-skill ./my-knowledge-base

The hatched agent answers strictly from the indexed archive, cites the source file for every claim, and reports honestly when a request falls outside the index.

How it works under the hood

Phase 1 (deterministic): Parse SKILL.md → ContextPack
Phase 2 (AI): 6 harnesses → HarnessOutput → Assembly → AHSSPEC
Phase 3 (Jinja2): AHSSPEC → agent package

CLI Reference

Installation

pip install agenthatch

Requires Python 3.11 or later. Runs on macOS, Linux, and Windows.

For development:

git clone https://github.com/agenthatch/agenthatch.git
cd agenthatch
pip install -e ".[dev]"

Documentation

Community

• GitHub Discussions — questions, ideas, roadmap
• GitHub Issues — bugs and feature requests
• X (Twitter)

Contributing

agenthatch is a solo project looking for its first contributors. Issues, pull requests, documentation, design -- every bit moves the project forward.

See CONTRIBUTING.md for dev setup, the quality gate (hatch run quality:check), and PR guidelines.

AI-assisted contributions are welcome. Run the quality gate before submitting — that's all that matters.

FAQ

Who is this for?

Anyone who maintains more than 3 SKILL.md files and feels the friction. Claude Code users, Codex CLI users, OpenClaw users — if you've ever thought "I wish this skill was a real program," this is for you.

Can I use this with Claude Code / Codex / OpenClaw?

Yes. The hatched agent is a standalone Python package. You can run it as a CLI, import it as a library, or wrap it as an MCP server. It doesn't depend on any specific agent platform.

What MCP servers are supported?

Any MCP server that speaks the standard protocol. Harness F auto-detects MCP servers referenced in your SKILL.md and configures them in the generated agent's runtime.

Does this replace SKILL.md?

No. SKILL.md is the input format. agenthatch is the compiler. You still write skills in markdown — agenthatch turns them into agents.

License

MIT — see LICENSE for details.

_{📖 简体中文版请见 README_CN.md}