Soushi888/holochain-agent-skill: The AI Playbook for Not Breaking Holochain

Why this repo exists: AI needs guardrails in Holochain

Holochain is not a forgiving stack. The rules around determinism, validation, and zome boundaries are easy to blur, and a general-purpose assistant will happily blur them for you. This repo exists to stop that drift before it becomes a broken app or a live DHT full of avoidable mistakes.

The interesting part is not that it documents Holochain. It packages expertise into a format an AI tool can consume automatically, which makes the repo feel closer to a control system than a manual. In this stack, that difference matters.

The router in the middle: how SKILL.md decides what happens next

At the center is SKILL.md, which behaves like a dispatch layer. It detects the task, maps the intent to a workflow, and keeps the assistant from freewheeling across architecture, scaffolding, testing, and deployment.

| Intent | Workflow |
| --- | --- |
| Design data model | Architecture and Patterns |
| Review access control | AccessControl.md |
| Scaffold a project | Workflow scaffold |
| Check compatibility | Version and upgrade guidance |

That routing matters because AI assistants are good at recall and weak at judgment. A workflow table gives the model a preferred path, and the proactive invocation rule means the skill can enter the conversation before bad assumptions harden.

The real story is the split: integrity zomes are not coordinator zomes

This is the core Holochain boundary, and the repo treats it like a hard law. Integrity zomes are where pure validation lives. Coordinator zomes are where I/O, network calls, and agent-facing behavior belong. Mixing them is how you get code that looks plausible and behaves badly.

The point is not just architectural neatness. The point is consistency across a distributed network, where validation must be deterministic and repeatable. Once you see that split clearly, a lot of the repo’s rules start to feel less like linting and more like survival.

The repo encodes the mistakes people keep making

The guardrails are specific because the failure modes are specific. Exact version pins like =0.6.0 keep examples from drifting into incompatible APIs. serde(default) protects old data from breaking when schemas evolve. Pure validation keeps runtime calls out of logic that must remain deterministic.

// Example pattern the skill cares about
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq)]
pub struct MyEntry {
    #[serde(default)]
    pub title: String,
    pub body: String,
}

// The point: old entries still deserialize when fields are added later.

This is where the repo stops looking like docs and starts looking like policy. It maps known mistakes to concrete constraints, which is exactly what AI tools need if they are going to be trusted in a sharp-edged framework.

Patterns, not recipes: how the skill teaches mutable graph thinking

Holochain is a graph problem as much as it is a coding problem. The repo leans on patterns like implicit versus explicit links, capability grants, and update tracking to teach that mental model. It is not just telling the assistant what to type. It is teaching it how to think about change in an append-only system.

That is the deeper value here. The skill is not merely a folder of references. It is a compressed apprenticeship for a domain where the wrong instinct is usually the expensive instinct.

What this tells us about the future of developer tooling

The best comparison is not Holochain versus some other framework. It is generic documentation versus domain-specific execution guidance. Generic docs tell you what exists. This kind of skill tells an AI system how to behave inside a narrow, difficult domain.

That is the real bet. As AI tooling gets more embedded in development, the winning interface may be less about bigger models and more about better constraints. In specialized frameworks, the future may belong to skills that teach the assistant how not to be wrong.