docs: trim SKILL.md inline handlers to verification core; point to examples

[leggetter]

Summary

Trims inline handler code from the three reference SKILL.md files (stripe-webhooks, github-webhooks, shopify-webhooks) to leave only the verification core (~10-20 lines per language), with explicit pointers to the runnable examples/ for the full Express/Next.js/FastAPI handlers. Bakes the rule into AGENTS.md and the generator prompt so future skills follow the same pattern.

Why

Two recent bug classes in this repo trace back to inline-handler drift between SKILL.md and examples/:

1. Stripe SDK 15+ break — stripe.Webhook.construct_event started requiring an object field on event payloads. The example's CI test caught it; if the example had been mirrored into SKILL.md, the inline copy would have rotted silently.
2. Hookdeck CLI convention shift (PR docs: IS_SANDBOX=1 generator note + normative Hookdeck CLI invocation #40 + chore: normalize Hookdeck CLI invocation across existing skills + top-level README #54) — touched 93 files because the same command line was duplicated across every skill's docs.

Pure pointer-only SKILL.md (no inline code at all) would force agents to load an example file for every "how do I verify X?" query, which is the most common skill query. Keeping the verification snippet inline preserves that fast path while removing the duplicated handler that's the real drift surface.

Changes

Spec:

• AGENTS.md "Content Guidelines" — adds a normative rule: SKILL.md inline code is for the verification core only (~25 lines), point to examples/ for the full handler. Includes a worked example of the pattern.
• scripts/skill-generator/prompts/generate-skill.md — adds the same rule to the generator's "Important Guidelines" so new skills follow it deterministically. Also relaxes the existing "Consistency Checks" entry — the verification snippet is what must match the example, not the full handler.

Reference skills (~140 lines net removed):

Skill	Before	After	Δ
stripe-webhooks/SKILL.md	162	120	−42
github-webhooks/SKILL.md	194	131	−63
shopify-webhooks/SKILL.md	182	129	−53

In each, the "Essential Code" block (full Express + FastAPI handlers) becomes a "Verification (core)" block (HMAC compute + timing-safe compare, ~10-20 lines per language) followed by:

> **For complete handlers with route wiring, event dispatch, and tests**, see:
> - [examples/express/](examples/express/)
> - [examples/nextjs/](examples/nextjs/)
> - [examples/fastapi/](examples/fastapi/)

Scope deliberately kept narrow

• No lint script. A length-only threshold ("no code fence > 25 lines") is too coarse — legitimate verification cores can hit that limit while compact-but-duplicated handlers slip under. A content-match lint ("SKILL.md snippet appears verbatim in examples/*") would be a better signal but is enough scope to defer until we see whether this spec + the generator prompt rule holds in practice.
• No sweep of the other 16 existing skills on main. The three reference skills are the ones the generator prompt explicitly tells the AI to mimic — those carry the pattern. A follow-up PR can sweep the rest once we agree the trim style reads well in review.
• No commits pushed to the 13 currently open feat PRs (feat: add discord-webhooks skill #41–feat: add twilio-webhooks skill #52, feat: add scrapfly-webhooks skill #55). Those should land as generated, then get swept later if needed. Touching them now mid-review would force reviewers to re-look at unchanged-by-them code.

Test plan

• SKILL.md files for stripe / github / shopify still answer "how do I verify a $PROVIDER webhook?" cold, without loading the examples
• The verification snippets compile/run as standalone functions (no missing imports)
• examples/{express,nextjs,fastapi}/ tests still pass for the three providers (no behavioral change there — only docs trimmed)
• Spot-check that the AGENTS.md + generator prompt rules read clearly enough that a future generation will follow them

https://claude.ai/code/session_01NNTgQRJss1V7gyzzJ9rjnB

---

Generated by Claude Code