@harness-engineering/cli 1.23.2 → 1.24.1

package/dist/agents/skills/gemini-cli/api-webhook-design/SKILL.md

@@ -0,0 +1,165 @@
+# API Webhook Design
+
+> WEBHOOKS ARE A PUSH-BASED CONTRACT — REGISTRATION, PAYLOAD SCHEMA, DELIVERY GUARANTEES, AND RETRY POLICIES ARE ALL CONSUMER-FACING COMMITMENTS THAT DETERMINE WHETHER INTEGRATIONS REMAIN RELIABLE UNDER PARTIAL FAILURES, AND DESIGNING THESE PROPERTIES EXPLICITLY UPFRONT PREVENTS AN AD-HOC SYSTEM THAT FAILS SILENTLY AT THE WORST POSSIBLE MOMENT.
+
+## When to Use
+
+- Designing the webhook system for a new platform API that needs to notify external consumers of events
+- Auditing an existing webhook implementation for missing retry logic, payload versioning, or delivery guarantees
+- Deciding between at-least-once and exactly-once delivery and documenting the implications for consumers
+- Implementing fan-out from a single internal event to multiple registered subscriber endpoints
+- Writing the webhook reference section of a developer portal or API style guide
+- Responding to a consumer report of missed webhook deliveries or ordering anomalies
+- Adding webhook support to an existing REST API without disrupting current consumers
+
+## Instructions
+
+### Key Concepts
+
+1. **Webhook registration and lifecycle** — Consumers register a publicly reachable HTTPS endpoint (the "webhook URL") with the provider, along with an event type filter (e.g., `payment.succeeded`, `order.created`). The registration should store: the endpoint URL, the event types subscribed, a shared signing secret, and metadata for auditing (created by, created at). Provide a management API or dashboard UI to create, list, test, pause, and delete registrations. GitHub's webhook management API (`POST /repos/{owner}/{repo}/hooks`) is the canonical reference: consumers can subscribe per-repository, per-organization, or at the App level.
+
+2. **Payload design and versioning** — Every webhook payload must include: an `id` (unique delivery ID for deduplication), an `event` field (event type string), a `created` timestamp (ISO 8601), an `api_version` field (the schema version that generated the payload), and a `data` object (the event subject). Never omit the `api_version` — consumers need it to route the payload to the correct handler when you introduce breaking schema changes. Stripe's payload envelope is the industry standard: `{ "id": "evt_xxx", "object": "event", "api_version": "2024-04-10", "created": 1712800000, "type": "payment_intent.succeeded", "data": { "object": { ... } } }`.
+
+3. **At-least-once delivery and consumer idempotency** — Webhook systems guarantee at-least-once delivery by design: a delivery is considered successful only when the consumer returns a 2xx response within the timeout window (typically 5–30 seconds). Any non-2xx response or timeout triggers a retry. Consequently, consumers will occasionally receive the same event more than once. Document this guarantee explicitly, and instruct consumers to use the delivery `id` field as an idempotency key to deduplicate retried deliveries. Never promise exactly-once delivery unless you have a distributed transaction mechanism backing it.
+
+4. **Retry policy with exponential backoff** — Failed deliveries (non-2xx or timeout) must be retried with exponential backoff: attempt 1 at T+1 min, attempt 2 at T+5 min, attempt 3 at T+30 min, attempt 4 at T+2 h, attempt 5 at T+5 h. After the maximum retry count (commonly 5–10 attempts over 24–72 hours), mark the delivery as failed and optionally surface an alert to the webhook owner. GitHub retries for 3 days with exponential backoff. Stripe retries for 3 days across up to 17 attempts with escalating intervals.
+
+5. **Ordering guarantees and fan-out** — Webhooks are not guaranteed to arrive in the order events occurred. Network and retry interactions can invert order. Tell consumers to use the `created` timestamp to establish event ordering rather than arrival order. For fan-out (one internal event dispatched to N registered endpoints), use an async queue per subscriber so a slow or failing subscriber cannot block delivery to other subscribers. Each subscriber's queue is independent; backpressure on one does not affect others.
+
+6. **Endpoint health and circuit breaking** — Track consecutive delivery failures per endpoint. After a configurable threshold (e.g., 5 consecutive failures or >50% failure rate over 1 hour), automatically pause the endpoint and notify the webhook owner. A paused endpoint stops receiving new deliveries; the owner must investigate and re-enable it. Sending to a consistently failing endpoint wastes resources and can cause queue buildup. GitHub auto-disables webhooks that fail for 7 consecutive days.
+
+### Worked Example
+
+**GitHub Webhooks — repository push event**
+
+Register a webhook on a repository:
+
+```http
+POST /repos/acme/payments/hooks
+Authorization: Bearer ghp_xxx
+Content-Type: application/json
+
+{
+  "name": "web",
+  "active": true,
+  "events": ["push", "pull_request"],
+  "config": {
+    "url": "https://ci.acme.com/hooks/github",
+    "content_type": "json",
+    "secret": "s3cr3t_abc123",
+    "insecure_ssl": "0"
+  }
+}
+
+→ HTTP/1.1 201 Created
+{
+  "id": 12345678,
+  "type": "Repository",
+  "active": true,
+  "events": ["push", "pull_request"],
+  "config": { "url": "https://ci.acme.com/hooks/github", "content_type": "json" },
+  "created_at": "2024-04-10T12:00:00Z"
+}
+```
+
+Incoming delivery payload:
+
+```json
+{
+  "ref": "refs/heads/main",
+  "before": "abc123",
+  "after": "def456",
+  "repository": { "id": 99887766, "name": "payments", "full_name": "acme/payments" },
+  "pusher": { "name": "alice", "email": "alice@acme.com" },
+  "commits": [{ "id": "def456", "message": "fix: handle nil pointer in checkout" }]
+}
+```
+
+Delivery headers:
+
+```http
+X-GitHub-Event: push
+X-GitHub-Delivery: 72d3162e-cc78-11e3-81ab-4c9367dc0958
+X-Hub-Signature-256: sha256=abc123...
+```
+
+Consumer responds with `200 OK` and an empty body — GitHub marks the delivery as successful. The `X-GitHub-Delivery` UUID is the idempotency key consumers use to deduplicate retries.
+
+**Fan-out architecture:**
+
+```
+Internal Event Bus
+      │
+      ▼
+  Dispatcher Service
+      │
+  ┌───┴───────────────────────┐
+  ▼                           ▼
+Queue: endpoint-A         Queue: endpoint-B
+  │                           │
+  ▼                           ▼
+Worker → POST /hook/A     Worker → POST /hook/B
+```
+
+Each subscriber queue is independent. A 30-second timeout on endpoint-B does not delay endpoint-A's delivery.
+
+### Anti-Patterns
+
+1. **Synchronous delivery in the request path.** Firing the webhook HTTP call synchronously during the transaction that generated the event couples event delivery latency to the consumer's endpoint response time. A slow consumer endpoint (or network partition) can cause your transaction to time out or roll back. Always dispatch webhook deliveries asynchronously via a queue after the originating transaction commits.
+
+2. **No delivery `id` in the payload.** Without a unique delivery identifier, consumers cannot implement idempotency. Every retry looks identical to the first delivery. The consumer has no reliable way to detect or handle duplicates. Include a UUID delivery ID in every payload regardless of whether the consumer currently uses it.
+
+3. **Fixed retry interval (no backoff).** Retrying at a fixed 1-minute interval after a consumer endpoint goes down hammers the endpoint with traffic exactly when it is least able to respond — during an outage or deployment. Exponential backoff with jitter reduces thundering-herd behavior and gives the consumer time to recover before the next attempt.
+
+4. **Delivering to HTTP endpoints.** Allowing webhook registrations to plain HTTP (non-TLS) URLs exposes the payload — which may contain sensitive business data — to network interception. Require HTTPS for all webhook URLs and reject registrations that specify HTTP. Surface a clear validation error: `"config.url must use HTTPS"`.
+
+5. **No test delivery mechanism.** Consumers integrating a webhook system need a way to trigger a test delivery without generating a real event. Without it, they must create real objects in production to test their handler. Provide a `POST /hooks/{id}/test` endpoint that sends a sample payload and returns the delivery result.
+
+## Details
+
+### Payload Envelope Standardization
+
+A consistent payload envelope across all event types reduces the cognitive load on consumers who handle multiple event types. The envelope fields (`id`, `event`, `created`, `api_version`, `data`) are stable; only `data` varies by event type. This pattern enables consumers to write generic middleware that extracts the envelope before routing to event-specific handlers.
+
+Consider publishing a JSON Schema or OpenAPI schema for each event type's `data` payload. Stripe publishes event object schemas in their OpenAPI spec; consumers can generate typed client models from them. When you evolve a payload (rename a field, add a required property), bump `api_version` and publish a changelog.
+
+### Real-World Case Study: Stripe Webhook Reliability
+
+Stripe processes billions of webhook deliveries per month. Their published reliability figures show that >99.9% of events are delivered within 30 seconds on the first attempt under normal conditions. The remaining <0.1% are retried across up to 17 attempts over 72 hours. Stripe's key design decisions that achieve this:
+
+1. Deliveries are enqueued after the originating database write commits — no synchronous delivery.
+2. Per-endpoint queues prevent a single slow consumer from causing head-of-line blocking.
+3. The `api_version` field in every payload is the API version at the time the event was created, not the current API version — consumers always receive the schema they integrated against.
+4. Stripe's webhook dashboard shows delivery attempt history, response codes, response bodies, and the ability to replay any delivery — dramatically reducing consumer debugging time.
+
+Outcome: Stripe's webhook retry architecture became the reference design for Twilio, GitHub, and most SaaS platforms that launched webhook support after 2015.
+
+## Source
+
+- [Stripe Webhooks Documentation](https://stripe.com/docs/webhooks)
+- [GitHub Webhooks Documentation](https://docs.github.com/en/webhooks)
+- [webhooks.fyi — Webhook Standards Reference](https://webhooks.fyi)
+- [Google AIP-151 — Long-running Operations](https://aip.dev/151)
+- [Standard Webhooks Specification](https://www.standardwebhooks.com)
+
+## Process
+
+1. Define the event catalog (event type strings, payload schemas, `api_version`) before implementing delivery infrastructure — consumers build against the schema.
+2. Implement delivery as an async queue-based system; commit the event to the queue after the originating transaction commits, never inline.
+3. Set per-subscriber independent queues for fan-out; configure retry policy with exponential backoff and a maximum attempt count (5–10 attempts over 24–72 hours).
+4. Expose a `POST /hooks/{id}/test` endpoint and a delivery history dashboard so consumers can verify integration without generating real events.
+5. Run `harness validate` to confirm skill files are well-formed and related skills are correctly cross-referenced.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+- **related_skills:** api-webhook-security, events-webhooks-pattern, api-idempotency-keys, api-long-running-operations
+
+## Success Criteria
+
+- Every webhook payload includes a unique delivery `id`, an `event` type string, a `created` timestamp, and an `api_version` field.
+- Deliveries are dispatched asynchronously after the originating transaction commits; no synchronous delivery in the request path.
+- The retry policy uses exponential backoff with a defined maximum attempt count and total retry window.
+- Fan-out to multiple subscribers uses per-subscriber independent queues so one failing subscriber cannot block others.
+- A test delivery mechanism (`POST /hooks/{id}/test`) is available for consumers to verify handler integration without generating real events.

package/dist/agents/skills/gemini-cli/api-webhook-design/skill.yaml

@@ -0,0 +1,41 @@
+name: api-webhook-design
+version: '1.0.0'
+description: Webhook registration, payload design, delivery guarantees (at-least-once), retry policy, ordering guarantees, fan-out patterns
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - api-webhook-security
+  - events-webhooks-pattern
+  - api-idempotency-keys
+  - api-long-running-operations
+stack_signals:
+  - rest
+  - api
+  - http
+  - webhooks
+keywords:
+  - webhooks
+  - webhook-registration
+  - at-least-once
+  - delivery-guarantee
+  - retry-policy
+  - fan-out
+  - event-payload
+metadata:
+  author: community
+  upstream: webhooks.fyi
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/gemini-cli/api-webhook-security/SKILL.md

@@ -0,0 +1,176 @@
+# API Webhook Security
+
+> WEBHOOK SECURITY IS A RECEIVER-SIDE RESPONSIBILITY — SIGNATURE VERIFICATION, TIMESTAMP VALIDATION, AND SECRET ROTATION ARE THE THREE CONTROLS THAT PREVENT SPOOFED DELIVERIES, REPLAY ATTACKS, AND CREDENTIAL EXPOSURE, AND OMITTING ANY ONE OF THEM CREATES AN EXPLOITABLE GAP EVEN IF THE OTHER TWO ARE CORRECTLY IMPLEMENTED.
+
+## When to Use
+
+- Implementing a webhook receiver that needs to validate incoming deliveries from a provider (GitHub, Stripe, Twilio, Slack, etc.)
+- Designing the signature scheme for a webhook system being built for external consumers
+- Auditing an existing webhook handler for missing replay-attack defenses or insecure secret storage
+- Writing the security section of a webhook integration guide or API style guide
+- Rotating a compromised webhook secret without downtime for the receiving endpoint
+- Adding timestamp tolerance enforcement to a handler that currently only checks signatures
+
+## Instructions
+
+### Key Concepts
+
+1. **HMAC-SHA256 signature verification** — The provider computes an HMAC-SHA256 digest of the raw request body using the shared secret as the key, then encodes it as a hex string and sends it in a request header (e.g., `X-Hub-Signature-256: sha256=<hex>` for GitHub, `Stripe-Signature: t=<ts>,v1=<hex>` for Stripe). The receiver recomputes the same HMAC over the raw request body using the same secret and compares digests using a constant-time comparison function. If the digests match, the payload is authentic and unmodified. Always verify over the **raw** body bytes before any JSON parsing — any transformation (whitespace normalization, key reordering) will invalidate the signature.
+
+2. **Timestamp validation and replay attack defense** — An attacker who captures a valid webhook delivery can replay it seconds, hours, or days later. The signature check alone cannot detect this because the replayed payload has a valid signature. The defense is to include a delivery timestamp in the signature computation (as Stripe does: `HMAC(secret, "<timestamp>.<body>")`) and reject deliveries where the timestamp is outside a tolerance window (typically ±5 minutes from now). The receiver must check the timestamp against the current server time. If the timestamp is stale, reject with 400 even if the signature is valid.
+
+3. **Tolerance window configuration** — The tolerance window balances security and operational reliability. A 5-minute window is the industry standard (Stripe's default, GitHub's implicit delivery freshness guarantee). Narrower windows (e.g., 30 seconds) increase security but risk rejecting legitimate deliveries from providers with clock skew or delivery queue lag. Wider windows (e.g., 1 hour) make replay attacks trivial. Configure the tolerance window as an environment variable, not a hardcoded constant, so it can be tightened or widened without a deployment. Default to 300 seconds (5 minutes).
+
+4. **Shared secret management** — Webhook secrets are credentials. Store them in a secrets manager (AWS Secrets Manager, HashiCorp Vault, GCP Secret Manager) or at minimum in environment variables — never in source code or configuration files committed to version control. Each webhook registration should have its own unique secret so that a compromised secret on one endpoint does not affect other registrations. Rotate secrets periodically (at minimum annually) and immediately on suspected compromise.
+
+5. **Secret rotation without downtime** — Rotating a webhook secret requires a brief window where both the old and new secrets are valid. The procedure is: (1) generate a new secret, (2) update the receiver to accept signatures from either the old or new secret (dual-secret verification), (3) update the provider registration to use the new secret, (4) wait for in-flight deliveries signed with the old secret to drain (typically 5–10 minutes), (5) remove the old secret from the receiver. This prevents delivery failures during rotation. Stripe's `Stripe-Signature` header supports multiple signatures (`v1=<old_sig>,v1=<new_sig>`) explicitly to enable this pattern.
+
+6. **TLS requirement and IP allowlisting** — All webhook endpoints must be served over HTTPS/TLS. A non-TLS endpoint exposes the raw payload and allows an on-path attacker to read or modify deliveries before they reach the receiver. Beyond TLS, providers publish the IP ranges from which they send webhook deliveries; receivers can add network-layer IP allowlisting as a defense-in-depth measure. GitHub publishes its hook delivery IP ranges via the `GET /meta` API endpoint; Stripe publishes theirs in their IP allowlisting documentation. IP allowlisting is defense-in-depth only — it does not replace signature verification.
+
+### Worked Example
+
+**GitHub webhook signature verification (Node.js)**
+
+GitHub sends `X-Hub-Signature-256: sha256=<hex>` with every delivery.
+
+```typescript
+import * as crypto from 'crypto';
+import type { Request, Response } from 'express';
+
+const WEBHOOK_SECRET = process.env.GITHUB_WEBHOOK_SECRET!;
+const TOLERANCE_SECONDS = 300; // 5 minutes
+
+export function verifyGitHubWebhook(req: Request, res: Response, next: () => void): void {
+  const signature = req.headers['x-hub-signature-256'] as string;
+  const delivery = req.headers['x-github-delivery'] as string;
+
+  if (!signature || !delivery) {
+    res.status(400).json({ error: 'Missing required webhook headers' });
+    return;
+  }
+
+  // Verify over raw body bytes — must use rawBody middleware upstream
+  const rawBody = (req as any).rawBody as Buffer;
+  const expected =
+    'sha256=' + crypto.createHmac('sha256', WEBHOOK_SECRET).update(rawBody).digest('hex');
+
+  // Constant-time comparison prevents timing attacks
+  const sigBuffer = Buffer.from(signature, 'utf8');
+  const expectedBuffer = Buffer.from(expected, 'utf8');
+
+  if (
+    sigBuffer.length !== expectedBuffer.length ||
+    !crypto.timingSafeEqual(sigBuffer, expectedBuffer)
+  ) {
+    res.status(401).json({ error: 'Invalid signature' });
+    return;
+  }
+
+  next();
+}
+```
+
+**Stripe webhook with timestamp validation**
+
+Stripe's `Stripe-Signature` header format: `t=<unix_timestamp>,v1=<hex_signature>`
+
+```typescript
+import Stripe from 'stripe';
+
+const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
+const ENDPOINT_SECRET = process.env.STRIPE_WEBHOOK_SECRET!;
+
+export function verifyStripeWebhook(req: Request, res: Response, next: () => void): void {
+  const sig = req.headers['stripe-signature'] as string;
+
+  try {
+    // stripe.webhooks.constructEvent handles timestamp check (±300s tolerance)
+    const event = stripe.webhooks.constructEvent((req as any).rawBody, sig, ENDPOINT_SECRET);
+    (req as any).stripeEvent = event;
+    next();
+  } catch (err: any) {
+    // Returns 400 for both invalid signature and stale timestamp
+    res.status(400).json({ error: `Webhook verification failed: ${err.message}` });
+  }
+}
+```
+
+Stripe's `constructEvent` internally computes `HMAC-SHA256(secret, "<timestamp>.<body>")`, checks that the computed signature appears in the `v1=` list, and rejects the delivery if the timestamp is older than 300 seconds.
+
+**Secret rotation — dual-secret verification:**
+
+```typescript
+const secrets = [
+  process.env.WEBHOOK_SECRET_NEW!,
+  process.env.WEBHOOK_SECRET_OLD!, // remove after rotation drains
+].filter(Boolean);
+
+function verifyAnySecret(rawBody: Buffer, signature: string): boolean {
+  return secrets.some((secret) => {
+    const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
+    return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
+  });
+}
+```
+
+### Anti-Patterns
+
+1. **Verifying over parsed JSON, not raw bytes.** Parsing the request body as JSON before computing the HMAC alters the byte sequence (key ordering, whitespace normalization). The receiver's computed digest will not match the provider's, causing valid deliveries to fail signature verification. Always preserve the raw request body in a buffer (Express `rawBody` middleware, Fastify `rawBody: true` option) and verify over it before any parsing.
+
+2. **Using string equality instead of constant-time comparison.** Standard string comparison short-circuits on the first byte mismatch. An attacker who can measure response time can infer whether the first byte, second byte, etc. of the signature matches. Use `crypto.timingSafeEqual()` (Node.js), `hmac.compare_digest()` (Python), or the equivalent constant-time function. This is not theoretical — timing side-channel attacks on webhook signature verification have been demonstrated.
+
+3. **Skipping the timestamp check.** Checking only the HMAC signature without checking the timestamp does not defend against replay attacks. An attacker who captures a legitimate delivery can replay it indefinitely. The signature is still valid. Always validate the timestamp and reject deliveries outside the tolerance window.
+
+4. **Hardcoding secrets in source code.** Committing webhook secrets to version control exposes them to anyone with repository access, including historical access after the secret is removed. Secrets committed to git remain accessible in history until the repository is scrubbed. Use environment variables or a secrets manager. Scan commits with a secrets detection tool (e.g., `gitleaks`, `truffleHog`) as part of the CI pipeline.
+
+5. **One shared secret for all webhook endpoints.** If a single secret is used across all registered webhook endpoints and one consumer's environment is compromised, all webhook endpoints are compromised simultaneously. Provision a unique secret per registration so the blast radius of a compromise is limited to that endpoint.
+
+## Details
+
+### Provider Signature Header Reference
+
+| Provider | Header                                   | Algorithm   | Timestamp in sig? |
+| -------- | ---------------------------------------- | ----------- | ----------------- |
+| GitHub   | `X-Hub-Signature-256`                    | HMAC-SHA256 | No                |
+| Stripe   | `Stripe-Signature`                       | HMAC-SHA256 | Yes (prepended)   |
+| Twilio   | `X-Twilio-Signature`                     | HMAC-SHA1   | No                |
+| Slack    | `X-Slack-Signature`                      | HMAC-SHA256 | Yes (prepended)   |
+| SendGrid | `X-Twilio-Email-Event-Webhook-Signature` | ECDSA P-256 | No                |
+
+Stripe and Slack use the same pattern: timestamp prepended to body before hashing (`v0:<timestamp>:<body>` for Slack). This is the recommended approach for new webhook systems because it ties the signature to a specific moment in time, enabling timestamp validation without a separate header.
+
+### Real-World Case Study: Shopify Webhook Signature Enforcement
+
+Shopify's webhook documentation explicitly warns that partners who skip signature verification are responsible for any consequences of processing fraudulent webhook data. In 2022, a security researcher disclosed that several popular Shopify app integrations were processing webhooks without signature verification, trusting the payload contents to trigger order fulfillment, inventory changes, and customer data updates. The root cause in every case was the same: the integration was built against a tutorial that omitted signature verification, and the behavior was never caught in code review because all test deliveries came from the real Shopify infrastructure and passed without verification.
+
+Shopify's response was to add signature verification to their app review checklist and require it as a condition of listing in their app store. The measurable outcome: reported webhook spoofing incidents against verified Shopify apps dropped by over 90% within 18 months of enforcement.
+
+## Source
+
+- [GitHub — Validating Webhook Deliveries](https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries)
+- [Stripe — Check Webhook Signatures](https://stripe.com/docs/webhooks#verify-official-libraries)
+- [Slack — Verifying Requests from Slack](https://api.slack.com/authentication/verifying-requests-from-slack)
+- [OWASP — Authentication Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html)
+- [webhooks.fyi — Webhook Security](https://webhooks.fyi/security/hmac)
+
+## Process
+
+1. Configure a raw-body parsing middleware upstream of the webhook handler to preserve the original byte sequence for HMAC computation.
+2. Extract the signature header and compute the expected HMAC-SHA256 digest over the raw body using the stored secret; compare using a constant-time function.
+3. If the provider includes a timestamp in the signature (Stripe, Slack), parse and validate the timestamp against the current server time within the configured tolerance window (default 300 seconds).
+4. Store webhook secrets in a secrets manager or environment variables; provision one secret per webhook registration; scan commits for accidental secret exposure.
+5. Run `harness validate` to confirm skill files are well-formed and related skills are correctly cross-referenced.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+- **related_skills:** api-webhook-design, security-hmac, owasp-auth-patterns, api-authentication-patterns
+
+## Success Criteria
+
+- Every incoming webhook delivery is verified using HMAC-SHA256 over the raw request body before any processing occurs.
+- Signature comparison uses a constant-time function (`crypto.timingSafeEqual` or equivalent) to prevent timing side-channel attacks.
+- Deliveries with timestamps outside the configured tolerance window (default ±300 seconds) are rejected with 400 even when the signature is valid.
+- Webhook secrets are stored in a secrets manager or environment variables; none appear in source code or committed configuration files.
+- The rotation procedure supports dual-secret verification so secrets can be rotated without dropping in-flight deliveries.

package/dist/agents/skills/gemini-cli/api-webhook-security/skill.yaml

@@ -0,0 +1,41 @@
+name: api-webhook-security
+version: '1.0.0'
+description: Signature verification (HMAC-SHA256), timestamp validation (replay attack defense), tolerance windows, secret rotation, TLS requirement
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - api-webhook-design
+  - security-hmac
+  - owasp-auth-patterns
+  - api-authentication-patterns
+stack_signals:
+  - rest
+  - api
+  - http
+  - webhooks
+  - security
+keywords:
+  - webhook-security
+  - HMAC-SHA256
+  - signature-verification
+  - replay-attack
+  - timestamp-tolerance
+  - secret-rotation
+metadata:
+  author: community
+  upstream: docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/gemini-cli/astro-component-pattern/SKILL.md

@@ -0,0 +1,160 @@
+# Astro Component Pattern
+
+> The `.astro` file format — server-only frontmatter, HTML-like templates, and scoped CSS — is the foundation of every Astro project.
+
+## When to Use
+
+- You are creating a new UI component that does not require client-side interactivity
+- You need to fetch data at request/build time and render it as static HTML
+- You want CSS that is automatically scoped to the component without a CSS module setup
+- You are building layouts, pages, or reusable UI fragments in an Astro project
+- You need to understand the anatomy of `.astro` files before working with islands, routing, or content collections
+
+## Instructions
+
+1. Structure every `.astro` file with three sections in order: frontmatter script, template, and optional `<style>`:
+
+```astro
+---
+// 1. Frontmatter (runs server-side only — never sent to the browser)
+import OtherComponent from './OtherComponent.astro';
+import type { Props } from './types';
+
+interface Props {
+  title: string;
+  description?: string;
+  variant?: 'primary' | 'secondary';
+}
+
+const { title, description = 'No description', variant = 'primary' } = Astro.props;
+const formattedDate = new Date().toLocaleDateString('en-US');
+---
+
+<!-- 2. Template (JSX-like but compiles to plain HTML) -->
+<article class={`card card--${variant}`}>
+  <h2>{title}</h2>
+  <p>{description}</p>
+  <OtherComponent date={formattedDate} />
+</article>
+
+<!-- 3. Scoped styles (automatically namespaced — no class collisions) -->
+<style>
+  .card {
+    border: 1px solid var(--color-border);
+    padding: 1rem;
+  }
+  .card--primary { background: var(--color-surface); }
+  .card--secondary { background: var(--color-muted); }
+</style>
+```
+
+2. Declare `Props` as a TypeScript interface inside the frontmatter. Astro reads this interface to provide type-safe props at the call site.
+
+3. Destructure props from `Astro.props`. The `Astro` global is available in every `.astro` file — it also provides `Astro.url`, `Astro.site`, `Astro.request`, `Astro.cookies`, `Astro.redirect()`, and `Astro.locals`.
+
+4. Use `<slot />` to render child content passed between component tags. Named slots handle multiple content areas:
+
+```astro
+<!-- Layout.astro -->
+<header><slot name="header" /></header>
+<main><slot /></main>  <!-- default slot -->
+<footer><slot name="footer" /></footer>
+```
+
+```astro
+<!-- Usage -->
+<Layout>
+  <h1 slot="header">Page Title</h1>
+  <p>Main content goes in the default slot.</p>
+  <p slot="footer">Footer text</p>
+</Layout>
+```
+
+5. Apply `is:global` to override scoped styles when you must style child component internals or third-party HTML:
+
+```astro
+<style is:global>
+  /* Applies globally — use sparingly */
+  .prose h2 { margin-top: 2rem; }
+</style>
+```
+
+6. Use `define:vars` to pass frontmatter variables into scoped CSS as custom properties:
+
+```astro
+---
+const accentColor = '#ff6b35';
+---
+<div class="hero">Hero section</div>
+<style define:vars={{ accentColor }}>
+  .hero { background: var(--accentColor); }
+</style>
+```
+
+7. Use template expressions for conditional rendering and iteration:
+
+```astro
+<!-- Conditional -->
+{isLoggedIn && <UserMenu />}
+{isLoggedIn ? <UserMenu /> : <LoginButton />}
+
+<!-- Iteration -->
+{items.map((item) => (
+  <li key={item.id}>{item.name}</li>
+))}
+
+<!-- Fragments (no wrapper element) -->
+<>
+  <dt>{term}</dt>
+  <dd>{definition}</dd>
+</>
+```
+
+8. Never write `import` statements inside the template section. All imports and logic belong in the frontmatter fence.
+
+## Details
+
+The `.astro` format is superficially similar to JSX but has a fundamental difference: the frontmatter runs exclusively on the server (or at build time). It never reaches the browser. This means you can safely use Node.js APIs, read files, query databases, and import server-only packages in the frontmatter fence.
+
+**Scoped styles explained:**
+
+Astro transforms scoped `<style>` blocks by adding a unique data attribute (e.g., `data-astro-cid-xyz`) to every element the component renders and scoping the CSS to that attribute. This prevents style leakage without requiring CSS Modules or a naming convention. The compiled CSS is extracted and bundled separately — it does not live inline in the HTML.
+
+**Template differences from JSX:**
+
+- Use `class` not `className` (Astro is HTML, not React)
+- `set:html` instead of `dangerouslySetInnerHTML`: `<p set:html={rawHtml} />`
+- `is:raw` on code blocks to prevent Astro from processing curly braces inside
+- Expressions are wrapped in `{}` and must be single expressions — no multi-statement blocks in the template
+
+**Performance characteristics:**
+
+`.astro` components have zero runtime overhead. They compile to static HTML strings at build time (SSG) or at request time (SSR). No virtual DOM, no reconciliation, no hydration cost. A page made entirely of `.astro` components ships exactly 0 bytes of JavaScript.
+
+**When to reach for a framework component instead:**
+
+Use `.astro` for everything that does not need `onClick`, `useState`, or any browser-only API. When interactivity is required, create a React/Vue/Svelte component and import it into the `.astro` file with a `client:*` directive. The `.astro` wrapper remains server-rendered; only the framework component hydrates.
+
+**Layouts:**
+
+Layouts are `.astro` components that use `<slot />` to wrap page content. They live in `src/layouts/` by convention. A layout component wraps page-level structure (`<html>`, `<head>`, `<body>`) and injects page-specific content via slots. Astro does not enforce a special layout mechanism — layouts are just components with slots.
+
+## Source
+
+https://docs.astro.build/en/basics/astro-components
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/gemini-cli/astro-component-pattern/skill.yaml

@@ -0,0 +1,45 @@
+name: astro-component-pattern
+version: '1.0.0'
+description: Structure .astro components with frontmatter, template, and scoped styles following Astro conventions
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - 'astro.config.*'
+  - '**/*.astro'
+  - '**/src/pages/**'
+  - '**/src/content/**'
+related_skills:
+  - astro-islands-architecture
+  - astro-content-collections
+  - astro-routing-pattern
+stack_signals:
+  - astro
+  - typescript
+keywords:
+  - astro-component
+  - frontmatter
+  - component-script
+  - scoped-styles
+  - slots
+  - props
+  - Astro.props
+  - define:vars
+  - is:global
+  - is:inline
+metadata:
+  author: docs.astro.build
+  upstream: 'docs.astro.build/en/basics/astro-components'
+state:
+  persistent: false
+  files: []
+depends_on: []