Holochain Development Skill

Expert assistant for Holochain hApp development. Covers the full development spiral: architecture, design, scaffolding, implementation, testing, and deployment.

Proactive Invocation Rule

Always invoke this skill in the PLAN phase when the task touches a Holochain project. Do not wait to be asked explicitly.

Trigger conditions — any of these means the skill should be loaded before coding begins:

• Working directory is a Holochain project (contains workdir/*.happ or dnas/*/zomes/)
• Task involves .rs files inside zomes/coordinator/ or zomes/integrity/
• Task involves entry types, link types, cross-DNA calls, or zome functions
• Task involves a PR on a Holochain project

When proactively invoked: load references/architecture.md + references/patterns.md, run the ReviewZome checklist against any files being modified, surface issues before implementation begins.

Workflow Routing

Context Files

Load on demand based on task:

Quick Reference

Versions (current stable):  hdk = "=0.7.0"   hdi = "=0.8.0"   holonix ref=main-0.7
Client / tooling:           @holochain/client 0.21.0   hc-spin 0.700.0   nodejs_24
Dev commands:  nix develop  |  hc sandbox clean  |  cargo test
Build zomes:   RUSTFLAGS='--cfg getrandom_backend="custom"' cargo build --release --target wasm32-unknown-unknown
Scaffold:      hc scaffold entry-type MyEntry  |  hc scaffold link-type AgentToMyEntry

Toolchain currency

Verified against live registries and git refs on 2026-08-20. Re-verify before trusting these past a Holochain minor release.

Scaffolder version trap. Holonix main-0.7 ships hc-scaffold 0.700.0-rc.0, not the stable v0.700.0. The rc emits holonix?ref=main and -rc crate pins, and its generated validate() does not compile against the stable hdi 0.8.0 it also pins. Install the stable scaffolder alongside holonix rather than using the bundled one:

nix run github:holochain/scaffolding/v0.700.0 -- web-app my-app
# or: cargo install holochain_scaffolding_cli --version 0.700.0 --locked

Always pass --version. cargo install holochain_scaffolding_cli with no version installs 0.4000.4, a Holochain 0.4-era scaffolder. This crate’s version history mixes numbering schemes, and semver orders 0.4000.4 above 0.700.0, so crates.io reports the old release as the latest stable one. Verified 2026-08-17: the crates.io API returns "max_stable_version":"0.4000.4" while 0.700.0 sits further down the version list.

references/troubleshooting.md lists each rc symptom and its fix if you are stuck with the bundled binary.

Companion libraries: what is actually on 0.7

Verified against npm and each repo’s Cargo.toml on 2026-08-17. Version numbers in this ecosystem are not reliable signals, so check the pins rather than the tag.

Unstable feature gates

Holochain 0.7 keeps several capabilities behind Cargo features that are off by default. Default features on holochain 0.7.0 are encryption, schema, wasmer-sys-cranelift only. Turning any of these on means building and shipping your own conductor, which stock holonix and Kangaroo binaries will not have.

Agent key management (DeepKey / DPKI) is not in the SDK. There is no dpki or deepkey surface anywhere in hdk 0.7.0 or hdi 0.8.0. It exists as a separate, still-unstable conductor service. Do not expect key rotation or key-to-person binding APIs from a zome.

Common Pitfalls Checklist

Run this against any zome code being written or reviewed. Each item is a class of bug that has burned projects before.

Entry Schema Evolution

• #[serde(default)] on new optional fields — Any field added to an existing entry struct after initial deployment MUST have #[serde(default)]. Without it, existing entries serialized before the field existed will fail to deserialize. Option<T> alone is NOT sufficient.

  #![allow(unused)]
  fn main() {
  #[serde(default)]          // ← REQUIRED for fields added post-deployment
  pub new_field: Option<ActionHash>,
  }

Cross-DNA Calls

• ZomeCallResponse is exhaustive — 0.7 has 5 variants: Ok(ExternIO), AuthenticationFailed(Signature, AgentPubKey), Unauthorized(ZomeCallAuthorization, Option<CapSecret>, ZomeName, FunctionName), NetworkError(String), CountersigningSession(String). Note Unauthorized carries no AgentPubKey in 0.7. Wildcard _ is safe but hides new variants. Exhaustive match is preferred.
• Role name matches happ.yaml — CallTargetCell::OtherRole("role_name") must exactly match the role name in workdir/happ.yaml. Typos fail silently at runtime.
• Zome name matches coordinator crate name — ZomeName("zome_name") must match the coordinator’s name in Cargo.toml. Check both.
• Local mirror structs for cross-DNA types — Avoid importing the remote DNA’s Cargo crate. Define a local serialization mirror struct instead.

Validation Rules

• No non-deterministic reads in validate() — no get(), get_links(), agent_info(), sys_time(). DHT reads ARE allowed through must_get_*, which defers on an unresolved dependency instead of failing. Everything else comes from the op itself.
• Use op.flattened::<EntryTypes, LinkTypes>() — Not the old op.to_type(). references/patterns.md has the correct pattern.
• Narrow actions with TypedAction::<D>::try_from_action(...)? — Not let r: Result<_, WrongActionError> = action.try_into(); followed by map_err(|e| wasm_error!(...)). try_from_action returns ExternResult and drops into a ?-chain directly. TypedAction<CreateData> and TypedAction<UpdateData> widen into TypedAction<EntryCreationData> infallibly with .into().
• A shape sys validation already guarantees is an error, not Invalid — if a DeleteLink’s target is not a CreateLink, propagate with ?. Returning ValidateCallbackResult::Invalid blames the author for a fault in how the op reached your code.
• TypedAction<D> derefs to D — action.data.entry_hash and action.entry_hash both work for reads. Keep action.data.x where you need to move the field out, since Deref only lends.

HDK 0.7 Get and Link API

• delete_link() requires GetOptions — delete_link(hash, GetOptions::default()) not delete_link(hash).
• get_links() takes a LinkQuery plus a GetStrategy — get_links(LinkQuery::try_new(base, LinkTypes::X)?, GetStrategy::default()). Not GetLinksInputBuilder for most cases.
• GetStrategy::Local vs Network — Use Local for own-data queries (fast, no network), Network for DHT queries (cross-agent data).

Shared Utility Patterns (project-specific)

• agent_pub_key and created_at are NOT entry fields — They live in the action header. Remove them from entry structs.
• If using a shared utility crate — verify intra-DNA and cross-DNA call helpers are used consistently rather than raw call() inline.

Examples

Example 1: Design a new entry type for a marketplace listing

User: "I need to model a Listing entry with status transitions"
→ Loads references/patterns.md (entry types, status enum, link types)
→ Designs ListingStatus enum (Active/Archived/Deleted)
→ Defines link types (AgentToListing, PathToListing, ListingUpdates)
→ Implements soft-delete via status field update, not entry deletion

Example 2: Debug a cross-agent test that fails intermittently

User: "My Sweettest passes alone but fails when another agent reads the entry"
→ Loads references/testing.md
→ Identifies missing await_consistency call before cross-agent read
→ Adds await_consistency(&cells).await.unwrap() after Alice's create, before Bob's get
→ Test passes reliably

Example 3: Scaffold a new hApp from scratch

User: "Start a new Holochain project for a community coordination app"
→ Loads references/scaffolding.md + references/workflows/scaffold.md
→ If hc scaffold CLI is available: guides nix flake setup → hc scaffold happ → entry types
→ If no CLI (AI coding session): invokes references/workflows/manual-scaffold.md → writes identical structure
→ Both paths produce the same standard hc scaffold architecture
→ Verifies compilation with hc s sandbox generate workdir/

Example 4: Implement CRUD for a new zome

User: "Implement a full resource zome with create, read, update, delete"
→ Loads references/architecture.md + references/patterns.md
→ Invokes references/workflows/implement-zome.md
→ Creates integrity crate (entry struct, link enum, validation)
→ Creates coordinator crate (create/read/update/delete functions)
→ Writes Sweettest tests at foundation + integration layers