From ea8782d446965f41cbba6c4ce038b0fb9ebc4754 Mon Sep 17 00:00:00 2001 From: rohan-tessl Date: Mon, 6 Apr 2026 13:54:38 +0530 Subject: [PATCH] feat: improve skill scores for hook workspace MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Hey @heyAyushh 👋 I ran your skills through `tessl skill review` at work and found some targeted improvements. Here's the full before/after: | Skill | Before | After | Change | |-------|--------|-------|--------| | hook-serve | 73% | 89% | +16% | | kafka-openclaw-hook | 79% | 94% | +15% | | relay-core | 83% | 100% | +17% | | contract-authoring | 80% | 97% | +17% | | kafka-add-broker | 90% | 90% | +0% | This PR is intentionally scoped to 5 skills to keep it reviewable — more skills can be improved in follow-ups or via automated review on future PRs.
Changes summary - Converted all frontmatter descriptions from YAML chevron (>) to quoted strings for consistent parsing - Expanded descriptions with concrete action verbs — e.g. "configure Kafka topics, validate hook contracts, register ingress/egress adapters" instead of abstract "build, maintain, and operate" - Added natural trigger terms users would actually say — "webhook source", "toml config errors", "cross-service contracts", "AWS MSK", "Confluent" - Added explicit validation feedback loops to workflows — e.g. "If clippy fails on contract changes, verify envelope schema compatibility in relay-core" - Annotated Key Docs and References with brief descriptions of what each file contains and when to consult it - Added validate-fix workflow to contract-authoring skill with explicit error recovery steps - Trimmed redundant "What a Contract Is" section in contract-authoring — consolidated into a concise opening paragraph
Honest disclosure — I work at @tesslio where we build tooling around skills like these. Not a pitch - just saw room for improvement and wanted to contribute. Want to self-improve your skills? Just point your agent (Claude Code, Codex, etc.) at this Tessl guide (https://docs.tessl.io/evaluate/optimize-a-skill-using-best-practices) and ask it to optimize your skill. Ping me - @rohan-tessl (https://github.com/rohan-tessl) - if you hit any snags. Thanks in advance 🙏 --- SKILL.md | 37 +++++++++++++++--------------- apps/kafka-openclaw-hook/SKILL.md | 28 +++++++++++----------- crates/relay-core/SKILL.md | 25 ++++++++++---------- skills/contract-authoring/SKILL.md | 20 ++++++---------- skills/kafka-add-broker/SKILL.md | 7 +----- 5 files changed, 55 insertions(+), 62 deletions(-) diff --git a/SKILL.md b/SKILL.md index 9412b6c..a6844c9 100644 --- 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 index 01de26e..eb16aa3 100644 --- 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 index 51f278a..0a18345 100644 --- 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 index f07ce73..ed0d286 100644 --- 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 index 1d46452..748b806 100644 --- 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