Suggestions for expanding api-and-interface-design skill

Hi Addy, hope you're well! I'm a big fan of your work — I've been using your [web-quality-skills](https://github.com/addyosmani/web-quality-skills) in my setup for a while now.

I recently adapted your [api-and-interface-design skill](https://github.com/addyosmani/agent-skills/blob/main/skills/api-and-interface-design/SKILL.md) into [my dotfiles](https://github.com/citypaul/.dotfiles) and ended up expanding it quite a bit in the process. I wanted to share what I added in case any of it might be useful for the original — totally understand if it doesn't fit your vision for the skill!

**1. Error format guidance with RFC 9457** — Rather than prescribing RFC 9457 (Problem Details) universally, the skill now helps you choose: RFC 9457 (`application/problem+json`) for public APIs with external consumers, or a simpler consistent shape for internal APIs with a single frontend. The key requirement is consistency across endpoints, not a specific format. RFC 9457 is still covered in depth — standard members (`type`, `title`, `status`, `detail`, `instance`), forward-compatible extension members, and the security considerations from §5 — but framed as the gold standard for public APIs rather than a universal mandate. Also includes guidance on when *not* to use problem details. ([See implementation](https://github.com/citypaul/.dotfiles/blob/main/claude/.claude/skills/api-design/SKILL.md#consistent-error-semantics))

**2. Idempotency** — Covers the HTTP method idempotency table, Stripe's idempotency keys pattern for POST, and making DELETE idempotent. The principle "design for at-least-once delivery" feels as fundamental as pagination for any API handling state changes. ([See implementation](https://github.com/citypaul/.dotfiles/blob/main/claude/.claude/skills/api-design/SKILL.md#idempotency))

**3. Rate Limiting** — Standard headers (`RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`) on every response, `Retry-After` with 429 responses, and the idea that rate limits are part of the API contract rather than an afterthought. ([See implementation](https://github.com/citypaul/.dotfiles/blob/main/claude/.claude/skills/api-design/SKILL.md#rate-limiting))

**4. HTTP Caching** — `Cache-Control` directives with common misconceptions (e.g., `no-cache` ≠ don't cache — it means revalidate), ETag revalidation, `Vary` header usage, and `no-store` for sensitive data. This was a gap in both our skills. ([See implementation](https://github.com/citypaul/.dotfiles/blob/main/claude/.claude/skills/api-design/SKILL.md#http-caching))

**5. API Evolution deep-dive** — Expanded "Prefer Addition Over Modification" into versioning strategies (Stripe's date-based pinning vs URL vs header), Postel's Law, Sunset/Deprecation headers (RFC 8594), enum evolution gotchas, and consumer-driven contract testing with Pact. ([See resource](https://github.com/citypaul/.dotfiles/blob/main/claude/.claude/skills/api-design/resources/api-evolution.md))

**6. API Security deep-dive** — The OWASP API Security Top 10 (2023) with TypeScript code examples, covering BOLA, mass assignment, SSRF, and others. Plus authentication pattern guidance (API keys, OAuth2+PKCE, JWT tradeoffs), browser security headers for APIs (`X-Content-Type-Options: nosniff`, `CSP: default-src 'none'`, `Referrer-Policy: no-referrer`), and TLS configuration requirements (TLS 1.2 minimum per RFC 9325/BCP 195). ([See resource](https://github.com/citypaul/.dotfiles/blob/main/claude/.claude/skills/api-design/resources/api-security.md))

**7. HTTP Fundamentals deep-dive** — Based on RFC 9205 "Building Protocols with HTTP" (BCP 56). Covers the cardinal rule (don't redefine HTTP semantics), status code discipline (don't map errors 1:1 — use general codes and put details in the body), HTTP method constraints (no semantic GET bodies, don't use OPTIONS for metadata), header design (no `X-` prefix per RFC 6648), full caching reference, browser security for APIs, and cookie/session security. ([See resource](https://github.com/citypaul/.dotfiles/blob/main/claude/.claude/skills/api-design/resources/http-fundamentals.md))

**8. Authentication & Token Security deep-dive** — Based on RFC 8725 "JWT Best Current Practices" (BCP 225) and RFC 9700 "OAuth 2.0 Security BCP" (BCP 240, January 2025). JWT coverage: algorithm allowlisting (the root cause of `alg: none` attacks), claim validation (`iss`/`sub`/`aud`/`exp`), explicit typing via `typ` header, input sanitization (`kid` as injection vector), compression oracle prevention. OAuth coverage: Authorization Code + PKCE (S256) for all client types, deprecated grants (Implicit, ROPC), exact redirect URI matching, token handling (never in query params), refresh token rotation, CSRF defense, clickjacking prevention, redirect security (303 not 307 for credential POSTs). ([See resource](https://github.com/citypaul/.dotfiles/blob/main/claude/.claude/skills/api-design/resources/auth-security.md))

**9. A few extra rationalizations** — "Retries are the client's problem", "We'll add rate limiting later", "Error messages are just for debugging".

Thanks again for open-sourcing the skills — they've been a great foundation to build on!