Merge pull request #35 from hookdeck/feat/hookdeck-skills-restructure

feat: Restructure Hookdeck skills and add dynamic test discovery

Author: leggetter

.github/workflows/test-examples.yml

@@ -28,7 +28,7 @@ jobs:
             echo "run_all=true" >> $GITHUB_OUTPUT
             echo "has_changes=true" >> $GITHUB_OUTPUT
             # Return all providers as JSON array
-            PROVIDERS=$(ls -d skills/*-webhooks skills/hookdeck-event-gateway 2>/dev/null | xargs -n1 basename | jq -R -s -c 'split("\n") | map(select(length > 0))')
+            PROVIDERS=$(ls -d skills/*-webhooks 2>/dev/null | xargs -n1 basename | jq -R -s -c 'split("\n") | map(select(length > 0))')
             echo "providers=$PROVIDERS" >> $GITHUB_OUTPUT
             exit 0
           fi
@@ -45,7 +45,7 @@ jobs:
             grep -E '^skills/[^/]+/' | \
             sed 's|skills/\([^/]*\)/.*|\1|' | \
             sort -u | \
-            grep -E '(-webhooks|hookdeck-event-gateway)$' || true)
+            grep -E '(-webhooks)$' || true)
           
           if [ -z "$CHANGED_PROVIDERS" ]; then
             echo "No skill changes detected"

AGENTS.md

@@ -15,7 +15,7 @@ webhook-skills/
 ├── TESTING.md                   # Testing documentation
 ├── LICENSE
 ├── scripts/
-│   ├── test-all-examples.sh     # Run all example tests
+│   ├── test-examples.sh          # Run example tests (all or specific skills)
 │   └── test-agent-scenario.sh   # Run agent integration tests
 ├── .github/
 │   └── workflows/
@@ -701,10 +701,14 @@ See [TESTING.md](TESTING.md) for comprehensive testing documentation.
 
 **Run example tests:**
 ```bash
-# All examples
-./scripts/test-all-examples.sh
+# All skills with examples
+./scripts/test-examples.sh
 
-# Single example
+# Specific skill(s)
+./scripts/test-examples.sh stripe-webhooks
+./scripts/test-examples.sh stripe-webhooks github-webhooks
+
+# Single example directly
 cd skills/{provider}-webhooks/examples/express && npm test
 ```
 
@@ -788,7 +792,7 @@ cd skills/{provider}-webhooks/examples/nextjs && npm test
 cd skills/{provider}-webhooks/examples/fastapi && pytest test_webhook.py -v
 
 # Run all example tests
-./scripts/test-all-examples.sh
+./scripts/test-examples.sh
 ```
 
 Ensure test scripts exit properly (e.g. `"test": "vitest run"` not `"vitest"`).

README.md

@@ -58,11 +58,13 @@ Framework-agnostic best practices for webhook handling, applicable across any we
 
 ### Webhook Infrastructure Skills
 
-Skills for setting up reliable webhook infrastructure with routing, replay, and monitoring.
+Skills for webhook infrastructure products — routing, queuing, delivery, and observability.
 
 | Skill | What It Does |
 |-------|--------------|
-| [`hookdeck-event-gateway`](skills/hookdeck-event-gateway/) | Set up Hookdeck Event Gateway for webhook routing, retry, replay, and monitoring |
+| [`hookdeck-event-gateway`](skills/hookdeck-event-gateway/) | Webhook infrastructure that replaces your queue — guaranteed delivery, retries, rate limiting, replay, observability |
+| [`hookdeck-event-gateway-webhooks`](skills/hookdeck-event-gateway-webhooks/) | Verify `x-hookdeck-signature` and handle webhooks forwarded by the Hookdeck Event Gateway |
+| [`outpost`](skills/outpost/) | Send webhooks and events to user-preferred destinations (HTTP, SQS, RabbitMQ, Pub/Sub, EventBridge, Kafka) |
 
 ## Quick Start
 

TESTING.md

@@ -38,7 +38,12 @@ npm test
 Use the test runner script to run all examples:
 
 ```bash
-./scripts/test-all-examples.sh
+# All skills with examples
+./scripts/test-examples.sh
+
+# Specific skill(s)
+./scripts/test-examples.sh stripe-webhooks
+./scripts/test-examples.sh stripe-webhooks github-webhooks
 ```
 
 ### CI Pipeline
@@ -151,17 +156,17 @@ Validate that AI agents (Cursor, Claude, Copilot) can successfully use these ski
 
 ---
 
-#### Scenario 4: Hookdeck Event Gateway Setup
+#### Scenario 4: Hookdeck Event Gateway Webhooks Setup
 
 **Setup:**
 1. Existing Express app with webhook endpoint
-2. Install the skill: `npx skills add hookdeck/webhook-skills --skill hookdeck-event-gateway`
+2. Install the skill: `npx skills add hookdeck/webhook-skills --skill hookdeck-event-gateway-webhooks`
 
 **Prompt:**
 > "I'm receiving webhooks through Hookdeck. Add signature verification for Hookdeck's signature."
 
 **Expected Behaviors:**
-- [ ] Agent reads `hookdeck-event-gateway/SKILL.md`
+- [ ] Agent reads `hookdeck-event-gateway-webhooks/SKILL.md`
 - [ ] Agent references `references/verification.md`
 - [ ] Generated code verifies `x-hookdeck-signature` header
 - [ ] Generated code uses base64-encoded HMAC SHA-256

providers.yaml

@@ -301,7 +301,6 @@ providers:
       providers and forwards them to your app with an x-hookdeck-signature header.
       Uses HMAC-SHA256 with base64 encoding. Signed content format is the raw request body.
     testScenario:
-      skillName: hookdeck-event-gateway
       events:
         - webhooks via Event Gateway
       prompt: >

scripts/test-all-examples.sh scripts/test-examples.shscripts/test-all-examples.sh renamed to scripts/test-examples.sh

@@ -1,7 +1,14 @@
 #!/bin/bash
 
-# Test All Webhook Skills Examples
-# This script runs tests for all example applications across providers and frameworks.
+# Test Webhook Skills Examples
+# Runs tests for example applications across skills and frameworks.
+#
+# Usage:
+#   ./scripts/test-examples.sh                  # Test all skills that have examples
+#   ./scripts/test-examples.sh stripe-webhooks   # Test one specific skill
+#   ./scripts/test-examples.sh stripe-webhooks github-webhooks  # Test multiple skills
+#
+# Discovery: Finds skills by looking for skills/*/examples/ directories.
 
 set -e
 
@@ -13,6 +20,7 @@ SKILLS_DIR="$ROOT_DIR/skills"
 RED='\033[0;31m'
 GREEN='\033[0;32m'
 YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
 NC='\033[0m' # No Color
 
 # Track results
@@ -21,16 +29,107 @@ FAILED=0
 SKIPPED=0
 FAILED_TESTS=()
 
-# Providers to test
-PROVIDERS=("stripe-webhooks" "shopify-webhooks" "github-webhooks" "hookdeck-event-gateway" "deepgram-webhooks")
-
 # Frameworks to test
 FRAMEWORKS=("express" "nextjs" "fastapi")
 
+usage() {
+    echo "Usage: $0 [skill-name ...]"
+    echo ""
+    echo "Test webhook skill example applications."
+    echo ""
+    echo "  No arguments    Discover and test all skills that have examples/"
+    echo "  skill-name ...  Test only the specified skill(s)"
+    echo ""
+    echo "Examples:"
+    echo "  $0                                          # Test all"
+    echo "  $0 stripe-webhooks                          # Test one"
+    echo "  $0 stripe-webhooks github-webhooks           # Test multiple"
+    echo ""
+    echo "Options:"
+    echo "  -h, --help    Show this help message"
+    echo ""
+
+    # Show available skills with examples
+    echo "Skills with examples:"
+    for dir in "$SKILLS_DIR"/*/examples; do
+        if [ -d "$dir" ]; then
+            local skill_name
+            skill_name=$(basename "$(dirname "$dir")")
+            # List which frameworks are available
+            local frameworks=()
+            for fw in "${FRAMEWORKS[@]}"; do
+                if [ -d "$dir/$fw" ]; then
+                    frameworks+=("$fw")
+                fi
+            done
+            echo "  $skill_name (${frameworks[*]})"
+        fi
+    done
+    exit 0
+}
+
+# Parse arguments
+REQUESTED_SKILLS=()
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        -h|--help)
+            usage
+            ;;
+        -*)
+            echo -e "${RED}Unknown option: $1${NC}"
+            echo ""
+            usage
+            ;;
+        *)
+            REQUESTED_SKILLS+=("$1")
+            shift
+            ;;
+    esac
+done
+
+# Discover skills with examples
+discover_skills() {
+    local skills=()
+    for dir in "$SKILLS_DIR"/*/examples; do
+        if [ -d "$dir" ]; then
+            skills+=("$(basename "$(dirname "$dir")")")
+        fi
+    done
+    # Sort alphabetically
+    IFS=$'\n' skills=($(sort <<<"${skills[*]}")); unset IFS
+    echo "${skills[@]}"
+}
+
+# Determine which skills to test
+if [ ${#REQUESTED_SKILLS[@]} -gt 0 ]; then
+    # Validate requested skills exist and have examples
+    SKILLS=()
+    for skill in "${REQUESTED_SKILLS[@]}"; do
+        if [ ! -d "$SKILLS_DIR/$skill" ]; then
+            echo -e "${RED}Error: Skill '$skill' not found in $SKILLS_DIR/${NC}"
+            exit 1
+        fi
+        if [ ! -d "$SKILLS_DIR/$skill/examples" ]; then
+            echo -e "${RED}Error: Skill '$skill' has no examples/ directory${NC}"
+            exit 1
+        fi
+        SKILLS+=("$skill")
+    done
+else
+    # Discover all skills with examples
+    read -ra SKILLS <<< "$(discover_skills)"
+fi
+
+if [ ${#SKILLS[@]} -eq 0 ]; then
+    echo -e "${YELLOW}No skills with examples found.${NC}"
+    exit 0
+fi
+
 echo "========================================"
 echo "  Webhook Skills Example Tests"
 echo "========================================"
 echo ""
+echo -e "Skills to test: ${BLUE}${#SKILLS[@]}${NC} (${SKILLS[*]})"
 
 # Function to run Node.js tests (Express/Next.js)
 run_node_tests() {
@@ -165,22 +264,17 @@ run_python_tests() {
     deactivate
 }
 
-# Run tests for each provider
-for provider in "${PROVIDERS[@]}"; do
-    provider_dir="$SKILLS_DIR/$provider"
-    
-    if [ ! -d "$provider_dir" ]; then
-        echo "Provider $provider not found, skipping..."
-        continue
-    fi
+# Run tests for each skill
+for skill in "${SKILLS[@]}"; do
+    skill_dir="$SKILLS_DIR/$skill"
 
     echo ""
-    echo "Testing $provider"
+    echo "Testing $skill"
     echo "----------------------------------------"
 
     for framework in "${FRAMEWORKS[@]}"; do
-        example_dir="$provider_dir/examples/$framework"
-        test_name="$provider/$framework"
+        example_dir="$skill_dir/examples/$framework"
+        test_name="$skill/$framework"
 
         if [ ! -d "$example_dir" ]; then
             echo -n "  Testing $test_name... "

skills/chargebee-webhooks/SKILL.md

@@ -240,4 +240,4 @@ We recommend installing the [webhook-handler-patterns](https://github.com/hookde
 - [openai-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/openai-webhooks) - OpenAI webhook handling
 - [paddle-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/paddle-webhooks) - Paddle billing webhook handling
 - [webhook-handler-patterns](https://github.com/hookdeck/webhook-skills/tree/main/skills/webhook-handler-patterns) - Handler sequence, idempotency, error handling, retry logic
-- [hookdeck-event-gateway](https://github.com/hookdeck/webhook-skills/tree/main/skills/hookdeck-event-gateway) - Production webhook infrastructure (routing, replay, monitoring)
+- [hookdeck-event-gateway](https://github.com/hookdeck/webhook-skills/tree/main/skills/hookdeck-event-gateway) - Webhook infrastructure that replaces your queue — guaranteed delivery, automatic retries, replay, rate limiting, and observability for your webhook handlers

skills/clerk-webhooks/SKILL.md

@@ -230,4 +230,4 @@ We recommend installing the [webhook-handler-patterns](https://github.com/hookde
 - [openai-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/openai-webhooks) - OpenAI webhook handling
 - [paddle-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/paddle-webhooks) - Paddle billing webhook handling
 - [webhook-handler-patterns](https://github.com/hookdeck/webhook-skills/tree/main/skills/webhook-handler-patterns) - Handler sequence, idempotency, error handling, retry logic
-- [hookdeck-event-gateway](https://github.com/hookdeck/webhook-skills/tree/main/skills/hookdeck-event-gateway) - Production webhook infrastructure (routing, replay, monitoring)
+- [hookdeck-event-gateway](https://github.com/hookdeck/webhook-skills/tree/main/skills/hookdeck-event-gateway) - Webhook infrastructure that replaces your queue — guaranteed delivery, automatic retries, replay, rate limiting, and observability for your webhook handlers

skills/cursor-webhooks/SKILL.md

@@ -192,4 +192,4 @@ For production-ready webhook handling, also use the webhook-handler-patterns ski
 - [shopify-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/shopify-webhooks) - Shopify webhook handling
 - [openai-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/openai-webhooks) - OpenAI webhook handling
 - [webhook-handler-patterns](https://github.com/hookdeck/webhook-skills/tree/main/skills/webhook-handler-patterns) - Idempotency, error handling, retry logic
-- [hookdeck-event-gateway](https://github.com/hookdeck/webhook-skills/tree/main/skills/hookdeck-event-gateway) - Production webhook infrastructure
+- [hookdeck-event-gateway](https://github.com/hookdeck/webhook-skills/tree/main/skills/hookdeck-event-gateway) - Webhook infrastructure that replaces your queue — guaranteed delivery, automatic retries, replay, rate limiting, and observability for your webhook handlers

skills/deepgram-webhooks/SKILL.md

@@ -175,4 +175,4 @@ For production handlers, install the patterns skill alongside this one. Key refe
 - [shopify-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/shopify-webhooks) - Shopify store webhooks
 - [github-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/github-webhooks) - GitHub repository webhooks
 - [webhook-handler-patterns](https://github.com/hookdeck/webhook-skills/tree/main/skills/webhook-handler-patterns) - Idempotency, error handling, retry logic
-- [hookdeck-event-gateway](https://github.com/hookdeck/webhook-skills/tree/main/skills/hookdeck-event-gateway) - Production webhook infrastructure (reliability, monitoring, replay)
+- [hookdeck-event-gateway](https://github.com/hookdeck/webhook-skills/tree/main/skills/hookdeck-event-gateway) - Webhook infrastructure that replaces your queue — guaranteed delivery, automatic retries, replay, rate limiting, and observability for your webhook handlers