ada-agent 0.1.0

package/skills/image-memory/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: image-memory
+description: Diagnose image memory blowups and leaks — huge decoded bitmaps, uncleared caches, retained handles
+category: image
+---
+
+# Image Memory
+
+Reach for this when an image workload's RSS balloons or grows unbounded over time, risking OOM, even though files on disk are small.
+
+1. Reproduce and watch memory over a controlled run (process N images in a loop) with an RSS sampler or memory profiler; a steadily rising baseline means a leak, a single spike means one oversized decode.
+2. Remember decoded size != file size: a 2 MB JPEG decodes to `width × height × channels` bytes (a 6000×4000 RGBA image is ~96 MB raw). Log decoded dimensions of the largest inputs — one giant image can dwarf the file size.
+3. For leaks, find what retains buffers: unclosed image handles, appending decoded arrays to a list/cache that's never evicted, closures capturing big arrays, or thumbnails keeping the full-res parent alive.
+4. Inspect caches: an unbounded LRU/dict keyed by URL or path that stores decoded bitmaps grows forever. Add a size cap (by bytes, not count) and confirm eviction actually frees memory.
+5. Stream/downscale early: decode at a reduced size (JPEG DCT scaling, `draft`/thumbnail-on-decode) so you never materialize the full-res bitmap when you only need a small one.
+6. Free deterministically: close/`del` large arrays as soon as you're done, avoid keeping the whole batch in memory, and process in chunks rather than loading everything.
+7. Confirm the fix by re-running the loop and showing RSS is now flat (leak) or capped (blowup).
+
+## Rules
+- Reason in decoded pixels, not file bytes — that's where the memory actually goes.
+- Always close/dispose image handles; rely on context managers, not the garbage collector.
+- Caches of decoded images must be bounded by total bytes and must evict; verify freeing, don't assume it.
+- Decode/downscale to the size you need; don't materialize full-res bitmaps for thumbnails.
+- A flat RSS over a long loop is the only proof a leak is fixed.

package/skills/image-perf/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: image-perf
+description: Optimize image load/decode/processing throughput — find the bottleneck before changing code
+category: image
+---
+
+# Image Perf
+
+Reach for this when image loading, decoding, or processing is too slow and you need to raise throughput without guessing.
+
+1. Reproduce on a representative batch and measure end-to-end time plus a per-stage breakdown (download vs decode vs resize vs model/encode). Optimize the dominant stage — never the one you assume.
+2. Determine if you're I/O-bound or CPU-bound: high wait/low CPU means I/O (network/disk), saturated cores means decode/compute. The diagnosis dictates the fix (concurrency vs faster codec/SIMD vs fewer pixels).
+3. Decode at target size, not full res: use JPEG scaled decoding / draft mode / thumbnail-on-load so you never decode pixels you'll immediately throw away — often the single biggest win.
+4. Parallelize the right way: overlap I/O with threads/async (GIL released during native decode), and use processes for CPU-heavy pure-Python work. Batch GPU/model calls instead of one-at-a-time.
+5. Swap in faster building blocks where it matters: a SIMD/turbo JPEG decoder, a vectorized resize, or GPU decode/resize; pick the right interpolation (don't pay for bicubic when bilinear suffices).
+6. Cache and avoid rework: memoize decoded/resized results, reuse buffers instead of reallocating per image, and skip redundant color conversions or copies between stages.
+7. Re-measure after each change and keep only the ones that move the dominant stage; verify output is still correct (perf must not silently change pixels).
+
+## Rules
+- Profile first and per-stage — the bottleneck is rarely where intuition says.
+- Decoding fewer pixels (scaled decode/downsample-on-load) usually beats any post-decode optimization.
+- Classify I/O-bound vs CPU-bound before choosing threads, processes, or a faster codec.
+- Threads overlap native decode (GIL released); use processes only for CPU-bound pure-Python.
+- Verify pixels are unchanged after optimizing; faster but wrong is a regression.

package/skills/image-pipeline/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: image-pipeline
+description: Debug an image-processing pipeline where resize/crop/filter order or off-by-one errors corrupt output
+category: image
+---
+
+# Image Pipeline
+
+Reach for this when an image pipeline produces shifted, cropped-wrong, blurred, or subtly-off output and you suspect operation ordering or boundary math.
+
+1. Reproduce with one fixed input image and dump the intermediate after EVERY stage (write `stage_01.png`, `stage_02.png`, ...) so you can see exactly where it breaks.
+2. Make a synthetic test image with known features — a 1px grid, a colored corner marker, a centered crosshair — so any shift, flip, or crop is obvious by eye and by pixel coordinate.
+3. Check operation ORDER: resize-then-crop vs crop-then-resize give different results; sharpen/blur before vs after downscale changes aliasing. Confirm the order matches the spec, not just "looks plausible".
+4. Audit boundary math: half-open vs closed ranges (`[x0, x1)` vs `[x0, x1]`), center computed as `w/2` vs `(w-1)/2`, and whether crop boxes are inclusive. Off-by-one usually shows as a 1px black/duplicated edge row or column.
+5. Verify interpolation and rounding: integer truncation vs round, and whether coordinates are floored before sampling. Switch to nearest-neighbor temporarily to expose pure positional errors without resampling blur.
+6. Bisect by short-circuiting stages to identity (pass-through) one at a time until the output goes correct; the last stage you disabled owns the bug.
+7. After the fix, assert pixel-exact equality (or SSIM above threshold) against a golden image so the regression is locked.
+
+## Rules
+- Always inspect intermediates as files; never trust "the array shape looks right".
+- Resize changes coordinates — any crop/box/coordinate computed before a resize must be rescaled, not reused.
+- A 1px dark border or doubled edge line almost always means an inclusive/exclusive range mismatch.
+- Keep a deterministic synthetic fixture in the repo; floating photos make off-by-one invisible.
+- Watch for silent dimension swaps: `(w, h)` vs `(h, w)` between libraries flips the whole image without erroring.

package/skills/image-upload/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: image-upload
+description: Debug an image upload pipeline end to end — mime sniffing, EXIF strip, orientation, resize, size limits, storage
+category: visual-test
+---
+
+# Image Upload
+
+Reach for this when uploads fail, get rejected, come out rotated, or land corrupted in storage. Debug the pipeline stage by stage, not all at once.
+
+1. Capture the raw bytes the server actually received (log to a temp file before any processing) — most "corrupt image" bugs are a truncated or wrongly-encoded multipart body.
+2. Verify type by content, not extension: sniff the magic bytes (`file`, libmagic) and reject on the sniffed mime; a `.png` that's really a polyglot/SVG is a security bug.
+3. Check orientation: read the EXIF `Orientation` tag — if you strip EXIF without baking rotation into pixels first, portrait photos render sideways.
+4. Strip metadata after applying orientation: remove EXIF/GPS/ICC (or transcode) so you don't leak location and don't ship surprise color profiles.
+5. Enforce limits in order — byte size, then decoded dimensions (the decompression-bomb guard), then re-encode to a safe format at a capped resolution.
+6. Confirm the stored object: re-download it, check mime/dimensions/byte size, and render it to verify the round trip, not just the HTTP 200.
+
+## Rules
+- Never trust the client filename or `Content-Type`; sniff magic bytes server-side and decide from that.
+- Apply EXIF orientation to pixels BEFORE stripping metadata, or rotated images become permanently sideways.
+- Guard decoded dimensions, not just file size — a 2KB PNG can decode to gigapixels (decompression bomb / OOM).
+- Strip GPS/EXIF for privacy and re-encode through a trusted decoder to neutralize embedded payloads.
+- Verify by reading the object back from storage and rendering it; a 200 response doesn't prove the bytes are intact.
+- Test the ugly cases: HEIC, CMYK JPEG, animated GIF/WebP, SVG, and zero-byte uploads each break a different stage.

package/skills/infra-cost/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: infra-cost
+description: Estimate cloud spend and trim it without degrading reliability
+category: cloud
+---
+
+# Infra Cost
+
+Use this to put a number on what infrastructure costs (before or after deploy) and to find the cuts that save the most money for the least risk.
+
+1. Pull the actual bill broken down by service and tag (Cost Explorer / billing export) to see where money actually goes.
+2. For planned changes, estimate with a pricing tool (`infracost breakdown` on Terraform, or the provider calculator) before merging.
+3. Rank line items by spend and target the top few — compute, egress, and idle/oversized resources are usually the bulk.
+4. Right-size: match instance/DB sizes to observed utilization, delete unattached volumes/IPs/snapshots, and stop non-prod overnight.
+5. Commit to discounts where usage is stable (savings plans / reserved / committed-use); use spot/preemptible for fault-tolerant batch work.
+6. Cut data-transfer cost by keeping traffic in-region/in-AZ and fronting egress with a CDN.
+7. Add billing alerts/budgets and a `cost` tag so regressions are caught early.
+
+## Rules
+- Measure before cutting — right-size from real utilization metrics, not guesses, to avoid causing incidents.
+- Egress is often the silent top cost; check cross-AZ, cross-region, and internet-egress traffic specifically.
+- Reserved/committed pricing only pays off for steady baseline load — don't commit to spiky or shrinking workloads.
+- Tag resources for cost allocation; untagged spend is unaccountable and the first place waste hides.
+- Don't sacrifice redundancy (multi-AZ, backups) for marginal savings — a single outage can dwarf the cut.

package/skills/input-validation/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: input-validation
+description: Add validation and sanitization at trust boundaries where untrusted data enters
+category: security
+---
+
+# Input Validation
+
+Use this when adding or hardening checks on data crossing a trust boundary — request bodies, query params, headers, file uploads, env, or upstream API responses.
+
+1. Identify each trust boundary and the exact shape expected (type, range, length, format, allowed values) for every field.
+2. Validate at the boundary with a schema/validator (zod, pydantic, JSON Schema, Joi) — parse into typed values, reject anything that does not conform.
+3. Prefer allowlists over denylists: enumerate what is permitted (enum, regex anchored with `^...$`, numeric bounds) rather than blocking known-bad.
+4. Enforce size and depth limits (max length, max array size, max upload bytes, max JSON nesting) to blunt resource-exhaustion.
+5. Apply context-correct encoding/escaping at the sink (SQL params, HTML escape, shell arg arrays) — validation does not replace output encoding.
+6. Fail closed with a clear, non-leaky error; log the rejection for monitoring without echoing raw payloads.
+
+## Rules
+- Validate on the server even if the client already validates — the client is untrusted.
+- Normalize before validating (Unicode, path, case) so checks cannot be bypassed by alternate encodings.
+- Validate is not the same as sanitize: reject bad input where you can; only transform when you must.
+- Keep validation declarative and centralized so it is auditable, not scattered ad-hoc checks.
+- Anchor regexes and set timeouts/limits to avoid ReDoS on attacker-controlled strings.

package/skills/issue-template/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: issue-template
+description: Add GitHub issue and pull request templates to standardize reports and reviews
+category: compliance
+---
+
+# Issue Template
+
+Use when a repo gets low-quality or inconsistent issues/PRs, or when setting up a new project's contribution scaffolding.
+
+1. Create `.github/ISSUE_TEMPLATE/` with separate templates for bug reports and feature requests (YAML issue forms preferred, or Markdown with front-matter `name`/`about`/`labels`).
+2. In the bug template require: steps to reproduce, expected vs actual, version/environment, and logs — fields that make triage possible.
+3. In the feature template ask for: problem/motivation, proposed solution, and alternatives considered.
+4. Add `.github/ISSUE_TEMPLATE/config.yml` to set default labels and add `contact_links` (e.g. discussions, security policy) and decide whether to disable blank issues.
+5. Add `.github/PULL_REQUEST_TEMPLATE.md` with a summary, linked issue (`Closes #`), testing notes, and a checklist (tests pass, docs updated).
+6. Validate YAML syntax and confirm GitHub renders the picker by checking the repo's New Issue page.
+
+## Rules
+- Issue forms (`.yml`) need valid YAML and correct field `type` values, or GitHub silently falls back to blank issues — validate before merging.
+- Keep required fields minimal; over-long forms suppress reports.
+- Reference labels that already exist in the repo, or create them, so auto-labeling doesn't fail.
+- Don't route security reports through public issues — link to `SECURITY.md` in `config.yml` instead.
+- Place everything under `.github/`; templates elsewhere are ignored by GitHub.

package/skills/java-streams/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: java-streams
+description: Modernize imperative Java loops into Streams and replace null checks with Optional
+category: languages
+---
+
+# Java Streams
+
+Use this when refactoring verbose loop-and-accumulate Java into the Streams API, or replacing null-juggling with `Optional`, without changing behavior.
+
+1. Spot the loop shape: filter/map/reduce/collect patterns over a collection are the prime candidates; a loop with side effects or early break may be clearer left as-is.
+2. Translate the pipeline: `for` + `if` + `add` becomes `stream().filter(...).map(...).collect(toList())`; sums/counts become `mapToInt(...).sum()` or `collect(counting())`.
+3. Replace grouping/partitioning loops with `Collectors.groupingBy` / `toMap` / `partitioningBy` instead of manually populating maps.
+4. Convert methods that may return null to `Optional<T>`, and consume them with `map`/`filter`/`orElseGet`/`ifPresent` rather than `.get()` after an `isPresent` check.
+5. Keep lambdas small and side-effect-free; extract complex bodies to named methods or method references (`Type::method`) for readability.
+6. Run the existing test suite and confirm output equality, ordering, and null behavior are unchanged.
+
+## Rules
+- Streams are for transformation, not iteration with side effects — don't mutate external state inside `forEach`; use `collect` to build results.
+- Never call `Optional.get()` without a guarantee; prefer `orElse`, `orElseThrow`, or `ifPresentOrElse`. Don't use `Optional` for fields or method parameters.
+- Watch performance: a stream over a tiny list can be slower and noisier than a plain loop — don't convert for its own sake.
+- Preserve ordering semantics; `Collectors.toMap` throws on duplicate keys and `groupingBy` returns a `HashMap` (unordered) unless you supply a map factory.
+- Avoid stateful or order-dependent lambdas in parallel streams — they'll race; default to sequential unless you've proven a parallel win.

package/skills/k8s-manifest/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: k8s-manifest
+description: Write Kubernetes Deployment, Service, and Ingress manifests with sane defaults
+category: cloud
+---
+
+# K8s Manifest
+
+Use this to stand up a stateless workload on Kubernetes — a Deployment fronted by a Service and exposed via an Ingress — without missing the production-critical fields people forget.
+
+1. Write the `Deployment` with explicit `replicas`, matching `selector`/`template` labels, and a pinned image tag (never `:latest`).
+2. Set `resources.requests` and `resources.limits` for cpu and memory on every container.
+3. Add `livenessProbe` and `readinessProbe` (HTTP or exec) so rollouts and restarts behave.
+4. Write the `Service` (usually `ClusterIP`) selecting the same pod labels and naming the target port.
+5. Write the `Ingress` with host rules, a `pathType`, the backend Service, and TLS referencing a cert Secret.
+6. Validate with `kubectl apply --dry-run=server -f .` (or `kubeval`) and `kubectl diff` before applying.
+
+## Rules
+- Always run as non-root: set `securityContext` with `runAsNonRoot: true`, drop capabilities, and `readOnlyRootFilesystem` where possible.
+- Keep config in `ConfigMap`/`Secret` and inject via `envFrom`/`valueFrom` — no secrets baked into manifests or images.
+- Label consistently (`app`, `app.kubernetes.io/name`, `version`) so selectors and tooling work.
+- Set a `Namespace` explicitly or via kustomize; don't rely on `default`.
+- Prefer a rolling `strategy` with `maxUnavailable`/`maxSurge` tuned for your replica count.

package/skills/kotlin-coroutines/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: kotlin-coroutines
+description: Refactor Kotlin callback and threaded code into coroutines with structured concurrency
+category: languages
+---
+
+# Kotlin Coroutines
+
+Use this when replacing callback hell, `Thread`/`Executor` code, or RxJava chains with `suspend` functions and structured concurrency.
+
+1. Identify the async boundaries: callbacks, futures, `Thread`, or blocking calls — these become `suspend` functions or `withContext` blocks.
+2. Convert callback APIs with `suspendCancellableCoroutine`, resuming on success/failure and wiring `invokeOnCancellation` to release the underlying resource.
+3. Mark functions that suspend as `suspend fun`, and run blocking work on the right dispatcher (`withContext(Dispatchers.IO)` for I/O, `Default` for CPU).
+4. Launch concurrent work inside a scope (`coroutineScope { ... }` or a lifecycle-bound scope), using `async`/`await` for parallel results and `launch` for fire-and-forget within that scope.
+5. Replace streams of callbacks with `Flow` (`callbackFlow` for callback sources), and collect them in a scope that respects lifecycle.
+6. Verify cancellation and exceptions propagate: test that cancelling the scope stops the work, and that failures surface rather than being swallowed.
+
+## Rules
+- Never use `GlobalScope`; tie coroutines to a structured scope (`viewModelScope`, `coroutineScope`, or an explicit `CoroutineScope` you cancel) so they're cancelled with their owner.
+- Switch dispatchers with `withContext`, not by launching new coroutines, and never block a coroutine thread with `Thread.sleep` or blocking I/O on `Default`/`Main`.
+- Suspending functions must be main-safe — a `suspend fun` should be callable from any dispatcher and move blocking work off it internally.
+- Make cancellation cooperative: check `isActive`/`ensureActive()` in loops, and don't swallow `CancellationException` — rethrow it.
+- Prefer `coroutineScope`/`supervisorScope` over manual `Job` juggling; choose `supervisorScope` only when one child's failure should not cancel its siblings.

package/skills/landing-page/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: landing-page
+description: Build a responsive marketing landing page with a hero, value sections, social proof, and a clear conversion CTA.
+category: html
+---
+
+# Landing Page
+
+Use when building a single-purpose conversion page (product launch, signup, waitlist). The job is one clear action above the fold and a scannable narrative below it.
+
+1. Lay out the standard arc: hero (headline + subhead + primary CTA), problem/benefit sections, social proof, feature grid, FAQ, final CTA, footer.
+2. Write the hero with a benefit-driven headline (not the product name), a one-line subhead, and a single high-contrast CTA button; keep it readable on mobile without scrolling.
+3. Build the layout mobile-first with semantic landmarks (`<header> <main> <section> <footer>`) and CSS grid/flex; use `clamp()` for fluid type and spacing.
+4. Add a sticky or repeated CTA so the action is always reachable; make every CTA button visually identical and lead to the same target.
+5. Optimize for speed: inline critical CSS, lazy-load below-fold images (`loading="lazy"`), use responsive `<img srcset>` / modern formats (AVIF/WebP), defer non-critical JS.
+6. Layer in trust: real logos, testimonials with names/photos, concrete numbers; add SEO + OpenGraph meta tags (see `meta-tags` skill).
+7. Verify contrast (WCAG AA), keyboard focus states, and that the page works with JS disabled.
+
+## Rules
+- One primary conversion goal per page; secondary links should not compete with the main CTA.
+- Mobile-first: design the small viewport first, then enhance up with `min-width` media queries.
+- Don't ship a megabyte hero image — compress, size to display dimensions, and serve modern formats.
+- Use semantic headings in order (one `<h1>`, then `<h2>`/`<h3>`); don't pick heading levels by size.
+- Avoid render-blocking third-party widgets above the fold; they tank Largest Contentful Paint.

package/skills/laravel-controller/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: laravel-controller
+description: Scaffold a Laravel controller with routes, form request, and Eloquent model
+category: frameworks
+---
+
+# Laravel Controller
+
+Use to add a resource to a Laravel app — controller, routes, validation, and Eloquent model — following Laravel conventions.
+
+1. Generate the pieces: `php artisan make:model <Name> -mcr` (model + migration + resource controller) and a `make:request` for validation.
+2. Edit the migration columns, then `php artisan migrate`; set `$fillable`/`$casts` and relationships on the model.
+3. Register routes with `Route::resource('<plural>', <Name>Controller::class)` in `routes/web.php` or `routes/api.php`.
+4. Type-hint the Form Request in controller actions so validation runs automatically; use `$request->validated()`.
+5. Implement the resource actions, leaning on route-model binding (`<Name> $model`) and returning views or JSON/API resources.
+6. Run `php artisan serve`, confirm routes with `php artisan route:list`, and exercise CRUD.
+
+## Rules
+- Validate with Form Request classes, not inline `$request->validate` scattered everywhere; use `validated()` for mass assignment.
+- Set `$fillable` (or `$guarded`) on models to prevent mass-assignment vulnerabilities.
+- Use route-model binding instead of manual `find` + 404 checks.
+- Return API Resources (`->toResource()` / `JsonResource`) for API responses rather than raw models.
+- Keep controllers thin; push reusable logic into services or model methods, and use `php artisan` generators over hand-rolling files.

package/skills/lazy-load/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: lazy-load
+description: Defer or lazy-load heavy work so it only happens when actually needed
+category: performance
+---
+
+# Lazy Load
+
+Reach for this when startup, page load, or a request pays for work whose result is often unused.
+
+1. Identify eager work that's expensive and not always needed: big imports, asset bundles, DB connections, precomputed data, or off-screen UI.
+2. Move the work behind first use — lazy imports/`import()`, deferred initialization, computed-on-demand, or route/component code-splitting.
+3. For UI/data, load on interaction or visibility (intersection observer, pagination, infinite scroll) instead of all up front.
+4. Memoize the deferred result so the expensive work runs at most once, not on every access.
+5. Add a lightweight placeholder/loading state and guard against repeated concurrent initialization (race on first use).
+6. Measure the win — faster startup/first paint or smaller initial payload — and confirm deferred paths still work.
+
+## Rules
+- Lazy-loading trades first-use latency for faster startup; don't defer work that's needed immediately on the critical path.
+- Always cache the result of a lazy init so you don't recompute on every call.
+- Guard the first-use path against concurrent callers triggering the heavy work twice.
+- Don't over-split — too many tiny lazy chunks add round-trips and can be slower than one bundle.
+- Keep a visible loading/fallback state so deferred work doesn't look like a hang.

package/skills/license-check/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: license-check
+description: Audit dependency licenses for compliance and flag copyleft or unknown-license packages
+category: dependencies
+---
+
+# License Check
+
+Use before a release, an open-source publish, or a legal review to confirm every dependency's license is acceptable.
+
+1. Generate a full license inventory including transitive deps (`license-checker`, `pip-licenses`, `cargo-deny`, `cargo-about`, an SBOM tool).
+2. Define the allowlist/denylist for the project (e.g. allow MIT/BSD/Apache-2.0, deny GPL/AGPL for proprietary code).
+3. Flag anything copyleft, dual-licensed, custom, or reported as UNKNOWN/UNLICENSED for closer review.
+4. For each flagged package, find the actual obligation (attribution, source disclosure, network-use clause) before deciding.
+5. Resolve issues: replace the offending dependency, isolate it, or document the obligation and add required attribution/NOTICE.
+6. Wire the check into CI so a new non-compliant license fails the build instead of slipping in.
+
+## Rules
+- Audit the whole transitive tree, not just direct dependencies — risk usually hides deep.
+- "UNKNOWN" means missing metadata, not safe — chase down the real license manually.
+- Copyleft (GPL/AGPL) in a proprietary product is a blocker; LGPL and weak-copyleft have nuance — read the terms.
+- Permissive licenses still carry attribution duties; ship a NOTICE/THIRD-PARTY file to satisfy them.
+- Re-run on every dependency change; a transitive bump can silently introduce a new license.

package/skills/license-header/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: license-header
+description: Add SPDX or license headers to source files consistently across the repo
+category: compliance
+---
+
+# License Header
+
+Reach for this when source files lack a license/copyright notice, or when adopting SPDX identifiers for tooling and audits.
+
+1. Pick the license and confirm it matches the repo `LICENSE` file (e.g. MIT, Apache-2.0); use the exact SPDX identifier from spdx.org/licenses.
+2. Decide the header form: short SPDX tag (`SPDX-License-Identifier: MIT`) plus a copyright line, or the full notice if the license requires it (Apache-2.0, GPL).
+3. Map comment syntax per language (`//` for C/Go/JS/Rust, `#` for Python/shell/YAML, `<!-- -->` for HTML/XML) and place the header as the first lines, after a shebang or encoding line if present.
+4. Apply to all in-scope files, skipping vendored/`node_modules`/generated code and anything with a conflicting third-party header.
+5. Run a check that every target file starts with the header (grep the first lines) and fix misses.
+6. Add or update a CI step (e.g. `licensee`, `reuse lint`, or a grep guard) so new files must include the header.
+
+## Rules
+- Never overwrite or remove an existing third-party copyright line; preserve it and add yours below.
+- Keep the year/owner consistent with `LICENSE`; do not invent dates or change ownership.
+- Respect shebangs: header goes on line 2+ so `#!/usr/bin/env` stays line 1 and the file stays executable.
+- Prefer SPDX identifiers over pasting full license text in every file unless the license mandates the full notice.
+- Match the project's existing comment style and spacing; do not reflow surrounding code.

package/skills/lint-fix/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: lint-fix
+description: Run the project linter and fix the violations it reports
+category: review
+---
+
+# Lint Fix
+
+Use this to get a clean lint run — discover the project's linter, run it, and resolve every violation without suppressing problems you should actually fix.
+
+1. Identify the configured linter from the manifest/config (e.g. `eslint`, `ruff`, `clippy`, `golangci-lint`, `rubocop`) and its invocation script.
+2. Run the linter across the changed files (or the whole project if that's the convention) and capture the full list of violations.
+3. Apply the safe autofix mode first (`--fix`, `ruff check --fix`, `cargo clippy --fix`) and re-run to see what remains.
+4. Fix remaining violations by hand — address the underlying issue rather than reaching for an inline disable.
+5. Re-run the linter until it reports zero violations, then run the test suite to confirm fixes didn't change behavior.
+6. Commit the lint fixes separately from feature changes so the diff stays easy to review.
+
+## Rules
+- Fix the root cause; only use an inline disable when the rule is genuinely wrong here, with a comment explaining why.
+- Never loosen the shared lint config to silence a violation unless that's the explicit, agreed task.
+- Re-run after autofix — autofixers can introduce new violations or leave some untouched.
+- Keep autofix-only churn (formatting-adjacent) reviewable; don't bundle it with logic changes.
+- A green test run is required after fixes — a lint fix that breaks behavior isn't a fix.

package/skills/llm-cost/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: llm-cost
+description: Estimate and reduce the token cost of LLM calls without losing output quality
+category: agent-llm
+---
+
+# LLM Cost
+
+Use this to measure where tokens go in an LLM workload and cut spend by trimming inputs, caching, and right-sizing the model.
+
+1. Measure first: log input/output token counts per call (from the API response usage) and multiply by the model's per-token price to get real cost.
+2. Find the hot path — usually a large system prompt or context re-sent on every turn, or oversized tool results echoed back.
+3. Cache the stable prefix (system prompt, tool schemas, long shared context) with prompt caching so repeated tokens bill at the reduced rate.
+4. Shrink inputs: trim/summarize history, paginate or filter tool outputs, drop redundant few-shot examples, and strip boilerplate.
+5. Right-size the model: route easy/structured calls to a cheaper/smaller model and reserve the frontier model for hard reasoning.
+6. Cap `max_tokens` to the real need and re-measure cost-per-task to confirm the change actually saved money.
+
+## Rules
+- Optimize by measured cost, not vibes — get token counts before and after every change.
+- Output tokens usually cost several times more than input tokens; trimming verbose responses often beats trimming the prompt.
+- Put cacheable content at the front and keep it byte-stable; any change to the prefix busts the cache.
+- Summarizing history saves tokens but loses fidelity — keep recent turns verbatim and compress only older ones.
+- A cheaper model that needs retries or longer outputs can cost more than the expensive one; compare end-to-end, not per-token.

package/skills/lockfile-fix/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: lockfile-fix
+description: Resolve lockfile drift or merge conflicts by regenerating the lockfile from the manifest
+category: dependencies
+---
+
+# Lockfile Fix
+
+Reach for this when the lockfile is out of sync with the manifest or has merge-conflict markers after a rebase/merge.
+
+1. Identify the manager and its lockfile (`package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`, `Cargo.lock`, `poetry.lock`, `uv.lock`).
+2. For a merge conflict, take the manifest's resolution first — accept both sides of the manifest, then discard the conflicted lockfile body.
+3. Regenerate from the manifest: `npm install`, `pnpm install`, `yarn install`, `cargo generate-lockfile`, `poetry lock`, `uv lock` — never resolve lockfile markers by hand.
+4. Verify the manifest itself merged cleanly and reflects the intended versions before regenerating.
+5. Reinstall clean (`npm ci`) to prove the new lockfile resolves and the tree installs.
+6. Commit the regenerated lockfile alongside the manifest and run tests.
+
+## Rules
+- Never hand-edit conflict markers in a lockfile; delete the conflicted content and regenerate.
+- Resolve the manifest first — the lockfile is derived, not authoritative.
+- Use the same package-manager version as the team/CI; a different version can rewrite the whole lockfile.
+- Run a clean install (`ci`/frozen) afterward to catch an unsatisfiable resolution early.
+- Keep the regenerated lockfile and manifest in one commit so the pair stays consistent.

package/skills/low-power/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: low-power
+description: Reduce firmware power draw with sleep modes, clock gating, and peripheral management
+category: gamedev
+---
+
+# Low Power
+
+Use when a battery-powered device must extend run time: cut active current, sleep aggressively, and wake only on events.
+
+1. Measure baseline current first (bench supply or coulomb counter) so every change is verified against real numbers.
+2. Restructure to event-driven: do work, then enter the deepest sleep mode that still allows the needed wake source.
+3. Wake from interrupts/RTC/peripheral events rather than polling; remove busy-wait and fixed delay loops.
+4. Gate clocks and power down unused peripherals, and configure idle GPIOs (pull or drive) to stop leakage current.
+5. Lower the active clock to the slowest rate that meets the deadline; run fast-then-sleep ("race to idle") when bursty.
+6. Re-measure after each change and check average current over a full duty cycle, not just the peak.
+
+## Rules
+- Floating input pins leak current — set every unused GPIO to a defined pull or output level before sleeping.
+- Confirm your chosen sleep mode retains the RAM/registers and wake sources you actually need before relying on it.
+- Disable or reconfigure debug/SWD, brown-out, and watchdog peripherals that quietly keep current high in sleep.
+- Average current over the whole duty cycle drives battery life; a low sleep current is moot if wakeups are too frequent.
+- Always re-measure on hardware; datasheet sleep figures assume an ideal configuration you probably have not matched.

package/skills/makefile/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: makefile
+description: Generate a Makefile or task runner exposing common project commands behind short aliases
+category: ci-cd
+---
+
+# Makefile
+
+Use when a project's everyday commands are long or scattered and you want one discoverable entrypoint (`make test`, `make run`).
+
+1. Collect the real commands developers run: install, build, lint, test, format, run, clean.
+2. Create a target per command with a short, conventional name; have each shell out to the actual tool.
+3. Declare `.PHONY` for every target that isn't a file, so they always run.
+4. Add a default `help` target (self-documenting via `##` comments) so `make` lists what's available.
+5. Compose targets where it helps (`ci: lint test build`, `check: lint test`) to mirror the pipeline.
+6. Run each target to confirm it works; reference the same targets from CI so local and CI commands stay identical.
+
+## Rules
+- Recipe lines must be tab-indented, not spaces — the classic Makefile footgun.
+- Mark non-file targets `.PHONY` or stale files silently skip them.
+- Keep targets thin wrappers over the real tools; don't reimplement logic in make.
+- Have CI call the same `make` targets so there's one source of truth for commands.
+- On Windows/non-make environments prefer a `justfile` or npm scripts instead of forcing make.

package/skills/man-page/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: man-page
+description: Write a man page / CLI --help reference with synopsis, options, examples, and exit codes.
+category: docs
+---
+
+# Man Page
+
+Use when a CLI needs a precise reference — the canonical `--help` output and/or a `man` page that documents every flag, argument, and exit code.
+
+1. Follow the standard section order: NAME, SYNOPSIS, DESCRIPTION, OPTIONS, EXAMPLES, EXIT STATUS, ENVIRONMENT, SEE ALSO.
+2. Write the SYNOPSIS with convention: `[ ]` optional, `<>` placeholders, `...` repeatable, `|` mutually exclusive.
+3. Document every option with both short and long forms (`-v, --verbose`), its argument, default, and one-line effect.
+4. Add an EXAMPLES section with real, copy-pasteable invocations covering the common cases and one advanced case.
+5. List exit codes and their meaning (0 success, non-zero failures) so scripts can branch on them.
+6. Keep the in-binary `--help` and the man page consistent — ideally generate one from the other (e.g. from the arg parser).
+7. Author the man page in Markdown and convert with `pandoc`/`ronn`/`scdoc` rather than hand-writing roff.
+
+## Rules
+- SYNOPSIS notation is a contract: optional/required/repeatable must match the parser's actual behavior.
+- Document defaults and units explicitly (`--timeout <sec>` default `30`); ambiguity here causes real bugs.
+- Examples are mandatory and must run as written — they're the section people actually read.
+- Don't hand-edit roff; generate the man page from a readable source.
+- Keep `--help` terse and the man page complete; cross-reference rather than duplicate.

package/skills/mcp-server/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: mcp-server
+description: Scaffold an MCP server that exposes tools over stdio or HTTP for an LLM agent to call
+category: agent-llm
+---
+
+# MCP Server
+
+Reach for this when you need to expose local capabilities (files, APIs, DB queries) to an agent via the Model Context Protocol instead of hand-rolling a custom integration.
+
+1. Pick a transport: stdio for local/CLI use (the default, simplest), or HTTP/SSE for a remote or multi-client server.
+2. Init the project and add the MCP SDK (`@modelcontextprotocol/sdk` for TS, `mcp` for Python); create a server with a name and version.
+3. Register each tool with a unique name, a one-line description, and a JSON-Schema (or zod/pydantic) input schema — keep inputs flat and typed.
+4. Implement each tool handler to do the work, then return content as a list of typed parts (text/json); never return raw exceptions.
+5. Wire the transport and start the loop (stdio: read/write over stdin/stdout; HTTP: bind a port and mount the session handler).
+6. Register the server in the client config (command + args for stdio, URL for HTTP) and smoke-test that tools list and a sample call both succeed.
+
+## Rules
+- For stdio, NEVER write logs or prints to stdout — it corrupts the protocol stream; log to stderr or a file.
+- Tool names must be stable and unique; renaming one breaks any agent that hardcoded it.
+- Validate and sanitize every input inside the handler; schema validation is a hint, not a security boundary.
+- Return structured errors (a result with `isError: true` and a message) so the agent can recover, rather than throwing.
+- Keep each tool single-purpose and side-effect-explicit; mark destructive tools clearly in the description.

package/skills/memory-leak/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: memory-leak
+description: Find and fix a memory leak by measuring growth, capturing heaps, and tracing retained references
+category: debugging
+---
+
+# Memory Leak
+
+Use when memory climbs over time and doesn't come back down — RSS growth, OOM kills, GC thrashing, or a process that gets slower the longer it runs. The goal is to find what's still being referenced after it should be free.
+
+1. Confirm it's a real leak: drive a repeating workload and watch memory across cycles — a leak grows monotonically and never returns to baseline after GC.
+2. Take a heap snapshot at a steady state, run more cycles, take another, and diff them to see which object types grew.
+3. Pick the growing type and inspect its retainer/retention path — find what's holding the reference that should have been released.
+4. Trace that reference to the code: usually an unbounded cache/array, an event listener never removed, a closure capturing large state, or a timer never cleared.
+5. Break the retention — remove the listener, bound or evict the cache, clear the timer, drop the closure capture — and re-run the cycle test.
+6. Verify memory now returns to baseline across many cycles and stays flat under sustained load.
+
+## Rules
+- Force/allow GC before measuring, or you'll chase garbage that just hadn't been collected yet.
+- Compare snapshots at the same point in the cycle — drift in workload looks like a leak when it isn't.
+- The biggest object isn't the leak; the one that keeps growing across snapshots is.
+- Common culprits: event emitters, global/module-level collections, caches without eviction, subscriptions, and detached DOM nodes.
+- Fix retention, then prove it with a long soak run — a single short run won't show a slow leak.

package/skills/mermaid-diagram/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: mermaid-diagram
+description: Add Mermaid flowchart, sequence, or ER diagrams to Markdown docs that render on GitHub and most doc sites.
+category: docs
+---
+
+# Mermaid Diagram
+
+Use when a diagram belongs *in* the doc and should stay diffable in git — Mermaid renders natively on GitHub, GitLab, MkDocs Material, and Docusaurus.
+
+1. Choose the diagram type by intent: `flowchart` for process/decisions, `sequenceDiagram` for interactions over time, `erDiagram` for data models, `stateDiagram-v2` for state machines.
+2. Open a fenced block tagged ```` ```mermaid ```` and declare the type and direction on the first line (e.g. `flowchart TD`).
+3. Define nodes with stable IDs and human labels (`A[Load config]`), then edges (`A --> B`); use `-->|label|` for edge text.
+4. Keep each diagram to one idea (~5-15 nodes); split large flows into multiple diagrams rather than one unreadable graph.
+5. Verify rendering — paste into the Mermaid Live Editor (mermaid.live) or your doc preview; a single syntax error blanks the whole block.
+6. For doc sites, confirm the Mermaid plugin is enabled (MkDocs: `pymdownx.superfences` custom fence; Docusaurus: `@docusaurus/theme-mermaid`).
+
+## Rules
+- IDs are code, labels are prose: never put spaces or punctuation in a bare node ID — wrap the label in `[]`, `()`, or `{}`.
+- Escape special characters in labels with quotes: `A["Retry (max 3)"]`.
+- Pick `TD`/`LR` deliberately; sequence diagrams flow top-down regardless.
+- Don't embed huge diagrams inline — if it needs zoom/pan, link to a standalone page.
+- Comment intent with `%% ...` so the next editor knows what the diagram is asserting.