ada-agent 0.1.0

package/skills/format/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: format
+description: Run the project formatter and apply consistent style across changed files
+category: review
+---
+
+# Format
+
+Use this to apply the project's canonical code style — run the configured formatter so style is consistent and never a review topic.
+
+1. Detect the project's formatter from config (e.g. `prettier`, `black`/`ruff format`, `gofmt`/`goimports`, `rustfmt`, `.editorconfig`) and its run command.
+2. Prefer the project script (`npm run format`, `make fmt`) over a global binary so the pinned version and config are used.
+3. Run the formatter in write mode, scoped to changed files when possible to keep the diff tight.
+4. Inspect the resulting diff to confirm only whitespace/style changed and no logic was touched.
+5. Run a `--check`/`--diff` pass to verify the tree is now clean, then run the test suite.
+6. Commit formatting on its own so functional diffs aren't buried under style churn.
+
+## Rules
+- Use the project's pinned formatter and config — never impose your own style preferences.
+- Don't reformat untouched files unless that's the explicit task; mass reformatting destroys blame and bloats reviews.
+- If no formatter is configured, match the surrounding file's existing style instead of introducing one.
+- Keep formatting commits separate from logic commits for a clean, reviewable history.
+- A formatter must be idempotent — if a second run produces a diff, the config or version is mismatched; resolve that.

package/skills/game-loop/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: game-loop
+description: Set up a fixed-timestep game loop with decoupled update and render
+category: gamedev
+---
+
+# Game Loop
+
+Reach for this when frame-rate-independent simulation matters: physics, networking, or deterministic gameplay that must behave the same at 30 and 144 fps.
+
+1. Pick a fixed simulation step (e.g. `dt = 1/60`) for update; keep rendering uncapped or vsync-bound separately.
+2. Each frame, measure real elapsed time and add it to an accumulator: `accumulator += frameTime`.
+3. Run `while (accumulator >= dt) { update(dt); accumulator -= dt; }` so simulation advances in fixed chunks.
+4. Compute interpolation alpha = `accumulator / dt` and render between previous and current state to avoid stutter.
+5. Clamp `frameTime` to a max (e.g. 0.25s) before accumulating to prevent the "spiral of death" after a stall.
+6. Keep input sampling at the top of the frame; apply input inside `update`, not render.
+
+## Rules
+- Never pass a variable wall-clock delta into physics — that breaks determinism and collision.
+- Cap accumulated time so a debugger pause or GC stall does not trigger hundreds of catch-up updates.
+- Store previous and current state explicitly so render interpolation has both endpoints.
+- Use a monotonic clock (`performance.now`, `std::chrono::steady_clock`), never system wall time.
+- Decouple render rate from update rate; do not block rendering on the simulation loop.

package/skills/gas-optimize/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: gas-optimize
+description: Reduce a contract's gas cost by measuring hotspots and applying proven storage/logic optimizations
+category: web3
+---
+
+# Gas Optimize
+
+Reach for this after a contract is correct and tested, to cut deployment and per-call gas. Measure first — never optimize blind.
+
+1. Baseline: run `forge test --gas-report` (or `hardhat-gas-reporter`) and `forge snapshot` to capture current costs per function.
+2. Attack storage — the biggest lever: pack variables into single 32-byte slots, shrink types where safe, cache `storage` reads in `memory`/local vars inside loops, and use `immutable`/`constant` for fixed values.
+3. Tighten loops: cache `array.length`, avoid repeated SLOADs, prefer `unchecked` increments where overflow is impossible (post-0.8).
+4. Trim logic: replace `require`-strings with custom errors, use `calldata` over `memory` for read-only external args, mark functions `external`, and short-circuit cheap conditions first.
+5. Tune the compiler: set the `optimizer` runs to match usage (low runs = cheaper deploy, high runs = cheaper calls); consider Yul/inline assembly only as a last resort.
+6. Re-measure after each change with `forge snapshot --diff`; keep changes that help, revert those that don't.
+7. Re-run the full test suite — confirm optimizations changed cost, not behavior.
+
+## Rules
+- Always measure before and after; an "obvious" optimization can cost more after compiler optimization.
+- Never sacrifice safety for gas — keep reentrancy guards, overflow checks, and access control intact.
+- Only use `unchecked` when you can prove the arithmetic cannot overflow/underflow.
+- Storage (SSTORE/SLOAD) dominates cost; optimize slot packing and read caching before micro-tweaks.
+- Avoid assembly unless the gas win is large, tested, and commented — it removes safety nets.
+- Watch the storage-layout: reordering variables can break upgradeable/proxy contracts.

package/skills/gdpr-review/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: gdpr-review
+description: Review how the codebase collects, stores, and shares PII for GDPR compliance
+category: compliance
+---
+
+# GDPR Review
+
+Use when auditing a feature or service that touches personal data, or before shipping anything that collects user information into the EU/EEA scope.
+
+1. Inventory PII: grep for fields and patterns (email, name, phone, IP, address, `user_id`, device IDs, geolocation, cookies) and list every place personal data enters the system.
+2. Trace data flow for each item — where it is stored (DB tables, logs, caches, analytics, third-party SaaS), how long, and who it is shared with.
+3. Check the legal basis and consent: is collection tied to a stated purpose, is consent recorded and revocable, and is data minimized to what the purpose needs.
+4. Verify data-subject rights are implementable: export (portability), deletion/erasure, and rectification — confirm a delete actually purges across DB, backups policy, logs, and downstream processors.
+5. Check protection controls: encryption at rest/in transit, access scoping, and that PII is not leaking into logs, error traces, URLs, or analytics events.
+6. Confirm cross-border transfers and sub-processors have a lawful mechanism, and that retention/auto-expiry is enforced in code, not just documented.
+7. Report findings ranked by risk with concrete file/line references and a remediation per gap.
+
+## Rules
+- Flag any PII written to plaintext logs, analytics, or third-party trackers without consent — this is a common and serious leak.
+- "Soft delete" (a flag) does not satisfy erasure; verify the data is truly removed or anonymized.
+- Pseudonymized data is still personal data if it can be re-linked; treat reversible hashing/IDs as PII.
+- Do not assume backups are out of scope — note the retention and deletion policy for them.
+- You are reviewing engineering controls, not giving legal advice; recommend legal/DPO sign-off for basis and contracts.

package/skills/github-actions/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: github-actions
+description: Author or fix a GitHub Actions workflow with correct triggers, jobs, caching, and permissions
+category: ci-cd
+---
+
+# GitHub Actions
+
+Use when creating a new `.github/workflows/*.yml` or debugging one that fails, misfires, or runs too often.
+
+1. Set the right triggers in `on:` (`push`, `pull_request`, `workflow_dispatch`, `schedule`) and scope branches/paths to avoid noise.
+2. Define jobs with a pinned `runs-on` image; use a `matrix` only when you genuinely test multiple versions.
+3. Pin actions to a tag or SHA (`actions/checkout@v4`), set up the runtime, and cache deps with `actions/cache` or the setup action's built-in cache.
+4. Grant least-privilege `permissions:` (default read; add `contents: write` / `id-token: write` only where needed).
+5. Store credentials in repo/org Secrets and reference via `${{ secrets.X }}`; never echo them.
+6. Validate by pushing to a branch and reading the run logs; when fixing, reproduce the failing step and inspect its exact output.
+
+## Rules
+- Pin third-party actions by SHA or major tag — floating `@master` is a supply-chain risk.
+- Set explicit `permissions:` per workflow or job; the broad default token is too powerful.
+- Add `concurrency:` with `cancel-in-progress` to kill superseded runs on the same ref.
+- Don't print secrets to logs and don't expose them to PRs from forks.
+- When debugging, read the failing job's logs first — guessing at YAML wastes runs.

package/skills/glossary/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: glossary
+description: Build a glossary of domain and project terms so docs and code use one shared, unambiguous vocabulary.
+category: docs
+---
+
+# Glossary
+
+Use when a project has overloaded or insider terms ("tenant", "job", "account") that mean different things to different people — a glossary fixes the canonical meaning.
+
+1. Harvest terms from code identifiers, docs, schemas, and onboarding questions; flag any word used two ways.
+2. For each term write a one-sentence definition in plain language, then add nuance only if needed.
+3. Note synonyms and explicitly call out "not to be confused with" near-misses.
+4. Add a tiny concrete example or the canonical code/type it maps to (`Order → orders table, OrderEntity`).
+5. Sort alphabetically with stable anchors so terms are deep-linkable from other docs.
+6. Cross-link related terms and link the glossary from the docs landing page and CONTRIBUTING.
+7. Assign an owner and review on schema/domain changes so definitions track reality.
+
+## Rules
+- One canonical definition per term — if a word legitimately means two things, that's two entries with disambiguators.
+- Define in plain words; don't define a term using three other undefined terms.
+- Tie each term to its concrete artifact (table, type, endpoint) where one exists.
+- Keep entries short; a glossary is a lookup, not an essay.
+- Update the glossary in the same PR that renames or repurposes a domain term.

package/skills/go-idioms/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: go-idioms
+description: Apply idiomatic Go for error handling, context propagation, and interface design
+category: languages
+---
+
+# Go Idioms
+
+Use this when reviewing or refactoring Go that fights the language — swallowed errors, missing context, or fat interfaces.
+
+1. Handle every error explicitly at the call site: return it wrapped with `fmt.Errorf("doing X: %w", err)` so callers can `errors.Is`/`errors.As` it; never discard with `_` unless intentional and commented.
+2. Thread `context.Context` as the first parameter through any call that does I/O or can block, and honor cancellation (`ctx.Err()`, `<-ctx.Done()`).
+3. Define interfaces where they're consumed, keep them small (one or two methods), and accept interfaces but return concrete types.
+4. Use `defer` for cleanup (close, unlock) right after acquiring the resource; prefer `sync.Mutex` zero-value over pointers and don't copy locks.
+5. Replace sentinel-error string matching with typed errors or `errors.Is`, and use `errors.Join` to aggregate when needed.
+6. Run `go vet`, `gofmt`/`goimports`, and `staticcheck`; fix shadowed `err`, unchecked returns, and ineffective assignments.
+
+## Rules
+- Wrap errors with `%w` (not `%v`) when callers may need to inspect the cause; add context, don't just rethrow.
+- Don't start goroutines you can't stop — every goroutine needs a clear exit path tied to a context or channel close.
+- Avoid `interface{}`/`any` in APIs; use concrete types or generics. Empty interfaces push type errors to runtime.
+- Name things tersely and idiomatically (`r io.Reader`, not `reader`), and return early instead of nesting `if/else`.
+- Don't panic across package boundaries — return errors; reserve `panic` for truly unrecoverable programmer bugs.

package/skills/gpu-profile/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: gpu-profile
+description: Profile GPU frame time and find the draw-call or fill-rate bottleneck behind dropped frames and jank
+category: graphics
+---
+
+# GPU Profile
+
+Reach for this when the frame rate drops or stutters and you need to find whether the GPU, the draw-call count, or the CPU submit is the bottleneck.
+
+1. Measure first, don't guess: get a stable frame-time number (ms/frame, not just FPS) from the browser/engine profiler or a GPU timer query. One slow frame vs sustained slowness point to different causes.
+2. Split CPU vs GPU: if CPU time per frame (JS/submit) already exceeds your budget, the GPU is starved — optimize the submit side. If CPU is cheap but frame time is high, you're GPU-bound; continue.
+3. For GPU-bound, separate vertex/draw-call cost from fill-rate: shrink the canvas to a tiny size and re-measure. If it speeds up dramatically, you're fill-rate/overdraw bound (fragment shader, blending, big textures); if not, you're geometry/draw-call bound.
+4. For draw-call bound, count draw calls per frame and batch: merge meshes, instance repeated geometry, atlas textures, and sort by material to cut state changes. Thousands of tiny draws is the classic cause.
+5. For fill-rate bound, reduce overdraw (sort opaque front-to-back, cut large transparent layers), lower the heaviest fragment shader cost, shrink/compress textures, and cap devicePixelRatio.
+6. Confirm the fix against the same frame-time metric under the same scene, and watch for a moved bottleneck (fixing fill-rate can expose a draw-call wall).
+
+## Rules
+- Profile in milliseconds per frame; FPS hides how close you are to the next dropped-frame threshold.
+- The resize-the-canvas test is the fastest way to tell fill-rate from geometry bound — use it before optimizing.
+- Draw-call count and state changes, not triangle count, are usually the wall on modern GPUs — batch and instance.
+- Always disable browser/devtools overlays and run a release build when measuring; debug layers distort timings.
+- Re-measure after each change; optimizing the non-bottleneck buys nothing and bottlenecks move.

package/skills/graphify/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: graphify
+description: Turn code, data, or relationships into a clear visual graph (Mermaid/Graphviz), then render it.
+category: docs
+---
+
+# Graphify
+
+Use when a relationship, flow, hierarchy, or dependency would land better as a picture than prose.
+
+1. Identify the **nodes** (entities) and **edges** (relationships), and what each edge means — calls, depends-on, contains, flows-to.
+2. Pick the graph type that fits: flowchart (a process), sequence (interactions over time), ER (a data model), class (types), state (modes), or a dependency graph (modules/packages).
+3. Express it as code — prefer **Mermaid** (renders on GitHub and most viewers) in a fenced ` ```mermaid ` block; use Graphviz/DOT or D2 when you need precise layout control.
+4. Keep it legible: ≤ ~15 nodes per view, short labels, group with subgraphs, `LR` direction for wide flows and `TB` for hierarchies.
+5. Put it in a doc (e.g. `docs/<name>.md`) or render to SVG/PNG (`mmdc -i in.mmd -o out.svg`, `dot -Tsvg`) and link it.
+
+## Rules
+- One graph = one idea. If it needs a legend longer than the graph, split it.
+- Derive nodes/edges from the actual code/data — don't invent structure.
+- Label edges with the relationship, not just bare arrows.
+- Re-render after edits so the committed image matches its source.

package/skills/graphql-resolver/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: graphql-resolver
+description: Add a GraphQL resolver and its schema type, wired into the existing graph
+category: api
+---
+
+# Graphql Resolver
+
+Use when exposing new data or a mutation through GraphQL — you need a schema type plus the resolver that backs it.
+
+1. Add or extend the SDL type (or code-first type) — define fields, nullability, and arguments; reuse existing scalars and enums.
+2. Wire the field into the root `Query`/`Mutation` (or parent type) so the schema actually exposes it.
+3. Implement the resolver, pulling shared services and the request `context` (auth, loaders) rather than instantiating clients inline.
+4. Use a DataLoader (or equivalent batching) for any field that fetches per-parent to avoid N+1 queries.
+5. Enforce auth/authorization inside the resolver or via a directive/middleware — never assume the gateway did it.
+6. Regenerate typed bindings if the project uses codegen, then add a resolver test covering one success and one error/forbidden case.
+
+## Rules
+- Keep schema and resolver in sync; if codegen exists, run it and commit the generated output.
+- Return GraphQL errors via the framework's error type (with extensions/codes), not by throwing raw strings.
+- Batch with DataLoader for list-of-parents fields; a naive resolver silently becomes an N+1.
+- Make nullability deliberate — non-null fields that can fail will null out the whole parent.
+- Don't over-fetch: select only the columns/fields the resolver actually returns.

package/skills/grpc-service/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: grpc-service
+description: Define a gRPC service from proto through generated stubs to a working server and client
+category: networking
+---
+
+# gRPC Service
+
+Reach for this when adding RPC between services and you want a typed contract, code-gen, and streaming. Best when both ends are yours.
+
+1. Write a `.proto` (`syntax = "proto3";`) with a `package`, a `service` block, and `rpc` methods; give every method a dedicated request and response message (never reuse one message for both).
+2. Pick the right method shape per call: unary, server-streaming (`returns (stream X)`), client-streaming (`(stream X)`), or bidi.
+3. Generate stubs with `protoc` (or `buf generate`) for your language, and check generated code into the build, not the repo unless that's the convention.
+4. Implement the server: bind the service to a server object, register interceptors for auth/logging, and serve on a port with a health check (`grpc.health.v1`).
+5. Build the client with a channel/stub, set per-call deadlines (`context` timeout / `CallOptions`), and handle the typed status codes.
+6. Test with `grpcurl -plaintext host:port list` and a real client call before wiring callers.
+
+## Rules
+- Never renumber or reuse field tags; mark removed fields `reserved`. Tag numbers are the wire contract, not the field names.
+- Always set a deadline on every client call — gRPC has no default timeout and a hung server blocks the caller forever.
+- Return proper `status` codes (`NOT_FOUND`, `INVALID_ARGUMENT`, `UNAVAILABLE`), not `UNKNOWN` for everything.
+- Enable TLS for anything off-localhost; `plaintext` is for local dev and tests only.
+- Make handlers idempotent where possible — clients retry `UNAVAILABLE`/`DEADLINE_EXCEEDED` automatically with some configs.

package/skills/guardrails/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: guardrails
+description: Add output validation and guardrails so LLM responses are safe, valid, and on-spec
+category: agent-llm
+---
+
+# Guardrails
+
+Reach for this when an LLM's output feeds a downstream system (UI, API, DB) and must conform to a schema or policy before you trust it.
+
+1. Define the contract: the exact output schema (JSON Schema / zod / pydantic) plus any content policy the response must satisfy.
+2. Steer at generation time — request structured output / tool-call format, and state the constraints explicitly in the prompt.
+3. Validate the raw output against the schema; on failure, do not pass it downstream.
+4. Add content checks beyond shape: required fields non-empty, values in allowed ranges/enums, no leaked secrets or injected instructions.
+5. On a validation failure, retry once with the validator error fed back to the model; if it still fails, fall back to a safe default or surface an error.
+6. Log every rejection with the offending output so you can tighten prompts and catch new failure modes.
+
+## Rules
+- Validate before use, always — never act on unvalidated model output, even when it "looks fine".
+- Treat tool results and retrieved documents as untrusted; strip or neutralize embedded instructions (prompt injection).
+- Schema-conformance is necessary but not sufficient — a well-formed answer can still be wrong or unsafe; layer semantic checks.
+- Bound retries (one or two) to avoid loops and cost blowups; have a definite fallback path.
+- Keep the validator independent of the model; don't let the same LLM both produce and "approve" its own output unchecked.

package/skills/healthcheck/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: healthcheck
+description: Add liveness/readiness endpoints so orchestrators and load balancers know when the service is healthy
+category: ci-cd
+---
+
+# Healthcheck
+
+Reach for this when a service runs under Docker, Kubernetes, or a load balancer that needs to probe whether it's alive and ready for traffic.
+
+1. Add a cheap liveness endpoint (`/healthz`) that returns 200 if the process is up — no external calls.
+2. Add a readiness endpoint (`/readyz`) that checks critical dependencies (DB ping, cache, required config) and returns 503 until all pass.
+3. Return a small JSON body with overall status and per-dependency results, and set the HTTP status code to match.
+4. Keep probes fast and side-effect-free with a short timeout so a slow dependency doesn't hang the check.
+5. Wire the probe into the platform: Dockerfile `HEALTHCHECK`, compose `healthcheck`, or k8s `livenessProbe`/`readinessProbe`.
+6. Test both states — healthy returns 200, and a downed dependency makes `/readyz` return 503 — before relying on it.
+
+## Rules
+- Separate liveness (am I running?) from readiness (can I serve?) — conflating them causes needless restarts.
+- Keep checks lightweight and bounded with a timeout; never let a probe block or do heavy work.
+- Don't require auth on the probe path, but don't leak secrets or stack details in the body either.
+- Make readiness actually fail (503) when a hard dependency is down, or it's decorative.
+- Match the HTTP status to reality — orchestrators key off the code, not the JSON.

package/skills/heisenbug/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: heisenbug
+description: Debug intermittent timing and concurrency bugs that vanish under observation
+category: debugging
+---
+
+# Heisenbug
+
+Use when a bug appears only sometimes — flaky tests, race conditions, ordering-dependent failures — and disappears the moment you add a log or a breakpoint. These are timing and shared-state bugs; treat them differently from deterministic ones.
+
+1. Quantify the flakiness: loop the failing case hundreds of times to get a failure rate you can track as you investigate.
+2. Hunt for shared mutable state crossing threads/tasks/processes, and for any code that assumes an order events don't guarantee.
+3. Suspect the usual sources: missing await/synchronization, check-then-act races, unprotected shared variables, reliance on iteration/map order, or wall-clock timing.
+4. Make the race more likely instead of less — add jitter/delays, increase concurrency, randomize scheduling, shrink timeouts — so it fails almost every run.
+5. Once it fails reliably, fix the cause: add proper locking/atomics, await the dependency, make the operation idempotent, or remove the shared state.
+6. Verify by running the original loop thousands of times with zero failures, then remove any artificial delays you added.
+
+## Rules
+- Adding a log or debugger changes timing and can hide the bug — prefer post-hoc capture (record then inspect) over live stepping.
+- A "fix" that just lowers the failure rate is not a fix; a real fix makes it impossible, not rare.
+- Don't paper over flakiness with retries or longer sleeps — that hides a race that will resurface under load.
+- Set a fixed seed for anything random so a failing run is reproducible.
+- Reproduce on the same concurrency/hardware profile as production; single-core or low-load runs may never trigger it.

package/skills/helm-chart/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: helm-chart
+description: Author a Helm chart with templated manifests, values, and helpers
+category: cloud
+---
+
+# Helm Chart
+
+Reach for this when a workload needs to ship to multiple environments with varying config — Helm templates the manifests and exposes the knobs through `values.yaml`.
+
+1. Scaffold with `helm create <name>` then strip the generated boilerplate you don't need.
+2. Define the chart contract in `Chart.yaml` (`apiVersion: v2`, `version`, `appVersion`) and declare any subchart `dependencies`.
+3. Move all environment-varying values into `values.yaml` with documented defaults; reference them as `.Values.x` in templates.
+4. Templatize `templates/*.yaml`, using `_helpers.tpl` for shared label/name logic and `include` to reuse it.
+5. Render and lint with `helm lint` and `helm template . -f values-prod.yaml` to eyeball the output.
+6. Dry-run against a cluster with `helm install --dry-run --debug` (or `helm upgrade --install`) before going live.
+7. Bump `Chart.yaml` `version` on every change and run `helm dependency update` when subcharts change.
+
+## Rules
+- Quote templated strings (`{{ .Values.x | quote }}`) and use `default`/`required` to fail fast on missing values.
+- Never commit real secrets to `values.yaml`; use `--set`, a secrets plugin, or an external secret store.
+- Keep `appVersion` (the app) distinct from chart `version` (the packaging) and bump them independently.
+- Indent with `nindent`, not hand-counted spaces, to avoid YAML breakage.
+- Provide a `values.schema.json` or sane validation so bad overrides are caught at install time.

package/skills/hero-section/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: hero-section
+description: Design a striking, conversion-focused hero with one clear message, sharp hierarchy, and a single CTA.
+category: ui-design
+---
+
+# Hero Section
+
+Reach for this for the first screen of a landing page — the hero has ~3 seconds to land the value proposition and drive one action.
+
+1. Lock the message architecture: one eyebrow/kicker (optional), one headline stating the outcome (not the feature), one subhead clarifying, one primary CTA. Cut everything else.
+2. Build a real type scale with `clamp()` — e.g. headline `clamp(2.5rem, 5vw + 1rem, 5rem)`, tight `line-height: 1.05`, and `letter-spacing: -0.02em` on large display text for an editorial feel.
+3. Establish hierarchy through contrast, not just size: the CTA is the highest-contrast element on screen; the subhead sits in a muted foreground; supporting visuals never out-shout the headline.
+4. Give it breathing room — generous vertical rhythm on an 8px scale, a constrained measure (~60ch) on the subhead, and asymmetry (off-center text + image) to avoid a sterile centered template.
+5. Add one tasteful motion beat on load: staggered fade-rise of headline → subhead → CTA (40–60ms apart, ease-out, ≤400ms total). Subtle, once, never looping.
+6. Engineer for performance and LCP: the headline is real text (not an image), hero media is `priority`/preloaded and properly sized, and the layout is reserved to prevent CLS.
+
+## Rules
+- One primary CTA. A secondary "Learn more" can exist as a quieter ghost/text link, never a competing button.
+- The headline sells the outcome to the user; if it could appear on a competitor's site verbatim, rewrite it.
+- Maintain ≥4.5:1 contrast for headline text over any image/gradient — add a scrim or duotone rather than risk legibility.
+- Don't center everything by reflex; intentional asymmetry and a strong grid read as designed, not default.
+- Hero must be legible and complete above the fold on a 360px phone before you polish desktop.

package/skills/html-email/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: html-email
+description: Build a responsive HTML email with inline CSS, table layout, and dark-mode support that survives Outlook/Gmail.
+category: html
+---
+
+# HTML Email
+
+Reach for this when you need a marketing or transactional email that renders consistently across Gmail, Outlook, and Apple Mail. Email clients strip `<style>`, ignore flexbox/grid, and demand tables.
+
+1. Set up the skeleton: `<table role="presentation" width="100%">` outer wrapper centering a `<table width="600">` content table; never use `<div>` for layout.
+2. Add `<!--[if mso]>` conditional comments for Outlook (it uses Word's rendering engine) and a VML fallback for any background image or button.
+3. Write all visual CSS inline on elements (`style="..."`); keep a `<style>` block in `<head>` only for media queries and `:root` color-scheme hints.
+4. Make it fluid: content table `width="600"` with `max-width:600px`, single-column stacking via `@media (max-width:600px){ .col{display:block;width:100%!important} }`.
+5. Add dark mode: `<meta name="color-scheme" content="light dark">`, `@media (prefers-color-scheme:dark)` overrides, and dark-friendly logo (transparent PNG).
+6. Use bulletproof buttons (table-cell with padding + bgcolor, not a styled `<a>`), set `alt` on every image, and keep total HTML under ~100KB (Gmail clips beyond 102KB).
+7. Test in Litmus/Email-on-Acid or send to real Gmail + Outlook + iOS before shipping.
+
+## Rules
+- Tables for layout, inline CSS for styling — no flexbox, grid, float, or external stylesheets.
+- Always provide `alt` text and explicit `width`/`height`; many clients block images by default.
+- Use web-safe fonts with a stack fallback; custom `@font-face` fails in Outlook and most clients.
+- Use absolute https URLs for every image and link; no relative paths.
+- Include a plain-text preheader (hidden span) and a working unsubscribe link for deliverability.

package/skills/html-form/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: html-form
+description: Build an accessible form with native + custom validation, clear error messaging, and correct input semantics.
+category: html
+---
+
+# HTML Form
+
+Use for any data-entry UI (signup, checkout, settings). Lean on native HTML form features first; add JS only to enhance, not replace, them.
+
+1. Structure with a real `<form>`, every control wrapped by or linked to a `<label for>`; group related fields in `<fieldset>` with a `<legend>`.
+2. Use the right input types and attributes (`type=email/tel/number/date`, `inputmode`, `autocomplete`, `required`, `minlength`, `pattern`) so browsers validate and mobile keyboards adapt.
+3. Validate progressively: native constraints first, then JS via the Constraint Validation API (`setCustomValidity`, `:invalid`); validate on blur/submit, not on every keystroke.
+4. Surface errors accessibly: tie each message to its field with `aria-describedby`, set `aria-invalid="true"`, move focus to the first error, and announce a summary in a live region.
+5. Submit safely: prevent double-submit, show a pending state, handle server errors, and re-validate on the server (client validation is never trusted).
+6. Polish UX: logical tab order, visible focus states, helpful placeholder vs. label distinction, and preserve entered values on failed submit.
+
+## Rules
+- Every input needs a programmatically associated `<label>`; placeholders are not labels.
+- Use native validation attributes before reaching for JS; they work without scripts.
+- Errors must be perceivable by screen readers (`aria-describedby` + `aria-invalid`), not color alone.
+- Always re-validate and sanitize on the server — client checks are a UX nicety, not security.
+- Set `autocomplete` and correct `type`/`inputmode` so password managers and mobile keyboards work.

package/skills/html-sanitize/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: html-sanitize
+description: Sanitize untrusted/user-supplied HTML to be XSS-safe using an allowlist library, never hand-rolled regex.
+category: html
+---
+
+# HTML Sanitize
+
+Use whenever you render HTML you didn't author — comments, rich-text input, CMS content, AI output — into a page. Naive insertion is a stored-XSS hole.
+
+1. Pick a battle-tested allowlist sanitizer: DOMPurify (browser/Node), sanitize-html (Node), Bleach (Python), or the language's equivalent; never write your own escaper.
+2. Configure a strict allowlist of tags and attributes (e.g., `p, a, strong, em, ul, li, code` + `href`, `title`); deny everything else by default.
+3. Strip dangerous vectors: `<script>`, `<style>`, `<iframe>`, event handlers (`on*`), and `javascript:`/`data:` URLs in `href`/`src`.
+4. Force-harden links: set `rel="noopener noreferrer"` and validate the URL scheme against an allowlist (`https`, `mailto`).
+5. Sanitize server-side as the source of truth (don't trust client-side sanitization alone) and re-sanitize on render, not just on input.
+6. Add a Content-Security-Policy header as defense-in-depth, and test with known XSS payloads (`<img src=x onerror=alert(1)>`, SVG/MathML vectors, mutation-XSS cases).
+
+## Rules
+- Never sanitize HTML with regex or string replacement — parsers and mXSS will defeat it.
+- Allowlist what's permitted; never blocklist "bad" tags (the bad list is infinite).
+- Keep the sanitizer library updated; bypasses are found and patched regularly.
+- For plain text, escape (`&lt; &gt; &amp;`) instead of sanitizing — don't allow any HTML at all.
+- CSP is a backstop, not a substitute for sanitizing the input.

package/skills/html-table/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: html-table
+description: Build an accessible, responsive data table with sortable columns, proper headers, and a sensible mobile layout.
+category: html
+---
+
+# HTML Table
+
+Use for presenting tabular data (dashboards, reports, listings). The goal is correct table semantics plus optional client-side sorting that stays accessible.
+
+1. Use real table structure: `<table>` with `<caption>`, `<thead>`, `<tbody>`, and `<th scope="col">` / `<th scope="row">` so screen readers announce header context.
+2. Add sorting on `<th>` headers: a `<button>` inside the header cell, `aria-sort="ascending|descending|none"` reflecting state, sorting `<tbody>` rows in JS (stable sort, type-aware for numbers/dates).
+3. Keep keyboard support: header sort controls are real buttons (focusable, Enter/Space activate); don't trap focus.
+4. Handle overflow responsively: wrap in a scroll container (`overflow-x:auto` with `tabindex="0"` and an `aria-label`), or restructure to stacked cards under a breakpoint with data labels.
+5. Style for scanability: zebra striping via `:nth-child`, sticky `<thead>` for long tables, right-align numeric columns, and clear sort-direction indicators.
+6. For large datasets add pagination or virtualization rather than rendering thousands of rows; announce row counts and sort changes via a polite live region.
+
+## Rules
+- Tables are for tabular data only — never for page layout.
+- Always include `scope` on header cells (and `headers`/`id` for complex multi-level headers).
+- Reflect sort state in `aria-sort` and keep the sort control a real `<button>`, not a clickable `<div>`.
+- Provide an accessible name (`<caption>` or `aria-label`) describing what the table contains.
+- For horizontal scroll, make the scroll container keyboard-focusable so it's reachable without a mouse.

package/skills/html-to-pdf/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: html-to-pdf
+description: Render HTML to a print-quality PDF with correct page breaks, margins, headers/footers, and selectable text.
+category: html
+---
+
+# HTML to PDF
+
+Use when you need a paginated, print-fidelity PDF (invoice, report, certificate) from HTML/CSS rather than a screenshot.
+
+1. Pick the engine: headless Chromium (Playwright/Puppeteer `page.pdf()`) for modern CSS, or WeasyPrint for pure-Python paged-media; both keep text selectable.
+2. Author a print stylesheet with `@page { size: A4; margin: 18mm }` and `@media print` rules; set a base font size in `pt`/`mm`, not `px`.
+3. Control pagination with `break-inside: avoid` on cards/tables, `break-before: page` for new sections, and `orphans`/`widows` for paragraphs.
+4. Add running headers/footers and page numbers via `@page` margin boxes (`content: counter(page)`) or the engine's header/footer template option.
+5. Ensure `printBackground: true` (Chromium) so background colors/images render; embed fonts so they aren't substituted.
+6. Verify output: check pixel-perfect margins, that tables don't split mid-row awkwardly, links remain clickable, and text is selectable (not rasterized).
+
+## Rules
+- Use real paged-media CSS, not viewport hacks; set page size and margins in `@page`.
+- Wait for fonts and images to fully load before generating (`waitUntil: networkidle`) or content clips.
+- Prefer vector/text output over screenshots so the PDF stays small and searchable.
+- Test the exact paper size you'll print (A4 vs Letter differ); don't assume the default.
+- Avoid fixed-height containers for variable content — they overflow or clip across page breaks.

package/skills/http-client/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: http-client
+description: Build a robust HTTP client with timeouts, bounded retries, backoff, and connection reuse
+category: networking
+---
+
+# HTTP Client
+
+Use whenever code calls an external HTTP API and must survive flaky networks and slow upstreams. A naive `fetch`/`get` with no timeout is a production incident waiting to happen.
+
+1. Set explicit timeouts on every request — connect, read/idle, and a total deadline — so a hung server can't pin a thread or goroutine forever.
+2. Reuse one client/connection pool instance across calls (keep-alive); creating a client per request exhausts sockets.
+3. Retry only idempotent, transient failures (connection errors, 429, 5xx) with exponential backoff + jitter and a hard cap on attempts.
+4. Honor `Retry-After` on 429/503; respect server-provided backoff over your own schedule.
+5. Add a circuit breaker or failure budget so a dead dependency fails fast instead of amplifying load with retries.
+6. Propagate cancellation (context/`AbortSignal`), set a descriptive `User-Agent`, and check status codes explicitly — don't assume 2xx.
+
+## Rules
+- Never retry non-idempotent requests (`POST` without an idempotency key) — you'll double-charge, double-send, double-create.
+- Add jitter to backoff; synchronized retries from many clients cause thundering-herd retry storms.
+- Always cap total retries and total elapsed time; unbounded retry loops turn a blip into an outage.
+- Read and close response bodies even on errors, or you leak connections from the pool.
+- Don't log full request/response bodies or auth headers by default — redact secrets.

package/skills/i18n/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: i18n
+description: Extract hardcoded strings and set up internationalization with locale-aware formatting
+category: frontend
+---
+
+# I18n
+
+Use when preparing an app for multiple languages: pulling hardcoded copy into message catalogs and wiring up locale switching and formatting.
+
+1. Pick or confirm the i18n library that fits the framework (e.g. i18next, react-intl, next-intl, vue-i18n) and set a default locale plus a fallback.
+2. Sweep the UI for user-facing strings and replace each with a translation call keyed by a stable, namespaced id (e.g. `cart.checkout.button`), not the English text.
+3. Externalize all strings into per-locale catalog files; seed the default locale and leave other locales as keys to be translated.
+4. Handle plurals, gender, and variables through the library's interpolation/ICU features — never build sentences by string concatenation.
+5. Use locale-aware formatting (`Intl.NumberFormat`, `Intl.DateTimeFormat`, currency, relative time) for all numbers, dates, and money instead of manual formatting.
+6. Wire a locale provider/switcher, persist the choice, set `<html lang>`/`dir` (including RTL), and lazy-load the active locale's catalog.
+
+## Rules
+- Never concatenate translated fragments; pass variables into a single parameterized message.
+- Use stable semantic keys, not English copy, as ids so wording changes don't break lookups.
+- Keep pluralization in the catalog (ICU/plural rules), not in component conditionals.
+- Format every date, number, and currency via `Intl`/the i18n layer, never hand-rolled.
+- Support RTL: set `dir`, avoid left/right-only CSS, and prefer logical properties (`margin-inline-start`).

package/skills/i2c-spi/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: i2c-spi
+description: Configure I2C or SPI peripheral communication and debug bus-level issues
+category: gamedev
+---
+
+# I2C / SPI
+
+Reach for this when talking to a sensor, EEPROM, or display over I2C or SPI and the link is not working yet.
+
+1. From the datasheet get the device address (I2C) or CS pin + SPI mode (CPOL/CPHA) and max clock rate.
+2. Configure pins: I2C needs open-drain SDA/SCL with pull-ups; SPI needs MOSI/MISO/SCK plus a GPIO chip-select.
+3. Set the bus clock below the device max, then do a probe: I2C address ACK scan, or SPI read of a known ID register.
+4. Implement a transfer: I2C start→addr+R/W→data→stop; SPI assert CS→full-duplex byte exchange→deassert CS.
+5. Add per-transfer timeouts and check ACK/error flags; return an error instead of hanging on a missing device.
+6. Verify with a logic analyzer if the first transfer fails — confirm clock, framing, and ACK on the wire.
+
+## Rules
+- I2C requires pull-up resistors on SDA and SCL; floating lines look like a dead bus.
+- Match SPI mode (CPOL/CPHA) exactly to the device; a wrong mode gives garbage with no error flag.
+- Toggle chip-select per transaction and honor setup/hold timing; sharing CS or wrong polarity corrupts reads.
+- Respect register auto-increment and burst-read rules; many devices need a specific address-then-read sequence.
+- On a stuck I2C bus (SDA held low), clock out up to 9 pulses or power-cycle the device to recover.

package/skills/image-decode/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: image-decode
+description: Debug image decode/encode failures — wrong format, corruption, bit depth, ICC profile, truncated files
+category: image
+---
+
+# Image Decode
+
+Reach for this when an image fails to load, decodes to garbage/partial, or comes out with wrong colors/depth after a round-trip.
+
+1. Reproduce and capture the exact error or symptom (exception, truncated render, color shift). Save the raw bytes so you can inspect them independent of your code.
+2. Verify the actual format vs the claimed one: check magic bytes / `file`, not the extension. A `.png` that's really a JPEG (or HTML error page) is a classic decode failure.
+3. Check for truncation/corruption: compare on-disk size to the header's expected size, try decoding with a strict decoder, and re-download/re-export the source if the tail is missing. Enable `ImageFile.LOAD_TRUNCATED_IMAGES` only to confirm truncation, not as a fix.
+4. Inspect bit depth and channel count: 8 vs 16-bit, palette (indexed) vs RGB, grayscale vs RGBA. A stage assuming uint8 on a 16-bit PNG, or RGB on an indexed/CMYK image, decodes to wrong values.
+5. Check ICC color profiles: CMYK JPEGs and wide-gamut PNGs with an embedded profile render wrong if the profile is dropped or not converted to sRGB. Convert explicitly rather than discarding the profile silently.
+6. Test the encode side by round-tripping: decode → re-encode → decode and diff. Lossy re-encoding (JPEG), wrong quality/subsampling, or dropping alpha shows up here.
+7. Lock the fix by decoding into an explicit mode/bit-depth and asserting shape, dtype, and channel count.
+
+## Rules
+- Trust magic bytes over file extensions and over the server's Content-Type.
+- CMYK and indexed/palette images are the silent killers — convert to a known mode right after decode.
+- Preserve or explicitly convert ICC profiles; silently dropping one shifts colors without erroring.
+- Distinguish "won't decode" (format/corruption) from "decodes wrong" (depth/profile/mode) before fixing.
+- Re-encoding is often lossy — verify round-trips when the pipeline writes intermediates.