Four bugs fell out. The last one is the interesting one, because it sailed through three rounds of verification before a fresh virtualenv caught it lying.

Why a spellbook

The agenthatch test suite already had three knowledge bases when I started. One was a fictional Chinese sword sect (a parallel experiment — long story). The other two were real-world topics that LLMs have seen a thousand times: Aetheria, a made-up planet, and a Chinese mythical star. The problem with real-world KBs is that you can never tell whether the agent actually retrieved from the index or just hallucinated from training data. The D&D 5e SRD is technically real, but the long-tail mechanical details (exact damage dice, components, school) are easy to fact-check and easy to get wrong — which makes them a decent probe for "did retrieval actually run."

There's also a softer reason. Programmers and D&D players overlap a lot. If I'm going to spend a week hand-writing markdown about evocation spells, I'd rather write about fireballs than about quarterly revenue benchmarks. Sue me.

The KB itself was small. Twelve spells, one file each: fireball, fire bolt, magic missile, shield, counterspell, cure wounds, healing word, light, darkness, mage armor, misty step, eldritch blast. Plus a draft/secret-unreleased-spell.md to test that the exclude-patterns filter actually excluded things, and a stray api.secretfile to make sure secret-file conventions were caught.

That last file matters more than it sounds. If you tell users "we honor exclude patterns" and then quietly don't, you've built a leak. I wanted to know before any user did.

Bug #6: a YAML that lied to itself

The first thing I noticed was weird. After hatching, the agent's knowledge_base.py had constants TOTAL_CHUNKS = 45 and INDEX_SIZE_BYTES = 4096 baked in. Those come from the actual built index. But the agenthatch.yaml sitting next to the skill said total_chunks: 0, index_size_bytes: 0.

Same agent, same hatch run, two files disagreeing about basic facts.

The cause was a write-ordering bug. The hatch command wrote agenthatch.yaml at step 11, before Phase 3.5 ran the KB index build. Phase 3.5 mutated the spec in memory — bumping chunk counts from 0 to 45 — but only the agent-output copy of the YAML got the updated values. The skill-dir copy stayed stale because nothing went back to refresh it.

The fix was the obvious one: after generate() returns, re-dump the spec to the skill-dir YAML. It's a fifteen-line patch. The interesting part is that nobody had caught it for weeks, because the stale file lived in tests/fixtures/ and the test suite never read it back. Tests assert what you tell them to assert.

Bug #7: the dependency that wasn't

Next one. I ran pip install -e . on the generated agent and called retrieve("fireball"). Got back an empty list. Every time. For every query.

The generated knowledge_base.py does this: from agenthatch_core.bricks.knowledge.store import KnowledgeStore

But the generated pyproject.toml didn't list agenthatch-core as a dependency. So pip install -e .succeeded (because the import only fires at runtime, not at install time), and then retrieve() swallowed the ImportError inside _get_store()'s exception handler and returned [] for everything.

This is the worst kind of bug. The user sees no error. They see empty results. They probably blame the LLM, or the chunker, or themselves. They almost never blame the dependency list.

Fix was a Jinja conditional in pyproject.toml.j2: if kb_enabled, add agenthatch-core and sentence-transformers to the dependencies list. Two lines of template, plus a paragraph of comment explaining why.

Bug #8: a top_k that lied about its own contract

This one I found by reading code, not by running it. The KnowledgeStore.search() method had this: if top_k <= 0: top_k = 1

With a comment that said, with a straight face, "preserves the contract of returning at most top_k results" and "surfaces user intent of getting at least one result." Both claims were wrong. Returning 1 result when the user asked for 0 violates "at most top_k." And top_k=0 doesn't express intent for "at least one." It expresses intent for zero.

A user passing top_k=0 is asking for an empty list. Maybe they're warming up a UI. Maybe they're measuring latency without payload. Maybe they have a reason I can't predict. The job of the API is to honor the contract, not to second-guess it.

Fix: if top_k <= 0:return []

With a warning log so the call is still traceable. Negative top_k hits the same branch — SQLite would treat LIMIT -1 as "no limit" without the early return, which is its own kind of bug.

The lesson I keep coming back to: API contracts shouldn't have escape hatches for "what the user probably meant." If they meant 1, they'd pass 1.

Bug #4: the one that almost got away

This is where the story gets good.

The original Bug #4 was straightforward. The generated pyproject.toml declared packages = ["src/<pkg>"] and nothing else. When a user ran pip install, only the Python package shipped. The knowledge/ directory — containing the pre-built SQLite index — stayed on the developer's machine. At runtime, _KB_INDEX_DIR resolved to a path inside site-packages that didn't exist, and retrieve() returned [] for every query. Same failure mode as Bug #7, different root cause.

The fix had two parts. First, add force-include = { "knowledge" = "knowledge" } to the generated pyproject.toml so hatchling ships the directory in the wheel. Second, replace the single hardcoded path in knowledge_base.py with a resolver that tried multiple candidate locations — because dev layout and pip layout put knowledge/ in different places relative to the package.

I wrote the resolver like this: def _resolve_kb_index_dir() -> Path: here = Path(file).resolve().parent # / candidates = [ here.parent.parent / "knowledge", # pip layout (site-packages/knowledge/) here.parent.parent.parent / "knowledge", # dev layout (<agent_dir>/knowledge/)]for c in candidates:if c.exists():return c return candidates[-1]

I tested it three ways. Unit tests in test_kb_regressions.py — twelve of them, all passing. End-to-end Python script that called GenerateEngine.generate() directly, bypassing the LLM harness, then ran retrieve("fireball") on the generated agent. Three results, all from spells/fireball.md. Then a virtualenv with pip install -e . — editable install — and retrieve("fireball") returned 3 results, retrieve("magic missile") returned 2 results, retrieve("fireball", top_k=0) returned 0.

I marked Bug #4 as fixed and moved on.

The fourth verification, and the lie

I had one verification left that I almost skipped. The editable-install venv had passed. The unit tests had passed. The end-to-end script had passed. I was done, by any reasonable standard.

But something bugged me. Editable installs symlink back to the source tree. The __file__ of an editable-installed module resolves to the source path, not to a site-packages copy. Which means an editable install's layout is identical to the dev layout — the resolver's second candidate, the one labeled "dev layout," would always hit first for editable installs.

I had never actually tested a non-editable install.

So I built a fresh venv and ran pip install <agent_dir> — no -e. The install succeeded. The knowledge/directory showed up in site-packages, right where force-include said it would. I fired up a Python REPL and called retrieve("fireball").

Zero results.

The resolver returned _KB_INDEX_DIR = /private/tmp/dnd_venv3/lib/python3.14/site-packages/../knowledge — that's site-packages's parent, which doesn't exist. The fallback path returned a directory that wasn't there, and _get_store() logged a warning that nobody would see.

The bug was in my candidate list. Look at the resolver again: here.parent.parent / "knowledge" # I called this "pip layout"

For an editable install, here resolves to <agent_dir>/src/<pkg>/. Two levels up is <agent_dir>/, and knowledge/ lives there. That's why it worked.

For a non-editable install, here is <site-packages>/<pkg>/. Two levels up is <site-packages>'s parent — typically <python>/, which has no knowledge/ directory. The actual knowledge/ shipped by force-include lives one level up from <pkg>/, at <site-packages>/knowledge/. That's here.parent / "knowledge". Not two levels up.

I had an off-by-one error in my "pip layout" candidate, and editable installs had been quietly covering for me.

The fix was a one-line change: candidates = [ here.parent / "knowledge", # non-editable pip layout here.parent.parent / "knowledge", # dev / editable layout]

I added three regression tests that exec the rendered resolver against a fake __file__ pointing at each layout. Pip layout passes. Dev layout passes. When both directories exist, the pip-layout candidate wins because it's listed first — which is what we want, because pip layout is what users actually hit.

Then I rebuilt the venv, reinstalled, and ran retrieve("fireball") one more time. Three results. spells/fireball.md, spells/fire-bolt.md, spells/counterspell.md. retrieve("magic missile")returned 2. retrieve("fireball", top_k=0) returned 0.

The off-by-one was a thirty-second fix. Finding it took a fresh venv and a willingness to test the install path that nobody on the team had bothered to test, because editable installs are faster and we're all impatient.

What I actually learned

Editable installs lie. They symlink back to source, which means any path resolution that happens to work in your dev checkout will also work in an editable install — for the wrong reason. The bug only surfaces when you test the install path your users actually use, which is pip install <dir>, not pip install -e <dir>.

This isn't a new lesson. It's the same lesson as "run your tests on CI, not just on your laptop." But it keeps needing to be relearned, because editable installs are convenient and convenience is seductive.

The other thing. When I wrote the resolver, I labeled the candidates with comments — "pip layout" and "dev layout." The comments were wrong about which was which. The tests passed anyway, because I was testing the labels, not the layouts. If I'd named the candidates one_level_up and two_levels_up instead, I would have caught the off-by-one in five seconds. Naming matters. Labels that describe intent rather than mechanism are a tax you pay later.

The whole bug hunt took a week. Four bugs, sixteen regression tests, four verification rounds. The D&D spellbook sage now lives in tests/fixtures/skills/dnd-spell-advisor/, and it'll keep stress-testing the RAG pipeline for as long as anyone runs the test suite. Which, given that this is open source, is probably forever.

Twelve spells. Four bugs. One near-miss. Not bad for a week of fake fireballs.

agenthatch is open source: github.com/agenthatch/agenthatch

Then I watched Claude Code run it.

My strict requirements, the ones in bold, the ones that said "check environment variables first" and "exit immediately on type X errors"? The model skimmed past them like they were terms of service. It treated the skill as a reference book, not a contract. Every run, the interpretation drifted a little. One run it drifted far enough that a bug which should have died in staging almost made it to production.

That was the night I decided skills shouldn't be interpreted. They should be compiled.

I'm an agent developer intern at DiDi and a junior CS student. I build this stuff for a living. And I'm tired of watching LLMs selectively ignore prose that took me weeks to write. So I built agenthatch. It turns a SKILL.md into a standalone, pip-installable Python agent with typed tools, a state machine, and its own runtime. Not a prompt wrapper. Actual generated code.

pip install agenthatch
agenthatch init
agenthatch skills add ./my-skill/SKILL.md
agenthatch hatch my-skill
agenthatch run my-skill

Three commands from markdown to a running agent. The rest of this post is the why and the how, with source file references so you can verify I'm not making this up.

The problem isn't your skill. It's the format.

Let me be precise about what's broken.

A SKILL.md file is prose. Human-written prose for humans to read. You then paste it into a system prompt and ask an LLM to figure out what you meant, at runtime, every single turn.

One skill, fine. Three skills, manageable. Five or more? Things break.

This isn't an Anthropic bug or an OpenAI bug. It's not your skill being bad either. It's architectural decay. You're asking one LLM to interpret seven pieces of zero-isolation prose in the same context window, and the interpretation shifts every run.

Think about it this way: you hand someone seven operating manuals and ask them a question. They have to flip through all seven books every time and stitch an answer together. That person would lose their mind. The LLM does too, just quietly.

The core issue is that SKILL.md is prompt engineering, not software engineering. There's no compile step, no type checking, no contract between you and the model.

The thesis: skills are source code, agents are binaries

This is the part I want you to actually think about, even if you skip the rest.

Right now everyone is writing skills. For Claude Code, for Codex CLI, for OpenClaw, for whatever comes next. And in all of these, the skill's role is the same: it's prose stuffed into a system prompt, interpreted at runtime by a host agent. The skill is a prompt accessory. It can't exist on its own.

That's the wrong paradigm.

Skills shouldn't be prompt accessories. Skills should be agent source code.

Java compiles to bytecode for the JVM. TypeScript compiles to JavaScript for the browser. The compile step exists because it converts human expression into a format the machine can execute deterministically, before runtime. Typos, type errors, ambiguity, all of it gets caught at compile time, before the agent ever runs.

SKILL.md has no compile step. It hands raw prose to an LLM and hopes for the best, every turn, forever.

So the endgame for skills isn't "write them better." It's "compile them into agents." A skill should be the hatching input for an agent. You write the skill, a compiler turns it into an independent runtime with its own tools, its own state machine, its own config. The skill stops being a prompt fragment and becomes a program.

That's what agenthatch does. You still write skills in markdown, that part doesn't change. The generated agent runs independently, no host required. agenthatch is the step in between, the compiler. javac is to .java what agenthatch is to SKILL.md.

Once you internalize this, a bunch of things click into place:

• Skills stop burning tokens in the system prompt. Compiled agents carry about 150 bytes of runtime config.

• Each skill becomes an isolated agent. No more cross-contamination.

• Schema validation happens at compile time. Typos and ambiguity die before runtime.

• The output is a real Python package. pip install, import, run it anywhere, no host required.

The pipeline: three phases, six harnesses

Here's the architecture. Every file path I mention is real, you can open it in the repo.

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

Phase 1: deterministic parse, zero AI

Phase 1 doesn't use AI. It reads the SKILL.md, pulls out the frontmatter, the body, and every file in the skill directory. Pure filesystem operations. The entry point is assemble_context() in parser.py:

def assemble_context(skill_path: str | Path) -> ContextPack:
    skill_dir = _resolve_skill_directory(Path(skill_path))
    dir_name = skill_dir.name
    manifest = _discover_files(skill_dir)
    frontmatter, body, warnings = _best_effort_parse_yaml(skill_dir)
    return ContextPack(frontmatter, body, manifest, dir_name, warnings, skill_dir)

The key design decision here: Phase 1 makes no semantic judgment. It doesn't try to guess whether a file is a script, a doc, or a config. That's Phase 2's job. Phase 1 just reads bytes, computes SHA-256 hashes, and does YAML parsing.

There's a small detail I like in the file reader. It checks binary magic numbers to skip PNGs, JPEGs, PDFs, ZIPs, and friends:

_BIN_SIGS: list[bytes] = [
    b"\x89PNG\r\n\x1a\n",
    b"\xff\xd8\xff",
    b"GIF89a",
    b"%PDF",
    b"PK\x03\x04",
    b"Rar!\x1a\x07",
    b"\x1f\x8b",
    b"BZh",
    b"\xca\xfe\xba\xbe",
]

Files over 1MB get skipped. Files with null bytes in the header get skipped. If something can be handled deterministically, don't ask an LLM. That principle shows up over and over in this codebase.

Phase 1.5: AST signature extraction

This was added in v0.8 and I think it's the most underrated part of the whole project.

Phase 1.5 uses Python's built-in ast module to parse Python scripts and regex to parse shell scripts, extracting function signatures. Deterministic, zero LLM. This feeds into Harness C for precise interface inference.

def extract_python_signatures(file_path: Path) -> list[ToolSchema]:
    """AST-parse a Python script, extract public function signatures.
    Deterministic, zero LLM. Uses Python's built-in ast module.
    Skips private functions (those starting with _).
    """
    try:
        tree = _ast.parse(file_path.read_text(encoding="utf-8"))
    except (SyntaxError, UnicodeDecodeError, OSError):
        return []

    functions: list[ToolSchema] = []
    for node in _ast.walk(tree):
        if isinstance(node, _ast.FunctionDef) and not node.name.startswith("_"):
            args: list[dict[str, str | None]] = []
            for arg in node.args.args:
                arg_type: str | None = None
                if arg.annotation:
                    try:
                        arg_type = _ast.unparse(arg.annotation)
                    except Exception:
                        arg_type = None
                args.append({"name": arg.arg, "type": arg_type})
            functions.append(ToolSchema(...))
    return functions

Why bother? Because Harness C has to design tool signatures. If it reads raw script contents, it burns tokens and hallucinates. Hand it a 1KB compact signature summary extracted via AST, and the inference quality jumps. This is compiler thinking: extract deterministically whatever you can, leave only the genuinely ambiguous stuff for the LLM.

Phase 2: six AI harnesses

This is the heart. Six specialized harnesses process the skill, each with its own persona and temperature. The config is hardcoded in engine.py:

HARNESS_CONFIG: dict[str, dict[str, Any]] = {
    "A": {"thinking": True, "temperature": 0.1,
          "reason": "Identity extraction is deterministic — low temp for consistency"},
    "B": {"thinking": True, "temperature": 0.5,
          "reason": "Intent inference requires creativity for long-tail triggers"},
    "C": {"thinking": True, "temperature": 0.5,
          "reason": "Interface inference is complex — needs SKILL.md + ScriptManifest"},
    "D": {"thinking": True, "temperature": 0.3,
          "reason": "Base detection needs precision — moderate temp"},
    "E": {"thinking": True, "temperature": 0.2,
          "reason": "Assembly validation is structured — low temp for consistency"},
    "F": {"thinking": True, "temperature": 0.3,
          "reason": "MCP config extraction needs exact matching — moderate temp"},
}

Every temperature has a reason. Identity extraction is deterministic, so temp drops to 0.1. Intent inference needs to cover long-tail triggers, so it gets 0.5 for creativity. Assembly validation is structured, so 0.2.

Why six? Because I tried one giant prompt that did everything, and the output was a lottery. Splitting it up so each harness does one thing, quality went up significantly. Same reason compilers split the frontend into lexer, parser, semantic analysis. Single responsibility.

Each harness runs an Analyze, Infer, Self-Validate, Correct loop with up to two internal retries. Every harness has its own validate_output(). Harness A checks that identity.id is kebab-case:

def validate_output(self, result: dict[str, Any]) -> tuple[bool, str]:
    identity = result.get("identity", {})
    identity_id = identity.get("id", "")
    if not identity_id:
        return False, "identity.id is empty"
    if not re.match(r"^[a-z0-9]+(-[a-z0-9]+)*$", identity_id):
        return False, f"identity.id '{identity_id}' is not kebab-case"
    if not identity.get("display_name"):
        return False, "identity.display_name is empty"
    return True, ""

Harness B checks that triggers count is between 5 and 15, satisfies between 3 and 8, summary at least 20 characters. These constraints aren't the LLM's call. They're enforced by code. If the LLM produces non-compliant output, it gets sent back to redo.

Harness E is the critical one. It cross-validates the other five and produces a unified AHSSPEC (Agent Hatch Standard Specification). E also computes a structural confidence score, and this is important: it's not LLM self-assessment, it's code counting fields:

def _compute_structural_confidence(self, ahs_dict: dict[str, Any]) -> float:
    """Compute confidence based on structural checks, not LLM self-assessment."""
    checks = 0
    passed = 0
    id_ = ahs_dict.get("identity", {})
    for f in ("id", "display_name", "version"):
        checks += 1
        if id_.get(f): passed += 1
    iface = ahs_dict.get("interface", {})
    for f in ("provides", "requires"):
        checks += 1
        if iface.get(f): passed += 1
    score = round(passed / max(checks, 1), 2)
    return score

I don't trust LLM self-reported confidence. The model will cheerfully tell you "0.95 confidence" while missing three required fields. Code counting fields doesn't lie.

There's also a pre-flight classifier that picks model tiers per skill type. A pure-instruction skill skips Harness D entirely (no base class to detect). An integration skill with API calls and scripts upgrades everything to large models. Not every skill deserves the expensive model. The classifier saves real money.

MODEL_TIER_MAP: dict[str, dict[str, str]] = {
    "pure_instruction": {
        "A": "small", "B": "small", "C": "large", "D": "skip", "E": "small", "F": "small",
    },
    "script_driven": {
        "A": "small", "B": "small", "C": "large", "D": "large", "E": "small", "F": "small",
    },
    "integration": {
        "A": "small", "B": "large", "C": "large", "D": "large", "E": "large", "F": "small",
    },
    "knowledge": {
        "A": "small", "B": "large", "C": "large", "D": "small", "E": "small", "F": "small",
    },
}

Phase 3: code generation

Phase 3 renders the AHSSPEC into a complete Python package via Jinja2 templates. The engine is GenerateEngine in generate/engine.py:

TEMPLATE_MAP: dict[str, str] = {
    "pyproject.toml.j2": "pyproject.toml",
    "agent.py.j2": "src/{package_name}/agent.py",
    "tools.py.j2": "src/{package_name}/tools.py",
    "references.py.j2": "src/{package_name}/references.py",
    "runtime.toml.j2": "runtime.toml",
    "README.md.j2": "README.md",
}

But Phase 3 isn't just template rendering. There's an AI code generation step. _ai_generate_tool_impls() reads the full skill directory context (SKILL.md, reference files, script files, templates) and has the LLM generate real Python function bodies for each tool. Not stubs.

The critical part is validation. AI-generated code doesn't get written to disk directly. It gets compile()-checked first. If it fails, the engine tries to auto-fix indentation:

wrapper = "def _validate():\n" + indented + "\n"
try:
    compile(wrapper, f"<tool:{func_name}>", "exec")
except SyntaxError as se:
    try:
        fixed = GenerateEngine._normalize_indentation(indented_lines, error_lines)
        fixed_wrapper = "def _validate():\n" + fixed_str + "\n"
        compile(fixed_wrapper, f"<tool:{func_name}>", "exec")
        indented = fixed_str
        valid = True
    except SyntaxError:
        pass

if valid:
    valid_tools[func_name] = indented
else:
    logger.warning(
        "AI-generated code for tool '%s' has syntax errors, skipping. "
        "Tool will use template fallback.", func_name,
    )

This is the compiler's attitude. Generated code must compile. If it doesn't, fix it. If it can't be fixed, fall back to a template stub. Never let syntactically broken code reach runtime.

There's also a _validate_generated_python() pass that scans every generated .py file for JavaScript keywords that leaked in (null, undefined, true, false). Added in v0.7.15 after I watched an LLM try to write Python like it was TypeScript one too many times.

What comes out

The output is a real Python package:

hatched-agent/
├── pyproject.toml          # pip-installable
├── runtime.toml            # LLM provider, model, API keys
├── README.md               # generated usage docs
├── agenthatch.yaml         # AHSSPEC manifest
└── src/{package_name}/
    ├── __init__.py
    ├── agent.py            # Agent class (extends AHCoreAgent)
    ├── tools.py            # type-annotated tool implementations
    └── references.py       # AI-extracted structured data

You can pip install it. You can import it. You can run it as a CLI. You can wrap it as an MCP server. It doesn't depend on Claude Code, Codex, or any host agent. It's a program.

The generated agent also carries a full copy of its source skill directory. It can read its own SKILL.md at runtime for self-reference, execute its own scripts, and self-repair when things go sideways. Like a compiled binary with debug symbols, not a stripped binary.

The runtime: PlanLayer state machine

The generated agent doesn't run a naive ReAct loop. It uses a 6-state PlanLayer state machine, defined in plan.py:

class AgentState(str, Enum):
    STARTING = "starting"       # initial state, waiting for plan
    PLANNING = "planning"       # generating/updating plan
    EXECUTING = "executing"     # executing plan steps
    VERIFYING = "verifying"     # checking results
    REPLANNING = "replanning"   # hit a blockage, revising plan
    DONE = "done"               # terminal state

The agent generates a structured plan via a virtual plan tool at session start, then executes steps with explicit state tracking. Three consecutive tool failures trigger REPLANNING. State transitions are managed by the loop, not the LLM. The LLM is unreliable. State machines are reliable.

class PlanLayer:
    MAX_CONSECUTIVE_FAILURES = 3
    VERIFY_EVERY_N_STEPS = 5

The plan renders into the system prompt so the agent can see its own progress:

## Plan: Add i18n to the project
  ☐ Step 1: Install next-intl
  ▶ Step 2: Create language packs
  ☐ Step 3: Configure middleware
Progress: 1/3 steps done

Model support: pick your poison

agenthatch supports OpenAI, Anthropic, DeepSeek, and any OpenAI-compatible endpoint. The harness system picks model tiers per task, so you can mix providers.

I've been testing with Claude Opus 4.5 for the large-tier harnesses (C and D, the ones doing interface and base detection) and GPT-5.2 Codex for comparison runs. Opus 4.5 is genuinely good at structured interface inference, the kind of task where you want the model to design a clean tool signature without inventing parameters. GPT-5.2 Codex is faster on the small-tier harnesses (A, B, E, F) where the job is extraction and validation, not design.

The point is: you're not locked in. The harness config is just a dict. Swap models per harness, swap providers, run the same SKILL.md through different stacks and diff the output. That's the kind of thing you can't do when your skill is glued to a host agent's system prompt.

What's still broken

I'm not going to pretend this is finished.

• Python only. JS/TS support is in progress. If you want a Node agent, not today.

• You need an LLM API key. Phase 2 is AI inference. No key, no hatch.

• Single-file skills work. Multi-file directory skills are in development.

• It's v0.9.x. There are bugs. I find new ones every week.

• Windows is untested. I develop on macOS and Linux. Windows users, tell me what breaks.

I've shipped 8 PRs to pytest and 1 to agent-browser. agenthatch is my first from-scratch project, built nights and weekends. "Ship beats perfect" is the most useful thing I learned from open source. This tool isn't perfect, but it runs, and the rest gets fixed in flight.

Try it

If you maintain more than three SKILL.md files and feel the friction, this is for you.

pip install agenthatch
agenthatch init
agenthatch skills add ./my-skill/SKILL.md
agenthatch hatch my-skill
agenthatch run my-skill

Repo: github.com/agenthatch/agenthatch​

PyPI: pypi.org/project/agenthatch​

If you hit bugs, file an issue. If you want to argue about the paradigm, the discussions tab is open. And if you think skills should stay as prompt fragments, I genuinely want to hear why, because I might be wrong and I'd rather find out now than after writing another 2,000 lines of compiler.

Skills are source code. Agents are binaries, and the compiler is the part everyone's been skipping.

​