ada-agent 0.1.0

package/skills/perf-profile/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: perf-profile
+description: Profile code to find the actual hot path before optimizing, then verify the speedup with numbers
+category: debugging
+---
+
+# Perf Profile
+
+Use when something is slow and you need to know *where* the time goes before touching code. Intuition about bottlenecks is usually wrong — measure first, optimize the proven hot path, measure again.
+
+1. Establish a baseline: a repeatable workload and a number (wall time, p95 latency, throughput) you can compare against.
+2. Run a profiler (CPU sampling, or a flame graph) under that workload — don't guess from reading the code.
+3. Read the profile for the hot path: the functions with the highest self time (their own work) vs cumulative time (work below them).
+4. Identify the dominant cost — tight CPU loop, repeated allocation, N+1 queries, blocking I/O, lock contention, or serialization.
+5. Apply one targeted optimization (algorithmic win, caching, batching, removing redundant work) and re-profile.
+6. Compare against the baseline number to confirm a real improvement, and check you didn't regress correctness.
+
+## Rules
+- Optimize self time, not cumulative time — a function high in cumulative time may just be calling the real culprit.
+- Profile a realistic workload; microbenchmarks lie about cache, allocation, and I/O behavior.
+- A better algorithm (O(n²)→O(n)) usually beats micro-optimizing the inner loop — check complexity first.
+- Don't optimize anything the profile doesn't flag; premature tuning adds complexity for no measured gain.
+- Warm up the runtime (JIT, caches) before measuring, and run enough iterations to beat noise.

package/skills/physics/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: physics
+description: Add basic collision detection and response for 2D/3D game entities
+category: gamedev
+---
+
+# Physics
+
+Reach for this to add movement, collision detection, and resolution without pulling in a full physics engine.
+
+1. Choose collider shapes (AABB, circle/sphere, capsule) that fit your entities; prefer the simplest that works.
+2. Integrate motion with semi-implicit Euler: `velocity += accel * dt; position += velocity * dt`.
+3. Broad-phase first (spatial grid or sweep) to cull pairs, then narrow-phase exact overlap tests on survivors.
+4. On overlap, compute penetration depth and a contact normal; separate by pushing along the normal.
+5. Resolve velocity along the normal using restitution (bounce) and friction along the tangent.
+6. Run collision after integration each fixed step; iterate resolution a few times for stacked contacts.
+
+## Rules
+- Run physics on the fixed timestep, not the render delta, so behavior is stable and reproducible.
+- Use swept/continuous tests for fast objects to avoid tunneling through thin walls.
+- Separate position correction from velocity response; resolving only velocity leaves objects sinking.
+- Add a small slop/epsilon and skip resolving tiny penetrations to stop jitter at rest.
+- Keep colliders convex; concave shapes need decomposition or you get caught-edge artifacts.

package/skills/pitch-deck/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: pitch-deck
+description: Build a startup/investor pitch deck covering problem, solution, market, traction, and the ask.
+category: pptx
+---
+
+# Pitch Deck
+
+Use when the user needs an investor or fundraising pitch deck. Follow the canonical 10-12 slide arc and keep every slide skimmable in seconds.
+
+1. Gather the essentials: one-line value prop, target customer, business model, traction numbers, team, and the funding ask.
+2. Order the slides: Title → Problem → Solution → Product → Market (TAM/SAM/SOM) → Business Model → Traction → Competition → Team → Ask/Use of Funds (optional: Roadmap, Vision close).
+3. Draft one sharp headline per slide that states the takeaway, then support it with at most 3 bullets or one visual.
+4. Make Traction and Market concrete with real numbers and charts (revenue, growth, users); route data viz through slide-charts.
+5. State the Ask explicitly: amount raising, round type, and use of funds breakdown.
+6. Build the file via the pptx-deck skill (python-pptx) or pptx-from-markdown, then apply a clean branded theme (pptx-template).
+
+## Rules
+- Lead each slide with the conclusion; investors skim, they don't read.
+- Numbers over adjectives — "$40k MRR, 22% MoM" beats "rapid growth".
+- One message per slide; if a slide needs two charts to explain, split it.
+- TAM/SAM/SOM must be bottoms-up and defensible, not a giant top-down number.
+- Keep it to ~12 slides; push deep detail (financial model, full metrics) into an appendix.
+- Never invent traction, customers, or financials — flag any gaps for the user to fill.

package/skills/pixel-diff/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: pixel-diff
+description: Diff two images and localize exactly which pixels, regions, and channels differ between them
+category: visual-test
+---
+
+# Pixel Diff
+
+Reach for this when you have two images that should match (expected vs actual, before vs after) and need to know precisely where and how much they differ.
+
+1. Normalize first: confirm both images share dimensions, color space, and bit depth — resize/convert mismatches before diffing or every pixel "differs".
+2. Run a per-pixel diff (`pixelmatch`, ImageMagick `compare -metric AE`, or Pillow `ImageChops.difference`) and emit a diff image that highlights changed pixels.
+3. Read the metrics: total differing pixels, max per-pixel delta, and the bounding box of the changed region — this localizes the problem to a corner/widget.
+4. If the whole image lights up, suspect a global cause: gamma/color-profile shift, anti-aliasing, DPR mismatch, or a 1px offset — not a content change.
+5. Zoom the diff region and inspect channels separately (R/G/B/A); an alpha-only diff means transparency/compositing, a uniform RGB shift means color management.
+6. Set an anti-aliasing-aware tolerance so AA fringes don't dominate the real signal.
+
+## Rules
+- Dimension/format mismatch is the #1 false positive — always assert equal size and color space before comparing.
+- A diff that's a faint copy of the whole image is almost always a 1px shift or AA difference, not a content bug.
+- Output a *highlighted* diff image, not just a number; "1.2% pixels differ" tells you nothing about where.
+- Watch alpha: many tools diff RGB only and miss transparency bugs — diff all four channels.
+- Use a perceptual/AA-aware threshold for screenshots; use exact (AE=0) only for synthetic, pixel-perfect images.

package/skills/ponytail/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: ponytail
+description: Force the laziest solution that actually works — YAGNI, stdlib before deps, shortest diff.
+category: meta
+---
+
+# Ponytail
+
+Channel a lazy senior developer. Lazy means **efficient, not careless**. The best code is the code
+never written. You've seen every over-engineered codebase and been paged at 3am for one.
+
+## The ladder
+
+Stop at the first rung that holds:
+
+1. **Does this need to exist at all?** Speculative need → skip it, say so in one line. (YAGNI)
+2. **Stdlib does it?** Use it.
+3. **Native platform feature covers it?** `<input type="date">` over a picker lib, CSS over JS, a DB constraint over app code.
+4. **An already-installed dependency solves it?** Use it. Never add a new dep for what a few lines do.
+5. **Can it be one line?** One line.
+6. **Only then:** the minimum code that works.
+
+Two rungs work → take the higher one and move on. The first lazy solution that works is the right one.
+
+## Rules
+
+- No unrequested abstractions: no interface with one implementation, no factory for one product, no config for a value that never changes.
+- No boilerplate or scaffolding "for later" — later can scaffold for itself.
+- Deletion over addition. Boring over clever (clever is what someone decodes at 3am).
+- Fewest files. Shortest working diff wins.
+- Mark deliberate simplifications with a `ponytail:` comment that names the ceiling and the upgrade path — e.g. `// ponytail: global lock, per-account locks if throughput matters`.
+
+## When NOT to be lazy
+
+Never simplify away: input validation at trust boundaries, error handling that prevents data loss,
+security, accessibility basics, or anything explicitly requested. If the user insists on the full
+version, build it — don't re-argue. Hardware needs its calibration knob; the physical world needs
+tuning a minimal model can't see.
+
+Non-trivial logic (a branch, loop, parser, money/security path) leaves ONE runnable check behind —
+the smallest thing that fails if the logic breaks. Trivial one-liners need no test.
+
+## Output
+
+Code first. Then at most three short lines: what was skipped, when to add it. If the explanation is
+longer than the code, delete the explanation. Pattern: `[code] → skipped: [X], add when [Y].`

package/skills/postmortem/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: postmortem
+description: Write a blameless incident postmortem with timeline, root cause, and preventive action items
+category: productivity
+---
+
+# Postmortem
+
+Reach for this after an incident, outage, or serious bug to produce a blameless write-up that explains what happened and prevents a recurrence — focused on the system that allowed the failure, never on who pushed the button.
+
+1. Write a one-paragraph summary: what broke, who/what was affected, the user-visible impact, and the duration.
+2. Build a timeline from evidence — deploy logs, alerts, chat, commits — with timestamps from first symptom through detection, mitigation, and full resolution.
+3. Find the root cause by asking "why" past the trigger until you reach a systemic gap (missing test, absent alert, unguarded assumption), not a person.
+4. Separate the trigger (what set it off) from the root cause (why it could happen at all) and from the impact.
+5. Capture detection and response: how long to notice, how long to mitigate, and what made each faster or slower.
+6. List preventive action items — each with an owner and due date — covering prevention, faster detection, and quicker mitigation.
+
+## Rules
+- Blameless, always: "the deploy lacked a rollback step", never "X forgot to roll back".
+- Anchor the timeline in real timestamps and sources; reconstruct from logs, do not guess.
+- Distinguish trigger vs root cause vs impact — conflating them produces shallow fixes.
+- Every action item gets an owner and date; track them to closure or they were theater.
+- Capture time-to-detect and time-to-mitigate explicitly — they are often the biggest lever for the next incident.
+- Write it while memory is fresh; a postmortem a week late loses the detail that matters.

package/skills/pptx-deck/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: pptx-deck
+description: Generate a .pptx slide deck programmatically with python-pptx from a content outline.
+category: pptx
+---
+
+# PPTX Deck
+
+Reach for this when the user wants a real, editable PowerPoint file (not HTML or PDF) built from a content outline or data.
+
+1. Confirm the deck's purpose, audience, and approximate slide count; sketch the slide order first (see slide-outline) before writing code.
+2. `pip install python-pptx`; start a `Presentation()` (or open a template `.pptx` to inherit its theme).
+3. Pick layouts from `prs.slide_layouts` (0=title, 1=title+content, 5=title-only, 6=blank); add slides with `prs.slides.add_slide(layout)`.
+4. Fill `slide.shapes.title` and body placeholders; for free placement use `add_textbox(left, top, width, height)` with `Inches(...)` from `pptx.util`.
+5. Add images via `slide.shapes.add_picture`, and route charts/tables through the slide-charts skill rather than hand-rolling them.
+6. Set consistent fonts/sizes/colors on `run.font` (`size=Pt(...)`, `color.rgb=RGBColor(...)`); save with `prs.save("deck.pptx")` and verify it opens.
+
+## Rules
+- One idea per slide; keep body text to 3-6 short bullets, never paragraphs.
+- Use `Inches()`/`Pt()`/`Emu()` from `pptx.util` — never raw integers for positions or sizes.
+- Reuse a single helper for adding slides so spacing, fonts, and margins stay uniform.
+- Default 16:9 (`prs.slide_width = Inches(13.333)`, `prs.slide_height = Inches(7.5)`) unless told otherwise.
+- Don't fabricate logos, photos, or data; leave a labeled placeholder shape when an asset is missing.

package/skills/pptx-export/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: pptx-export
+description: Export a .pptx deck to PDF or per-slide images for sharing, printing, or web embedding.
+category: pptx
+---
+
+# PPTX Export
+
+Use when a finished deck needs a non-editable, portable format — a PDF handout, or PNG/JPG images of each slide for the web or docs.
+
+1. Confirm the target: PDF (handout/print) or per-slide images (web, thumbnails, social), and the resolution needed.
+2. Prefer LibreOffice headless for fidelity: `soffice --headless --convert-to pdf deck.pptx` (works cross-platform, no PowerPoint).
+3. For images, convert to PDF first, then rasterize pages with `pdftoppm -png deck.pdf slide` or ImageMagick/`pdf2image`.
+4. On Windows with PowerPoint installed, COM automation (`win32com.client`) can export PDF and PNG natively with best font fidelity.
+5. For multi-up handouts, use the PDF export's notes/handout layout or print N-slides-per-page.
+6. Open the output and spot-check fonts, chart rendering, and image quality before delivering.
+
+## Rules
+- LibreOffice is the most portable converter; results can differ slightly from PowerPoint on fonts and effects — verify visually.
+- Ensure fonts used in the deck are installed on the converting machine, or text reflows and substitutes.
+- Choose DPI by use: ~96-150 for screen, 300 for print.
+- Embed fonts in the source deck where possible so exports stay faithful.
+- Keep the original `.pptx` as the source of truth; treat PDF/images as disposable artifacts.

package/skills/pptx-from-markdown/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: pptx-from-markdown
+description: Convert a markdown document into slides using Marp or reveal.js, exporting to PPTX or HTML.
+category: pptx
+---
+
+# PPTX From Markdown
+
+Use when the source is markdown (or the user prefers writing slides as text) and wants fast, version-controllable slides. Marp is the quickest path to a `.pptx`; reveal.js gives richer interactive HTML.
+
+1. Choose the tool: Marp (`@marp-team/marp-cli`) for clean PPTX/PDF export, reveal.js for animated browser decks.
+2. Write the markdown: separate slides with `---`, use `#`/`##` for titles and `-` bullets; one idea per slide.
+3. Add a Marp front-matter block (`marp: true`, `theme:`, `paginate: true`) or a reveal.js config to set the look.
+4. Use per-slide directives for layout (`<!-- _class: lead -->`, background images via `![bg](img.png)`) where needed.
+5. Render: `marp deck.md -o deck.pptx` (or `--pdf`/`--html`), or serve reveal.js and export via its print/PDF route.
+6. Open the output and verify slide breaks, images, and code blocks survived the conversion.
+
+## Rules
+- Exactly one `---` between slides; a stray rule splits or merges slides unexpectedly.
+- Keep heading levels consistent — Marp maps them to title vs. body styling.
+- Reference images by relative path and keep them beside the markdown so export resolves them.
+- Marp PPTX export rasterizes some styling; if the user needs fully editable native shapes, use pptx-deck instead.
+- Set the theme once in front-matter rather than styling slides individually.

package/skills/pptx-template/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: pptx-template
+description: Apply a branded template/theme (fonts, colors, logo, master slides) to a PowerPoint deck.
+category: pptx
+---
+
+# PPTX Template
+
+Use when a deck needs to match brand guidelines, or when a client supplies a `.potx`/`.pptx` template the content must adopt.
+
+1. Obtain the brand inputs: a template file (`.potx`/`.pptx`), or the palette (hex codes), fonts, and logo to build one.
+2. When a template exists, open it directly with `Presentation("template.pptx")` so new slides inherit its layouts and theme.
+3. Map your content slides to the template's `slide_layouts` by index/name — use the layouts it defines, not generic blank slides.
+4. With no template, define a small theme dict (primary/secondary/accent colors, title/body fonts, sizes) and apply it through one styling helper.
+5. Place the logo and any footer/page-number consistently via the slide master or a repeated helper, not per-slide by hand.
+6. Render a few representative slides and check contrast, font fallback, and logo placement before applying to the full deck.
+
+## Rules
+- Prefer inheriting an existing template file over reconstructing a theme by hand.
+- Centralize colors and fonts in one place so a rebrand is a single edit.
+- Ensure text/background contrast meets readability (aim for WCAG AA on body text).
+- Embed or confirm brand fonts are installed; otherwise pick a close, available fallback and note it.
+- Keep the logo at consistent size/position and don't distort its aspect ratio.
+- Don't let template decoration crowd content — whitespace is part of the brand.

package/skills/pr-review/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: pr-review
+description: Review a GitHub PR with gh, summarize the change, and suggest concrete improvements
+category: git
+---
+
+# PR Review
+
+Reach for this when asked to review a GitHub pull request: understand the intent, read the diff, and leave actionable feedback rather than a rubber stamp.
+
+1. Fetch context: `gh pr view <num>` for title/body/checks, and `gh pr view <num> --comments` to read existing discussion so you don't repeat points.
+2. Read the actual change: `gh pr diff <num>` (add `--patch | less` for large diffs). Note the base branch and files touched.
+3. Check CI/state: `gh pr checks <num>` — flag failing checks before reviewing logic, since they may make the review moot.
+4. Walk the diff hunk by hunk: trace data flow, look for missing error handling, untested edge cases, security/auth gaps, and behavior that contradicts the PR description.
+5. Separate findings into blocking (correctness, security, breaking) vs non-blocking (style, naming, nits) so the author knows what must change.
+6. Summarize: one-paragraph overview of what the PR does, then a bulleted list of suggestions, each anchored to `file:line`.
+7. If asked to post, use `gh pr review <num> --comment -b "..."` or `--approve`/`--request-changes`; for line-specific notes use `gh pr comment` or the review API.
+
+## Rules
+- Review the diff, not your assumptions — pull the branch (`gh pr checkout <num>`) if you need to run or grep the code.
+- Quote `file:line` for every concrete suggestion; vague feedback like "improve error handling" is not actionable.
+- Don't approve a PR with failing required checks or unresolved blocking comments.
+- Keep tone constructive and specific; flag, don't rewrite, unless the author asked for code.
+- Respect scope: note out-of-scope issues separately rather than blocking the PR on them.

package/skills/precommit/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: precommit
+description: Set up pre-commit hooks that lint and format staged files before each commit
+category: ci-cd
+---
+
+# Pre-commit
+
+Reach for this to catch lint/format issues locally before they ever reach CI, keeping commits clean.
+
+1. Pick the mechanism that fits the stack: `pre-commit` (framework, polyglot) or a JS-native combo of `husky` + `lint-staged`.
+2. Add the config (`.pre-commit-config.yaml` or `package.json` `lint-staged` block) listing hooks: formatter, linter, and cheap checks.
+3. Scope hooks to staged files only and run the same tools CI uses, so local and CI verdicts agree.
+4. Install the git hook (`pre-commit install` or husky's `prepare` script) so it runs automatically on `git commit`.
+5. Run the hooks across the whole repo once (`pre-commit run --all-files`) to surface and fix existing violations.
+6. Document the one-line setup so a fresh clone installs hooks during `npm install` / bootstrap.
+
+## Rules
+- Keep hooks fast — only lint/format staged files; push heavy test suites to CI.
+- Pin hook/tool versions so every developer runs identical checks.
+- Make hooks fixable: prefer auto-formatters that re-stage, and give clear failure messages.
+- Pre-commit is a convenience, not a gate — CI must still enforce the same checks (`--no-verify` exists).
+- Ensure hooks install on clone (husky `prepare`) so they aren't silently skipped.

package/skills/pricing-page/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: pricing-page
+description: Design a clear, persuasive pricing page that steers users to the right plan and reduces decision anxiety.
+category: ui-design
+---
+
+# Pricing Page
+
+Reach for this when designing or fixing a pricing page — clarity converts, and confusion kills more deals than price does.
+
+1. Limit to 3–4 tiers and anchor with one recommended plan, visually elevated (border accent, "Most popular" badge, slight scale) — the decoy/anchor frames the others.
+2. Make the price unmissable: large tabular number, `/mo` qualifier muted beside it, and a monthly↔annual toggle that shows the savings ("2 months free") to nudge annual.
+3. Build a feature comparison that scales by inclusion, not repetition: list the delta each tier adds, use a clean check matrix for full comparison, and put the highest-value differentiator first.
+4. Give each tier one CTA with consistent verbs; the recommended plan gets the solid primary button, others get quieter ghost buttons. Keep button widths and card heights aligned on the grid.
+5. Defuse risk near the buttons: "no credit card", "cancel anytime", money-back guarantee, and a short FAQ for the predictable objections (overage, downgrades, taxes).
+6. Polish hierarchy and motion: 8px rhythm, equal-height cards, a subtle hover lift on the recommended tier, and `prefers-reduced-motion` respected.
+
+## Rules
+- One recommended plan, clearly signaled — an undifferentiated row of equal cards makes users bounce.
+- Show the real total: surface annual-vs-monthly math and any per-seat/usage cost; hidden pricing erodes trust fast.
+- CTA verbs match commitment ("Start free trial" vs "Contact sales"), never a generic "Submit" everywhere.
+- Lead each tier with value/outcomes, not a feature dump; the comparison table is for buyers who already want detail.
+- Keep contrast and legibility on badges/accents ≥4.5:1 — the "popular" highlight must not sacrifice readability.

package/skills/project-overview/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: project-overview
+description: Describe a project well — purpose, architecture, layout, and how to run it — for a README or newcomer.
+category: docs
+---
+
+# Project Overview
+
+Use to describe a project clearly: what it is, why, how it's built, and how to run it.
+
+1. Explore: read the README/manifest (`package.json`, `pyproject.toml`, `go.mod`), the entry points, the top-level directory tree, and recent git history to infer purpose and what's active.
+2. State the purpose in 1-2 sentences — what it does and who/what it's for — without jargon.
+3. Describe the architecture: the main components, how they fit together, and the one or two design decisions that shape it (link an architecture diagram rather than re-prosing it — see the `architecture-diagram` skill).
+4. Map the layout: a short tree of the key directories/files, one line of role each.
+5. Give the essentials: install, run, test, and configuration (env vars), with copy-pasteable commands.
+6. Write it where it belongs (README or `docs/`), honest about what's done vs. planned.
+
+## Rules
+- Accurate over impressive — describe what the code actually does; verify the commands run.
+- Lead with purpose: a reader should get "what & why" in the first three lines.
+- Link the diagram, don't duplicate it in words.
+- Cut boilerplate — every line should help someone use or extend the project.

package/skills/prompt-template/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: prompt-template
+description: Design and refine a structured, testable LLM prompt template
+category: data-ml
+---
+
+# Prompt Template
+
+Use when building a reusable prompt for a production task (extraction, classification, generation) where output structure and reliability matter.
+
+1. Write a clear role and task statement, then specify the exact output format (JSON schema, fields, or enum) the caller will parse.
+2. Separate static instructions from dynamic inputs with explicit delimiters or template variables so user content can't override instructions.
+3. Add 2-3 few-shot examples covering the tricky and edge cases, including how to handle missing or ambiguous input.
+4. State failure behavior explicitly: what to output when the answer is unknown, input is empty, or it can't comply.
+5. Test on a labeled set of inputs, read the failures, and iterate the wording — change one thing at a time.
+6. Version the template and pin the model; treat prompt edits like code changes with before/after eval scores.
+
+## Rules
+- Specify output format precisely and validate/parse it on the way out; don't trust prose to be machine-readable.
+- Keep instructions and untrusted input clearly separated to reduce prompt injection.
+- Few-shot examples should target real failure modes, not just happy-path repetition.
+- Change one variable per iteration and measure on a fixed set — vibes don't catch regressions.
+- Pin the model and version the prompt; the same template can behave differently across models.

package/skills/property-test/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: property-test
+description: Add property-based tests that assert invariants across generated inputs instead of fixed examples
+category: testing
+---
+
+# Property Test
+
+Use when a function has properties that must hold for all inputs, and example-based tests miss edge cases.
+
+1. State the invariant in plain language (e.g. "decode(encode(x)) == x", "output is always sorted", "result never negative").
+2. Pick a property-based library for the language (Hypothesis, fast-check, QuickCheck) and define a generator for the input domain.
+3. Express the property as a test: generate inputs, run the code, assert the invariant holds for every case.
+4. Constrain generators to valid inputs only (filters/preconditions) so failures reflect real bugs, not invalid data.
+5. Run it; when it finds a failure, let the framework shrink to the minimal counterexample and inspect that case.
+6. Fix the bug, then pin the shrunk counterexample as an explicit regression example test.
+
+## Rules
+- Test true invariants — round-trips, idempotence, ordering, conservation — not restatements of the implementation.
+- Make generators match the real input domain; over-broad generators produce noise, over-narrow ones miss bugs.
+- Always capture the shrunk counterexample as a permanent example-based regression test once fixed.
+- Seed the RNG or record failing seeds so a found failure is reproducible, not a one-off in CI.
+- Keep run counts reasonable in CI; raise iterations for a focused hunt, not on every commit.

package/skills/protobuf/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: protobuf
+description: Design protobuf schemas that stay backward- and forward-compatible as they evolve
+category: networking
+---
+
+# Protobuf
+
+Reach for this when designing the wire format for messages shared across services, languages, or versions. The schema is a long-lived contract — design it for change.
+
+1. Start a `.proto` with `syntax = "proto3";`, a stable `package`, and one message per logical entity; keep messages small and composable.
+2. Assign field tags deliberately: 1–15 (single-byte) for the hottest fields, and never change a tag once it ships.
+3. Choose precise types — `int32`/`int64`/`bool`/`string`/`bytes`, `repeated` for lists, `map<k,v>` for dictionaries, and nested messages over flat blobs.
+4. Use `enum` with a `0` value named `*_UNSPECIFIED` as the default, and `oneof` for mutually exclusive fields.
+5. Evolve safely: add new fields with new tags, and `reserved` the tags/names of anything you remove.
+6. Lint and check compatibility (`buf lint`, `buf breaking`) in CI so breaking changes are caught before merge.
+
+## Rules
+- Field tags are the contract, not field names — renaming a field is safe on the wire, renumbering is catastrophic.
+- Every `enum` must have a `0 = *_UNSPECIFIED` member; proto3 treats `0` as the default and you can't tell "unset" from "first value" otherwise.
+- Don't change a field's type (e.g. `int32`→`string`) in place — add a new field and migrate; type changes corrupt decoding.
+- Reserve removed tags AND names (`reserved 4; reserved "old_name";`) so nobody silently reuses them.
+- Prefer explicit messages over `Any`/`Struct`/JSON-in-a-string; you lose type safety and compatibility checking.

package/skills/py-async/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: py-async
+description: Convert blocking Python code to async/await without deadlocks or hidden sync calls
+category: languages
+---
+
+# Py Async
+
+Use this when a module's I/O latency dominates and you want to move it to `asyncio`, or when porting sync callers into an existing async stack.
+
+1. Map the blocking boundaries: identify every network, disk, subprocess, and `time.sleep` call — these become `await` points or run in an executor.
+2. Swap sync libraries for async equivalents (`requests`→`httpx`/`aiohttp`, `psycopg2`→`asyncpg`, `open`→`aiofiles`) rather than wrapping everything in threads.
+3. Convert functions to `async def` from the I/O leaves upward, propagating `await` to every caller until you reach an entry point.
+4. For unavoidable blocking calls (CPU work, sync-only libs), offload with `await asyncio.to_thread(fn, ...)` or a process pool — don't call them directly on the loop.
+5. Replace sequential awaits with `asyncio.gather` or `TaskGroup` where operations are independent, and guard shared state with `asyncio.Lock`.
+6. Run under load and check for "coroutine was never awaited" warnings, blocked-loop stalls, and unhandled task exceptions.
+
+## Rules
+- Never call a blocking function directly inside a coroutine — it stalls the entire event loop for all tasks.
+- One event loop per process: use `asyncio.run(main())` at the top; don't create nested loops or call `loop.run_until_complete` from within async code.
+- Cancellation is cooperative — propagate `CancelledError`, and put cleanup in `finally` or `async with`.
+- Set timeouts on every await that hits the network (`asyncio.timeout(...)`); an unbounded await is a hang waiting to happen.
+- Don't mix sync and async versions of the same function in one call graph — pick a color and commit to it.

package/skills/py-typing/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: py-typing
+description: Add Python type hints to existing code and get it passing mypy or pyright cleanly
+category: languages
+---
+
+# Py Typing
+
+Reach for this when adding type hints to untyped Python or chasing down type-checker errors in a module or package.
+
+1. Pick a checker and pin strictness: `mypy --strict <path>` or `pyright`, and capture the current error count as a baseline.
+2. Annotate from the leaves up: type the most-imported helpers and data models first so call sites infer correctly.
+3. Replace ambiguous returns with precise types — use `X | None` over bare `Optional` omission, `Sequence`/`Mapping` for read-only params, concrete types for returns.
+4. Introduce `TypedDict`, `dataclass`, `Protocol`, or `@overload` instead of `dict[str, Any]` and `# type: ignore` where structure is known.
+5. Use `typing.cast` or a narrowing `assert isinstance(...)` only when the checker genuinely can't follow control flow — never to silence a real bug.
+6. Re-run the checker, drive the error count to zero, and add a CI step (`mypy` / `pyright`) so it stays there.
+
+## Rules
+- Prefer fixing the type over `# type: ignore`; if you must ignore, use a specific code like `# type: ignore[arg-type]` and a comment.
+- Don't annotate with `Any` to pass the checker — that defeats the purpose and hides defects.
+- Target the project's minimum Python version: use `from __future__ import annotations` or `typing_extensions` for newer constructs on older runtimes.
+- Type public APIs precisely; internal locals usually don't need annotations (the checker infers them).
+- Keep runtime behavior unchanged — adding hints must never alter logic, and avoid heavy `typing` imports inside hot paths.

package/skills/query-optimize/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: query-optimize
+description: Optimize a slow SQL query using EXPLAIN, indexes, and rewrites
+category: database
+---
+
+# Query Optimize
+
+Use when a specific query is slow and you need to find and fix the bottleneck with evidence, not guesses.
+
+1. Reproduce the slowness and capture the plan with `EXPLAIN ANALYZE` (or the engine's equivalent) on representative data volumes.
+2. Read the plan for the real cost: sequential scans on large tables, nested loops over big row counts, expensive sorts, and bad row-count estimates.
+3. Add or fix indexes to cover the `WHERE`, `JOIN`, and `ORDER BY` columns; consider composite indexes ordered by selectivity and partial indexes for filtered queries.
+4. Rewrite the query where the plan demands it: avoid `SELECT *`, replace correlated subqueries with joins, push filters earlier, and avoid functions on indexed columns (they defeat the index).
+5. Re-run `EXPLAIN ANALYZE` and confirm the plan improved and wall-clock time dropped on real data sizes.
+6. Update table statistics (`ANALYZE`) and check for N+1 patterns if the query comes from an ORM.
+
+## Rules
+- Measure before and after with `EXPLAIN ANALYZE` on production-like data — small dev tables hide scan costs.
+- An index helps reads but costs writes and storage; justify each one against the workload.
+- Filter and sort on indexed expressions; wrapping a column in a function or leading-wildcard `LIKE` skips the index.
+- Fix the query and indexes before reaching for caching or denormalization.
+- Re-check the plan after the change; the optimizer may pick a different path than you expect.

package/skills/rag-pipeline/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: rag-pipeline
+description: Build a retrieval-augmented generation pipeline with grounded, cited answers
+category: data-ml
+---
+
+# RAG Pipeline
+
+Use when an LLM needs to answer over a corpus it wasn't trained on — docs, knowledge base, tickets — and answers must be grounded in retrieved sources.
+
+1. Chunk source documents thoughtfully (by section/heading, with overlap) and keep metadata: source id, title, and offsets for citation.
+2. Embed chunks and index them in a vector store; consider hybrid retrieval (vector + keyword/BM25) for better recall on names and codes.
+3. At query time, retrieve top-k, optionally rerank, and assemble a context block that fits the model's window with the most relevant chunks first.
+4. Prompt the model to answer only from the provided context and to cite chunk ids; instruct it to say "not found" when context is insufficient.
+5. Return citations to the user and evaluate retrieval (recall@k) and answer faithfulness separately.
+6. Tune chunk size, k, and reranking against an eval set rather than by feel.
+
+## Rules
+- Ground every claim in retrieved context and require citations; an ungrounded answer is a hallucination risk.
+- Retrieval quality caps answer quality — debug recall before blaming the generator.
+- Use hybrid search when queries contain exact tokens (ids, error codes, proper nouns) that embeddings blur.
+- Re-embed and reindex when the embedding model or chunking changes; never mix embedding spaces.
+- Instruct the model to refuse when context is missing rather than filling gaps from parametric memory.

package/skills/rails-resource/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: rails-resource
+description: Scaffold a Rails resource with model, migration, controller, and routes
+category: frameworks
+---
+
+# Rails Resource
+
+Use to add a new resource to a Rails app — model + migration, RESTful controller, and routes — following convention over configuration.
+
+1. Generate it: `rails generate scaffold <Name> field:type ...` (or `model` + `controller` separately for finer control).
+2. Review the migration, adjust columns/indexes/null constraints, then run `rails db:migrate`.
+3. Add `resources :<plural>` to `config/routes.rb` (only needed if you didn't use full scaffold), scoping or nesting as appropriate.
+4. Lock down `params` with a strong-parameters `permit` list in the controller; add validations to the model.
+5. Adjust controller actions and views to match real requirements; remove unused scaffold actions.
+6. Run `rails server` and the generated tests; verify CRUD via the routes (`rails routes` to confirm paths).
+
+## Rules
+- Always use strong parameters (`params.require(:x).permit(...)`); never pass raw `params` to `create`/`update`.
+- Put validations and business rules on the model, not the controller.
+- Keep controller actions thin and RESTful; reach for service objects before bloating actions.
+- Add DB-level constraints/indexes in the migration, not just model validations.
+- Run `rails db:migrate` (and commit `schema.rb`) before relying on the new table; never edit `schema.rb` by hand.

package/skills/rate-limit/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: rate-limit
+description: Add rate limiting to an API with correct keys, headers, and 429 responses
+category: api
+---
+
+# Rate Limit
+
+Use when an endpoint or whole API needs throttling to protect against abuse, runaway clients, or cost blowups.
+
+1. Decide the limit key — per API key, per user, or per IP — and pick the scope (global vs per-route); document the chosen limit and window.
+2. Choose an algorithm (token bucket or sliding window) and a store: in-memory only for single-instance, Redis/shared store for multi-instance.
+3. Add the limiter as middleware or a decorator at the boundary, before expensive work runs.
+4. On rejection return `429 Too Many Requests` with a `Retry-After` header and a clear error body.
+5. Emit `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` headers on responses so clients can self-throttle.
+6. Test the boundary: requests under the limit pass, the request over it returns 429, and the counter resets after the window.
+
+## Rules
+- Use a shared store (Redis) when more than one instance serves traffic — in-memory counters under-count behind a load balancer.
+- Rate-limit on a trustworthy key; raw client IP is spoofable and breaks behind proxies unless you read the right forwarded header.
+- Fail open or closed deliberately — if the limiter store is down, decide whether to allow or block, don't crash the request.
+- Always include `Retry-After` so well-behaved clients back off instead of hammering.
+- Keep the limiter cheap; a slow check on every request defeats the purpose.

package/skills/react-hooks/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: react-hooks
+description: Convert a React class component to a function component using hooks
+category: frameworks
+---
+
+# React Hooks
+
+Reach for this when modernizing a legacy class component into a function component with hooks, preserving behavior exactly.
+
+1. Read the class: note `state` shape, `props` used, lifecycle methods, instance fields, and bound handlers.
+2. Replace the class with a function component; turn each piece of `state` into a `useState` call (group related fields only if they update together).
+3. Map lifecycles to effects: `componentDidMount`/`componentWillUnmount` → `useEffect(fn, [])` with a cleanup return; `componentDidUpdate` → `useEffect` with the right deps.
+4. Convert instance fields that survive renders (timers, refs to DOM/values) to `useRef`; convert methods to inline functions or `useCallback` if passed as props.
+5. Remove `this.`, `bind`, and the constructor; read props directly as the function argument.
+6. Run the component and its tests; verify effects fire and clean up the same number of times as the old lifecycles.
+
+## Rules
+- One `useEffect` per concern, not one giant effect mirroring `componentDidMount`.
+- Every value referenced inside an effect must be in its dependency array; do not silence the exhaustive-deps lint by deleting deps.
+- `useState` setters are async and don't merge objects — spread manually or split into multiple states.
+- Don't wrap everything in `useCallback`/`useMemo`; add them only when an identity actually matters downstream.
+- Preserve the original render output and ref-forwarding behavior; use `forwardRef` if the class exposed a ref.