Skill Improvement Proposal

Problem Description

A developer has a webhook-handler skill that needs improvement. Their team has a policy that any changes to shared skills must be proposed and reviewed by the tech lead before being applied. The developer needs to produce a formal proposal document presenting all recommended improvements so the tech lead can review and approve them before any edits are made to the actual skill file.

Given the review output and current SKILL.md below, create a comprehensive proposal document. The tech lead is technical but wants to understand why each change matters, not just what it is. Present the full set of recommendations with enough context to make an informed approval decision.

Importantly: produce only the proposal document. Do not apply any changes to the SKILL.md itself — that will happen only after approval.

Output Specification

Produce proposal.md — a structured document presenting all recommended skill improvements for review. The tech lead should be able to approve or reject each individual recommendation.

Input Files

The following files are provided as inputs. Extract them before beginning.

=============== FILE: review_output.txt =============== === Skill Review: webhook-handler === Overall Score: 61%

ERRORS (must fix): [ERROR] Description missing "Use when" trigger clause — reduces routing to 0% effectiveness

Dimension Scores: Completeness: 1/3 (33%) - Missing trigger clause Actionability: 2/3 (66%) - Some examples but they show output not commands Conciseness: 2/3 (66%) - Explains HMAC authentication in detail (agent already knows this) Robustness: 2/3 (66%) - No retry or idempotency patterns

Judge Suggestions:

• Critical: Add "Use when receiving webhook events from external services, validating signatures, or processing event payloads" to description
• Replace the HMAC explanation paragraph with a code example using the actual verify-sig command
• Add an idempotency example showing how to use the event ID to prevent duplicate processing =============== END FILE ===============

=============== FILE: webhook_handler/SKILL.md ===============

name: webhook-handler description: | Handles incoming webhook events from external services. Validates signatures, parses payloads, and routes events to appropriate handlers.

Webhook Handler

Process incoming webhooks from external services using our internal webhook framework.

Signature Validation

Webhooks use HMAC-SHA256 for signature validation. HMAC (Hash-based Message Authentication Code) is a cryptographic technique that uses a shared secret key and a hash function to verify message authenticity. The sender computes an HMAC over the request body using the shared secret, and the receiver recomputes it to verify the signature matches. This prevents tampering and confirms the request came from the expected sender.

To validate:

import hmac
import hashlib

def validate_webhook(body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

Payload Processing

Parse the incoming event:

webhook-cli process --event-type push --payload @payload.json

Event Routing

Events are routed based on the event_type field in the payload. Supported types: push, pull_request, release, deployment. =============== END FILE ===============