heyAyushh · rohan-tessl · Apr 6, 2026
diff --git a/SKILL.md b/SKILL.md
@@ -1,19 +1,15 @@
 ---
 name: hook-serve
-description: >
-  Build, maintain, and operate the contract-driven hook workspace with
-  serve/relay/smash roles, Kafka core transport, and plug-and-play adapters.
-  Use when editing runtime behavior, contract validation, adapter/plugin
-  execution, or deployment documentation.
+description: "Configure Kafka topics, validate hook contracts, register ingress/egress adapters, and manage serve/relay/smash runtime roles in the contract-driven hook workspace. Use when adding a webhook source, writing or debugging a contract.toml, implementing an adapter or plugin, changing event routing, or updating deployment and operator documentation."
 ---
 
 # Hook Serve Workspace Skill
 
 ## Workspace Map
 
-- `src/`: serve runtime (`hook-serve`)
-- `tools/hook/`: operator CLI for role execution and ops workflows
-- `apps/default-openclaw/`: canonical compatibility contract
+- `src/`: serve runtime (`hook-serve`) — HTTP/WebSocket/MCP ingress, rate limiting, health checks
+- `tools/hook/`: operator CLI (`hook serve`, `hook relay`, `hook smash`, `hook debug`)
+- `apps/default-openclaw/`: canonical compatibility contract (`contract.toml`)
 - `apps/kafka-openclaw-hook/`: compatibility wrapper binary for smash runtime
 - `crates/relay-core/`: contracts, validator, shared envelope/security primitives
 - `crates/hook-runtime/`: smash runtime and adapter execution engine
@@ -41,16 +37,21 @@ description: >
 
 1. Make the smallest change in the owning module.
 2. Update contract/runtime docs when behavior changes.
-3. Run:
-- `cargo fmt --all`
-- `cargo clippy --workspace --all-targets -- -D warnings`
-- `cargo test --workspace`
+3. Validate:
+
+```bash
+cargo fmt --all
+cargo clippy --workspace --all-targets -- -D warnings
+cargo test --workspace
+```
+
+If clippy fails on contract changes, verify envelope schema compatibility in `crates/relay-core/`. If tests fail, check that adapter driver enums match the contract schema before re-running.
 
 ## Key Docs
 
-- `README.md`
-- `docs/CHANGELOG.md`
-- `docs/spec.md`
-- `tools/hook/README.md`
-- `crates/relay-core/README.md`
-- `crates/hook-runtime/README.md`
+- `README.md` — project overview, CLI quick reference, coding standards
+- `docs/CHANGELOG.md` — release history and breaking changes
+- `docs/spec.md` — contract schema definitions and profile semantics
+- `tools/hook/README.md` — CLI subcommands and flags
+- `crates/relay-core/README.md` — shared contracts, validation, envelope models
+- `crates/hook-runtime/README.md` — smash runtime, adapter execution engine
diff --git a/apps/kafka-openclaw-hook/SKILL.md b/apps/kafka-openclaw-hook/SKILL.md
@@ -1,16 +1,13 @@
 ---
 name: kafka-openclaw-hook
-description: >
-  Maintain the kafka-openclaw-hook compatibility binary and its integration with
-  hook-runtime smash execution. Use when changing startup wiring, runtime env
-  expectations, deployment compatibility, or smash adapter/plugin behavior.
+description: "Maintain the kafka-openclaw-hook compatibility binary, update startup configuration, modify smash adapter bindings, and troubleshoot deployment compatibility with hook-runtime smash execution. Use when changing startup wiring, runtime env expectations, deployment compatibility, smash adapter/plugin behavior, or debugging runtime integration issues."
 ---
 
 # kafka-openclaw-hook Skill
 
 ## Scope
 
-- `apps/kafka-openclaw-hook/src/main.rs`: compatibility entrypoint
+- `apps/kafka-openclaw-hook/src/main.rs`: compatibility entrypoint — calls `hook_runtime::smash::run_from_env()`
 - `crates/hook-runtime/src/smash/*`: smash runtime behavior
 - `crates/hook-runtime/src/adapters/egress/*`: egress adapter drivers
 
@@ -26,14 +23,19 @@ description: >
 1. Edit only the owning runtime module.
 2. Keep adapter/plugin behavior explicit and test-backed.
 3. Update docs if env keys or driver semantics change.
-4. Run:
-- `cargo fmt --all`
-- `cargo clippy --workspace --all-targets -- -D warnings`
-- `cargo test -p hook-runtime`
-- `cargo test -p kafka-openclaw-hook`
+4. Validate:
+
+```bash
+cargo fmt --all
+cargo clippy --workspace --all-targets -- -D warnings
+cargo test -p hook-runtime
+cargo test -p kafka-openclaw-hook
+```
+
+If clippy fails, fix warnings before proceeding. If tests fail, check DLQ behavior and at-least-once delivery semantics before re-running — a failing delivery test often means a required destination is misconfigured in the contract.
 
 ## References
 
-- `apps/kafka-openclaw-hook/README.md`
-- `crates/hook-runtime/README.md`
-- `apps/default-openclaw/contract.toml`
+- `apps/kafka-openclaw-hook/README.md` — binary overview and env expectations
+- `crates/hook-runtime/README.md` — smash runtime and adapter engine
+- `apps/default-openclaw/contract.toml` — canonical contract example
diff --git a/crates/relay-core/SKILL.md b/crates/relay-core/SKILL.md
@@ -1,10 +1,6 @@
 ---
 name: relay-core
-description: >
-  Maintain shared relay-core contracts, validation, envelope models, and
-  security primitives used by serve, relay, smash, and hook-runtime.
-  Use when changing contract schema, active-profile validation, model
-  compatibility, or signature/sanitization/timestamp logic.
+description: "Maintain shared relay-core contracts, validation, envelope models, and security primitives (signatures, sanitization, timestamps) used across serve, relay, smash, and hook-runtime. Use when changing contract schema, adding a driver enum variant, modifying active-profile validation, updating shared types or cross-service contracts, or adjusting signature/sanitization/timestamp logic."
 ---
 
 # relay-core Skill
@@ -33,13 +29,18 @@ description: >
 1. Edit only the module owning the behavior.
 2. Add or adjust focused unit tests.
 3. Update docs/spec/changelog for contract changes.
-4. Run:
-- `cargo fmt --all`
-- `cargo clippy --workspace --all-targets -- -D warnings`
-- `cargo test -p relay-core`
+4. Validate:
+
+```bash
+cargo fmt --all
+cargo clippy --workspace --all-targets -- -D warnings
+cargo test -p relay-core
+```
+
+After contract schema changes, verify serialized envelope compatibility by running the full test suite — `cargo test -p relay-core` includes deserialization round-trip tests. If tests fail on envelope changes, check `src/model.rs` for serde attribute compatibility before re-running.
 
 ## References
 
-- `crates/relay-core/README.md`
-- `docs/spec.md`
-- `apps/default-openclaw/contract.toml`
+- `crates/relay-core/README.md` — crate overview, public API, module responsibilities
+- `docs/spec.md` — contract schema definitions, driver semantics, validation rules
+- `apps/default-openclaw/contract.toml` — canonical contract example for testing changes
diff --git a/skills/contract-authoring/SKILL.md b/skills/contract-authoring/SKILL.md
@@ -1,24 +1,18 @@
 ---
 name: contract-authoring
-description: >
-  Write, validate, and debug hook contract.toml files. Covers the full schema
-  (app, policies, serve, smash, profiles, transports), all supported driver
-  config keys, validation rules, plugin system, and common error codes. Use
-  when creating a new app contract, extending an existing one, or diagnosing
-  contract validation failures.
+description: "Write, validate, and debug hook contract.toml files covering the full schema (app, policies, serve, smash, profiles, transports), all supported driver config keys, validation rules, plugin system, and error codes. Use when creating a new app contract, extending an existing one, diagnosing validation failures, configuring hook routing, or troubleshooting toml config errors."
 ---
 
 # Contract Authoring
 
-## What a Contract Is
+`contract.toml` is the runtime configuration for a hook app. It declares which ingress adapters receive events (`serve`), which egress adapters deliver events (`smash`), how events route between them (`routes`), and which combination is active (`profiles`). The validator uses `deny_unknown_fields` — any typo in a key is a hard error.
 
-`contract.toml` is the runtime configuration for a hook app. It declares:
-- Which ingress adapters receive events (`serve`)
-- Which egress adapters deliver events (`smash`)
-- How events are routed between them (`routes`)
-- Which combination of adapters and routes is active (`profiles`)
+## Validate-Fix Workflow
 
-The validator uses `deny_unknown_fields` throughout — any typo in a key is a hard error.
+1. Write or edit `contract.toml`
+2. Run `hook debug capabilities` to validate
+3. If an error code appears, consult the error table below → fix the issue → re-validate
+4. Only deploy when validation passes clean
 
 ---
 

diff --git a/skills/kafka-add-broker/SKILL.md b/skills/kafka-add-broker/SKILL.md
@@ -1,11 +1,6 @@
 ---
 name: kafka-add-broker
-description: >
-  Add additional Kafka broker nodes to an existing KRaft cluster (typically
-  bootstrapped via the kafka-kraft-firecracker skill), or configure hook to
-  connect to an external Kafka broker or cluster. Use when scaling out brokers,
-  adding redundancy, or pointing hook serve/relay/smash at an externally managed
-  Kafka.
+description: "Add Kafka broker nodes to an existing KRaft cluster (typically bootstrapped via kafka-kraft-firecracker) or configure hook to connect to an external Kafka broker or cluster. Use when scaling out brokers, adding redundancy, connecting to external Kafka (AWS MSK, Confluent, self-hosted), or pointing hook serve/relay/smash at a new message broker."
 ---
 
 # Kafka Add Broker