ada-agent 0.1.0

package/skills/self-review/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: self-review
+description: Run a pre-PR self-review checklist over your own changes before opening the PR
+category: review
+---
+
+# Self Review
+
+Use this right before you open a PR or hand off work — read your own diff as a skeptical reviewer would, catching the obvious stuff before someone else does.
+
+1. Run `git diff main...HEAD` and read every hunk top to bottom as if you'd never seen it.
+2. Confirm the diff is scoped: no stray debug prints, commented-out code, leftover TODOs, or unrelated reformatting.
+3. Check the change actually does what the task asked — re-read the requirements and map each one to a line in the diff.
+4. Verify edge cases and error paths are handled (empty input, nulls, failures, concurrency) and that new behavior has tests.
+5. Run the build, linter, formatter, and test suite; fix anything red before proceeding.
+6. Review the commit messages and PR description for clarity, then list any follow-ups you're deliberately deferring.
+
+## Rules
+- Read the whole diff, not just the files you remember editing — staging mistakes hide in the rest.
+- Be your own harshest reviewer; if a line would draw a comment from a teammate, fix it now.
+- Don't claim tests pass without actually running them and seeing green output.
+- Keep unrelated cleanups out of the PR — file them separately so the diff stays reviewable.
+- If something is intentionally incomplete, call it out explicitly rather than hoping nobody notices.

package/skills/semantic-html/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: semantic-html
+description: Audit and fix HTML for semantic structure and accessibility — landmarks, headings, ARIA, and keyboard support.
+category: html
+---
+
+# Semantic HTML
+
+Use when markup is a soup of `<div>`s, screen-reader output is broken, or an accessibility audit failed. The goal is meaning-bearing elements over generic containers.
+
+1. Replace `<div>`-as-everything with landmarks: `<header> <nav> <main> <article> <section> <aside> <footer>`; exactly one `<main>` per page.
+2. Fix the heading outline: a single `<h1>`, no skipped levels, headings chosen by document hierarchy not font size.
+3. Swap fake interactive elements (`<div onclick>`) for real `<button>` / `<a>`; ensure everything actionable is keyboard-focusable and has a visible focus ring.
+4. Add accessible names: `alt` on images (empty `alt=""` for decorative), `<label>` tied to every input, `aria-label` only where no visible text exists.
+5. Use ARIA sparingly — prefer native semantics; only add roles/states the platform can't express, and never override correct native roles.
+6. Validate: run an axe / Lighthouse / WAVE pass, tab through the page, and check with a screen reader (NVDA/VoiceOver) for sensible reading order.
+
+## Rules
+- Native element first, ARIA last; a `<button>` beats `role="button"` every time.
+- No `alt`-less images, no unlabeled form controls, no positive `tabindex`.
+- Don't use heading tags or lists for visual styling; style with CSS instead.
+- Maintain logical DOM order so reading/tab order matches the visual layout.
+- Every interactive control must be operable by keyboard and have a focus indicator (don't `outline:none` without a replacement).

package/skills/semver-bump/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: semver-bump
+description: Bump the project version per semver, update changelog, and create the release tag
+category: compliance
+---
+
+# Semver Bump
+
+Reach for this when cutting a release and you need to choose the right version increment and tag it consistently.
+
+1. Determine the bump from the changes since the last tag: MAJOR for breaking API changes, MINOR for backward-compatible features, PATCH for backward-compatible fixes (`git log <lastTag>..HEAD`).
+2. Update the version in the source of truth (`package.json`, `pyproject.toml`, `Cargo.toml`, `VERSION`, etc.) and any places that mirror it.
+3. Update `CHANGELOG.md`: move Unreleased entries under the new version with the date, grouped by Added/Changed/Fixed/Removed.
+4. Commit with a clear message (e.g. `chore(release): v1.4.0`) on a release branch, not directly on a protected default branch.
+5. Create an annotated, prefixed tag matching the repo convention: `git tag -a v1.4.0 -m "v1.4.0"`.
+6. Push the commit and tag (`git push && git push --tags`) and open the PR / trigger the release pipeline.
+
+## Rules
+- A breaking change is MAJOR even if it feels small; never hide it in a MINOR/PATCH.
+- Pre-1.0.0: treat MINOR as the place for breaking changes (the 0.y.z special case) per semver.
+- Keep the tag format consistent with existing tags (`v`-prefixed or not) — check `git tag` first.
+- Use annotated tags (`-a`) so the tag carries metadata; lightweight tags break some release tooling.
+- Don't reuse or move a published tag; if wrong, cut a new version rather than rewriting history.
+- Bump the version and changelog in the same commit so the tag points at a coherent state.

package/skills/shader/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: shader
+description: Write and wire up a GLSL or WGSL shader with correct varyings and uniforms
+category: gamedev
+---
+
+# Shader
+
+Use when authoring a vertex/fragment (or compute) shader and binding it to geometry, uniforms, and textures.
+
+1. Decide the stage and language target (GLSL ES 3.0, GLSL 4.x core, or WGSL) and match it to your graphics API.
+2. Declare inputs explicitly: vertex attributes by location, varyings (`out`/`in`) matching between stages by name and type.
+3. Pass per-draw data via uniforms / uniform buffers / push constants; keep the layout in sync with host-side structs.
+4. In the vertex stage output clip-space position; in the fragment stage compute color, sampling textures with a bound sampler.
+5. Compile and check the info log; fail loudly on shader compile and program link errors before first draw.
+6. Verify output with a flat color or UV-visualization pass before adding lighting or effects.
+
+## Rules
+- Varying names and types must match exactly across vertex→fragment, or linking silently mismatches.
+- Watch precision qualifiers in GLSL ES (`highp`/`mediump`) — defaults differ between desktop and mobile.
+- Respect uniform buffer std140/std430 alignment; a `vec3` is padded to 16 bytes and will corrupt later fields.
+- Y axis and clip-space depth range differ between OpenGL, Vulkan/WGSL, and D3D — flip UVs/viewport as needed.
+- Avoid dynamic branching and unbounded loops in fragment shaders on mobile GPUs; prefer `mix`/`step`.

package/skills/shader-debug/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: shader-debug
+description: Debug a GLSL/WGSL shader: black/garbage output, NaNs, wrong UVs, precision and uniform mismatches
+category: graphics
+---
+
+# Shader Debug
+
+Reach for this when geometry draws but the shading is wrong: solid black, blown-out white, banding, flicker, or NaN holes.
+
+1. Reproduce with a constant: replace the fragment output with `gl_FragColor = vec4(1.0,0.0,1.0,1.0)` (or `return vec4(1,0,1,1)`). If magenta shows, the pixeling pipeline is fine and the bug is in your math/inputs.
+2. Visualize inputs as color instead of guessing: output `vec4(uv, 0, 1)`, then `vec4(normal*0.5+0.5,1)`, then each uniform. Wrong gradients pinpoint bad UVs, un-normalized normals, or a uniform stuck at 0.
+3. Hunt NaN/Inf: they propagate to black or weird pixels. Guard `pow`, `log`, `sqrt`, `normalize(vec3(0))`, and divides by length/dot that can hit zero. Add `if (isnan(x)) out = vec4(1,0,0,1);` to see where.
+4. Check uniforms actually arrive: confirm the uniform location is valid (not -1), the value is set every frame after binding the program, and the CPU/GPU types match (a `float` sent to a `vec3`, or an int/float mismatch, silently misbehaves).
+5. For mobile-only or GPU-specific breakage, add explicit `precision highp float;` and test — default `mediump` overflows on large coords/times, causing banding or jitter that desktop hides.
+6. Confirm UV orientation: many pipelines flip V. If textures appear upside-down or mirrored, try `uv.y = 1.0 - uv.y` and fix at the source (texcoord upload or sampler), not per-shader hacks.
+
+## Rules
+- A uniform location of -1 means the name is wrong OR the compiler dead-stripped it because it's unused — verify it's actually referenced.
+- `normalize` of a zero vector is NaN; guard any vector that can degenerate.
+- Don't trust `mediump` for world-space positions or `time` — promote to `highp` and confirm the artifact moves.
+- GLSL has no debugger; debug by writing intermediate values to the output color, one at a time.
+- Match CPU and GPU types and component counts exactly — silent mismatches are the most common "looks fine but wrong" bug.

package/skills/simplify-conditionals/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: simplify-conditionals
+description: Flatten nested or complex branches using guard clauses and early returns
+category: refactoring
+---
+
+# Simplify Conditionals
+
+Use when branching is deeply nested, hard to follow, or buried in negations. The aim is to make the happy path obvious and edge cases explicit.
+
+1. Identify the failure/edge conditions and convert them into guard clauses that return early at the top.
+2. Flatten the remaining nesting so the main logic sits at the lowest indentation level.
+3. Replace negated and compound conditions with positively-named boolean variables or small predicates.
+4. Collapse redundant branches (duplicate arms, dead `else`, unreachable cases) and consider a lookup table for long if/else chains.
+5. Confirm the truth table is unchanged — every input still hits the same outcome.
+6. Run tests, especially around boundary and short-circuit cases.
+
+## Rules
+- Early returns must preserve any cleanup that ran in the original tail — watch for finally/teardown.
+- Don't change short-circuit order if conditions have side effects or guard against null/undefined.
+- Keep guard clauses for true exceptions only; don't shove core logic into early returns.
+- Extract a complex condition into a well-named helper rather than commenting it.
+- Re-verify de Morgan transforms (`!(a && b)` ↔ `!a || !b`) — these are an easy place to flip behavior.

package/skills/sitemap/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: sitemap
+description: Generate a valid sitemap.xml and robots.txt so crawlers discover and correctly index every public URL.
+category: html
+---
+
+# Sitemap
+
+Use when launching or growing a site and you want search engines to find all pages and respect crawl rules.
+
+1. Enumerate canonical, indexable URLs (skip noindex, redirects, auth-only, and duplicate query-string variants); use absolute https URLs.
+2. Emit `sitemap.xml` with the `urlset` schema: one `<url>` per page with `<loc>` and accurate `<lastmod>` (ISO 8601); `changefreq`/`priority` are optional and largely ignored.
+3. If over 50,000 URLs or 50MB uncompressed, split into multiple sitemaps and reference them from a `sitemapindex` file.
+4. Write `robots.txt` at the site root: allow crawlers to public content, `Disallow` admin/private paths, and add a `Sitemap: https://.../sitemap.xml` line.
+5. Automate generation in the build (crawl the route table or filesystem) so the sitemap never drifts from the real pages.
+6. Validate the XML, then submit the sitemap in Google Search Console / Bing Webmaster Tools and confirm it's fetched without errors.
+
+## Rules
+- Only list canonical, 200-status, indexable URLs; broken or redirected entries hurt trust.
+- `robots.txt` blocks crawling, not indexing — use `<meta robots noindex>` to keep a page out of results.
+- Keep `lastmod` honest; faking recent dates can get the sitemap ignored.
+- Both files live at the domain root (`/sitemap.xml`, `/robots.txt`) and must be publicly fetchable.
+- Don't `Disallow` resources (CSS/JS) the page needs to render — Google penalizes blocked rendering.

package/skills/skeleton-loader/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: skeleton-loader
+description: Build loading skeletons and shimmer that mirror the final layout to reduce perceived wait and CLS.
+category: ui-design
+---
+
+# Skeleton Loader
+
+Reach for this when content takes a beat to load and a spinner would feel slow or cause layout shift — skeletons preview structure so the page feels fast and stable.
+
+1. Mirror the real layout: build the skeleton from the same component with placeholder blocks at the actual sizes/positions, so swapping in data causes zero shift (protects CLS).
+2. Skeleton-ize structure, not pixels: a few grey rounded blocks for title/avatar/lines — vary line widths (last line ~60%) so it reads as text, not a wireframe of every glyph.
+3. Animate with a restrained shimmer: a slow gradient sweep (~1.5–2s linear, looping) or a gentle opacity pulse — subtle, low-contrast, never a strobing distraction.
+4. Use the skeleton only past a perception threshold: render instantly when content is likely <~200ms? show nothing or the cached value; show the skeleton when you expect a real wait, and avoid flash-of-skeleton for sub-100ms loads.
+5. Transition out smoothly: crossfade skeleton → content (~150ms) rather than a hard pop, and stagger if many items resolve together.
+6. Honor `prefers-reduced-motion` by replacing the sweep with a static muted block, and keep the skeleton color derived from your surface/muted tokens for theme + dark-mode correctness.
+
+## Rules
+- Skeleton dimensions must equal final dimensions — if the content reflows on load, the skeleton failed its one job.
+- Keep shimmer low-contrast and slow; a fast, high-contrast sweep is more annoying than a spinner.
+- Don't skeleton a whole page when only one region is async — load shell + chrome instantly, skeleton just the pending part.
+- Avoid skeleton flicker: gate on a short delay so fast responses never flash a placeholder.
+- Build from muted/surface tokens so it adapts to light/dark automatically — no hard-coded greys.

package/skills/slide-charts/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: slide-charts
+description: Add native charts and tables to slides from data using python-pptx chart and table APIs.
+category: pptx
+---
+
+# Slide Charts
+
+Use when a slide needs to visualize numbers — trends, comparisons, breakdowns — or present structured rows of data.
+
+1. Get the data into a clean structure (lists/dict or a DataFrame) and decide the message the chart must make obvious.
+2. Pick the chart type for that message: line for trend, bar/column for comparison, pie/doughnut sparingly for parts-of-whole.
+3. Build a `CategoryChartData` with `.categories` and one or more `.add_series(name, values)`.
+4. Place it with `slide.shapes.add_chart(XL_CHART_TYPE.<TYPE>, x, y, cx, cy, chart_data)` using `Inches(...)` coordinates.
+5. Style for clarity: title, data labels where useful, legend only if multi-series, and brand colors on the series fill.
+6. For tabular data use `shapes.add_table(rows, cols, ...)`, bold the header row, and keep it to the columns that matter.
+
+## Rules
+- Native python-pptx charts stay editable in PowerPoint; only fall back to an image (matplotlib export) when a chart type isn't supported.
+- One chart, one message — don't overload axes or stack unrelated series.
+- Label axes and units; never show a bare number with no context.
+- Avoid 3-D effects and chart junk; they distort perception and hurt readability.
+- Keep tables small (rough max ~6 columns, ~8 rows) — dense grids belong in an appendix or handout.
+- Sort categories meaningfully (by value or time), not alphabetically by default.

package/skills/slide-outline/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: slide-outline
+description: Outline a presentation as one idea per slide before building any actual slides.
+category: pptx
+---
+
+# Slide Outline
+
+Always reach for this before generating a deck. A tight outline prevents bloated, unfocused slides and makes the build step mechanical.
+
+1. Pin down the single goal of the talk and the one action or belief you want the audience to leave with.
+2. Identify the audience and time budget (roughly 1-2 minutes per content slide) to bound the slide count.
+3. List each slide as a one-line takeaway headline — the assertion, not the topic ("Churn dropped 30% after onboarding redesign", not "Churn").
+4. Under each headline note the supporting evidence: a stat, chart, image, or 2-3 bullets — nothing more.
+5. Order for narrative flow (hook → context → core argument → evidence → call to action) and check each slide earns its place.
+6. Review the outline with the user, then hand it to pptx-deck or pptx-from-markdown to build.
+
+## Rules
+- One idea per slide; if a headline contains "and", split it into two slides.
+- Headlines are full assertions, not topic labels.
+- Keep supporting points to 3 or fewer per slide at the outline stage.
+- Cut any slide that doesn't advance the single goal.
+- Settle structure and message in the outline; defer all visual styling to the build.

package/skills/snapshot-update/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: snapshot-update
+description: Review snapshot test diffs and update them intentionally, never blindly accepting all
+category: testing
+---
+
+# Snapshot Update
+
+Use when snapshot tests fail after a change and you need to decide which diffs are intended versus regressions.
+
+1. Run the snapshot tests and read each failing diff in full before touching the snapshot files.
+2. For every diff, decide deliberately: is this the change I intended, or did I break something I didn't mean to?
+3. Fix the code for any unintended diff; only update the snapshot for diffs that reflect intended behavior.
+4. Update accepted snapshots (e.g. `--update`/`-u`) and re-run to confirm the suite is green.
+5. Open the snapshot file changes in the diff and review them like any other code change before committing.
+6. Commit the snapshot updates alongside the code change that justifies them, with a message explaining why.
+
+## Rules
+- Never run a blanket "update all snapshots" without reading every diff — that turns the test into a rubber stamp.
+- A snapshot diff you can't explain is a regression until proven otherwise; investigate, don't accept.
+- Keep snapshots small and focused; giant snapshots hide meaningful diffs in noise — prefer targeted assertions for logic.
+- Commit snapshot updates with the change that caused them, never as a separate "fix snapshots" cleanup later.
+- Scrub nondeterministic values (timestamps, ids, paths) from snapshots so they don't churn on every run.

package/skills/solidity-contract/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: solidity-contract
+description: Write a production-ready Solidity smart contract with tests, access control, and a deploy script
+category: web3
+---
+
+# Solidity Contract
+
+Reach for this when implementing a new on-chain contract from scratch. Favor battle-tested libraries over hand-rolled logic.
+
+1. Pin a compiler: set an exact `pragma solidity 0.8.x;` and lock it in `foundry.toml`/`hardhat.config` (`evmVersion`, `optimizer`).
+2. Scaffold from OpenZeppelin: import vetted bases (`Ownable`/`AccessControl`, `ReentrancyGuard`, `Pausable`, `SafeERC20`) instead of writing your own.
+3. Define state and the external interface first: storage layout, events for every state change, custom errors instead of `require` strings.
+4. Implement with checks-effects-interactions order; mark functions `external`/`view`/`pure` correctly and add `onlyRole`/`onlyOwner` guards.
+5. Write tests (`forge test` or Hardhat): cover happy path, revert paths, access control, and at least one fuzz/invariant test.
+6. Add a deploy script (`forge script` or Hardhat deploy) that reads addresses/params from env, never hardcoded keys.
+7. Run `forge build`/`compile`, the test suite, and a linter (`solhint`) before declaring done.
+
+## Rules
+- Never use `tx.origin` for auth; use `msg.sender` with explicit roles.
+- Emit an event for every meaningful state mutation so off-chain indexers can follow.
+- Validate all external inputs; reject zero addresses and zero amounts explicitly.
+- Avoid `delegatecall`, `selfdestruct`, and assembly unless you can justify and test them.
+- Keep funds-handling functions `nonReentrant` and follow checks-effects-interactions.
+- Pin dependency versions (no floating `^`) for reproducible bytecode.

package/skills/speaker-notes/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: speaker-notes
+description: Write per-slide speaker notes that a presenter can deliver, added to each slide's notes pane.
+category: pptx
+---
+
+# Speaker Notes
+
+Use when a deck needs a spoken script or presenter guidance — slides carry the headline, notes carry what the presenter actually says.
+
+1. Read each slide's headline and visuals to understand the point that slide must land.
+2. Write the notes as spoken language: the opening line, the key point, and a transition into the next slide.
+3. Keep each slide's notes to roughly 30-90 seconds of speech (about 75-200 words); trim anything the slide already shows.
+4. Add timing cues, the "so what" for any chart, and reminders for demos or audience questions.
+5. Write notes into `slide.notes_slide.notes_text_frame.text` in python-pptx (this auto-creates the notes slide).
+6. Read the notes end-to-end as a continuous script to check the narrative flows between slides.
+
+## Rules
+- Notes are a script to speak, not bullet points to read aloud — write in full, natural sentences.
+- Never just restate the slide text; add the context, story, or data interpretation behind it.
+- Match the speaker's voice and the talk's time budget; cut ruthlessly if over.
+- Always end a slide's notes with a one-line bridge to the next slide.
+- Flag any claim that needs a source or a number the presenter must confirm.

package/skills/spike/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: spike
+description: Run a timeboxed exploration of an unknown and write up findings, a recommendation, and next steps
+category: productivity
+---
+
+# Spike
+
+Use this when a task is too uncertain to estimate or plan — you need to learn something (a library, an API, a feasibility question) within a fixed time budget and report back, not ship production code.
+
+1. State the question the spike must answer and the timebox (e.g. "Can we stream this API's responses? — 60 min") before touching anything.
+2. List 2-4 concrete things to try or check, ordered cheapest-to-prove-first.
+3. Explore: prototype throwaway code, read docs/source, run experiments — keep notes on what you tried and what happened.
+4. Stop when the timebox ends OR the question is answered, whichever comes first; do not let scope creep into building the real thing.
+5. Write up findings: the answer, the evidence behind it, surprises/risks discovered, and a clear recommendation (do it / don't / need another spike).
+6. List the follow-up tasks the spike unblocked, and explicitly mark prototype code as throwaway.
+
+## Rules
+- Honor the timebox — a spike that runs long has failed its own purpose; report partial findings instead.
+- Optimize for learning, not quality: no tests, no polish, no refactors on spike code.
+- Always end with a decision or recommendation; "it's complicated" is not an output.
+- Keep prototype code on a scratch branch or clearly labeled dir so it never merges by accident.
+- If you cannot answer within the box, say so and propose a narrower follow-up spike.

package/skills/split-file/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: split-file
+description: Break a large file into focused modules without changing behavior
+category: refactoring
+---
+
+# Split File
+
+Use when a file has grown to mix several responsibilities and is hard to navigate or test. Split along seams that already exist, not arbitrary line counts.
+
+1. Map the file's contents into groups by responsibility (types, helpers, one cohesive feature each).
+2. Identify the dependency direction between groups so new modules don't create import cycles.
+3. Move one group at a time into a new module, keeping names intact to minimize churn.
+4. Add imports/exports; update every external reference to point at the new location.
+5. Optionally keep the original file as a thin barrel that re-exports, to avoid touching many call sites at once.
+6. Build and run tests after each move; commit per extracted module.
+
+## Rules
+- Split by responsibility, not by size — a 600-line file with one clear job may be fine as is.
+- Watch for circular imports; if two new modules need each other, the seam is wrong — extract shared parts to a third.
+- Keep public exports stable, or update all importers in the same change.
+- Don't relocate code and edit its logic in the same step; move first, then refactor.
+- Preserve file-level side effects (registration, init order) — moving them can change runtime behavior.

package/skills/spring-controller/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: spring-controller
+description: Add a Spring Boot REST controller backed by a service and DTOs
+category: frameworks
+---
+
+# Spring Controller
+
+Use to expose a new REST endpoint in a Spring Boot app, layering controller → service → repository with proper DTOs and status codes.
+
+1. Define request/response DTOs (records work well) and validation annotations (`@NotNull`, `@Size`, …) — don't expose entities directly.
+2. Create a `@RestController` with a class-level `@RequestMapping("/api/...")`; inject the service via constructor.
+3. Add handler methods with `@GetMapping`/`@PostMapping`/etc., binding `@RequestBody`/`@PathVariable`/`@RequestParam` and `@Valid` on bodies.
+4. Put business logic in a `@Service` bean; keep the controller to mapping, validation, and response shaping.
+5. Return `ResponseEntity<T>` with correct status codes; handle errors centrally via `@ControllerAdvice`/`@ExceptionHandler`.
+6. Run the app (`./mvnw spring-boot:run` or `./gradlew bootRun`) and exercise the endpoint with curl/HTTP client.
+
+## Rules
+- Never serialize JPA entities over the wire — map to DTOs to avoid lazy-loading and over-exposure bugs.
+- Use constructor injection (final fields), not field `@Autowired`.
+- Validate input with `@Valid` and surface failures as 400s via a global exception handler, not stack traces.
+- Keep controllers free of persistence/transaction logic; `@Transactional` belongs in the service layer.
+- Choose accurate status codes (201 + `Location` on create, 404 on missing, 204 on delete).

package/skills/sprite-anim/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: sprite-anim
+description: Build a frame-based sprite animation system driven by a texture atlas
+category: gamedev
+---
+
+# Sprite Animation
+
+Use to play named animation clips (idle, run, attack) from a sprite sheet with correct timing and state transitions.
+
+1. Pack frames into an atlas and record each frame's source rect (x, y, w, h) plus pivot/origin.
+2. Define clips as ordered frame lists with per-clip frame duration (or per-frame durations) and a loop flag.
+3. Track playback state per entity: current clip, elapsed time, current frame index, playing/paused.
+4. Each update, advance elapsed by `dt`; while it exceeds the frame duration, subtract and step the frame index.
+5. At clip end, loop back to frame 0 or hold the last frame and fire an "animation finished" event.
+6. On render, draw the current frame's source rect to the destination, honoring the pivot for flips and rotation.
+
+## Rules
+- Drive timing by accumulated `dt`, never by frame count, so speed is constant across frame rates.
+- Keep animation state separate from gameplay state; a state machine decides which clip, the player just plays it.
+- Use the pivot/origin for horizontal flips so the sprite does not visually jump on direction change.
+- Disable texture filtering (use nearest) for pixel art to avoid bleeding between atlas frames; add padding/extrusion.
+- Make non-looping clips emit a completion signal so transitions (attack→idle) are event-driven, not polled.

package/skills/sql-report/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: sql-report
+description: Write a correct, readable analytics SQL query or report
+category: data-ml
+---
+
+# SQL Report
+
+Use when answering an analytics question with SQL — metrics, cohorts, funnels, time series — where correctness of grain and joins matters more than cleverness.
+
+1. State the question precisely: what's one row in the output (the grain), over what time window, and filtered how.
+2. Identify the base tables and their grain; confirm join keys are unique on at least one side to avoid fan-out.
+3. Build incrementally with CTEs — one logical step per CTE (filter, join, aggregate) — instead of nested subqueries.
+4. Aggregate with explicit GROUP BY matching the SELECT, and use window functions for running totals, ranks, and period-over-period.
+5. Guard against double counting from many-to-many joins; pre-aggregate to the right grain before joining.
+6. Sanity-check totals against a known number, check for NULLs in keys, and review the row count.
+
+## Rules
+- Define the output grain first; most SQL bugs are a join that silently multiplies rows.
+- Filter dates with half-open ranges (`>= start AND < end`) to avoid boundary and timezone errors.
+- Beware aggregates over LEFT-joined NULLs — `COUNT(col)` skips NULLs, `SUM` treats them as zero; be intentional.
+- Name CTEs for what they represent; avoid `SELECT *` in reports so the contract is explicit.
+- Verify with a small spot-check (a single known entity) before trusting the aggregate.

package/skills/squash/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: squash
+description: Squash a feature branch into one clean commit before merging
+category: git
+---
+
+# Squash
+
+Reach for this when a feature branch has many WIP/fixup commits and you want a single, well-described commit on the main history before merge.
+
+1. Update the base so the squash sits on current code: `git fetch origin` then `git rebase origin/main` (resolve conflicts if any).
+2. Count the commits to combine: `git log --oneline origin/main..HEAD`.
+3. Squash interactively: `git rebase -i origin/main`, keep the first as `pick`, change the rest to `squash` (keeps their messages) or `fixup` (discards them).
+4. Write one clear commit message in the editor that summarizes the whole change — subject line plus a body explaining the "why".
+5. Alternatively, for a no-rebase squash: `git reset --soft origin/main` then a single `git commit` — collapses all changes into one staged commit.
+6. Verify the tree is unchanged (`git diff origin/main` should match the branch's net effect) and tests pass, then `git push --force-with-lease`.
+7. Or skip local squashing entirely and use GitHub's "Squash and merge" button if the repo enables it.
+
+## Rules
+- Squash only commits unique to your branch; never squash across commits others have based work on.
+- Force-push the rewritten branch with `--force-with-lease`, never plain `--force`.
+- Preserve the meaningful detail in the final message — don't reduce a real change to "fix stuff".
+- `git reset --soft origin/main` is the simplest path when you just want everything as one commit and don't need to reorder.
+- If the platform offers squash-merge, prefer it for shared branches so local history stays untouched.

package/skills/ssl-setup/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: ssl-setup
+description: Set up TLS certificates with Let's Encrypt and automate renewal
+category: cloud
+---
+
+# SSL Setup
+
+Use this to get a domain onto HTTPS with a free, auto-renewing Let's Encrypt certificate — and to make sure renewal won't silently lapse.
+
+1. Confirm the domain's DNS A/AAAA record points at the server and ports 80/443 are reachable.
+2. Pick a challenge: HTTP-01 (certbot --webroot/--nginx) for a public server, or DNS-01 for wildcards and private hosts.
+3. Issue the cert with certbot (e.g. `certbot --nginx -d example.com -d www.example.com`), supplying a contact email.
+4. Wire the cert into the server (nginx/apache) and force HTTP→HTTPS redirects.
+5. Verify the chain and expiry with `openssl s_client -connect host:443` or an SSL Labs scan.
+6. Confirm auto-renewal: `certbot renew --dry-run` and ensure the systemd timer / cron job is active.
+
+## Rules
+- Let's Encrypt certs last 90 days — renewal MUST be automated; a manual process will eventually expire.
+- Test against the staging ACME endpoint first to avoid hitting rate limits on bad attempts.
+- Use DNS-01 for wildcard (`*.example.com`) certs; HTTP-01 can't issue wildcards.
+- Keep private keys `600` and owned by the service user; never commit them to git.
+- After renewal, reload (not restart) the web server so it picks up the new cert with zero downtime.

package/skills/stacktrace/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: stacktrace
+description: Read a stack trace and locate the root cause frame instead of fixing where the error surfaced
+category: debugging
+---
+
+# Stacktrace
+
+Use when you have an exception, panic, or crash trace and need to find what actually went wrong. The top of the trace is where it blew up, not always where the bug lives.
+
+1. Read the exception type and message first — they often tell you the category (null/undefined, type mismatch, index, IO, timeout).
+2. Find the deepest frame that belongs to your code (skip framework/library frames) — that's usually where to start looking.
+3. Identify the exact line and the values involved: which variable was null, which index was out of range, which call failed.
+4. Walk up the trace to see how that bad value got there — trace the argument back to its origin (caller, config, input, prior call).
+5. Reproduce the failing call in isolation if possible, or add a log just above the failing line to inspect the inputs.
+6. Fix at the origin of the bad value, not merely at the line that threw.
+
+## Rules
+- "Caused by" / chained exceptions matter most — read to the bottom of the chain for the original failure.
+- Async/promise traces can be truncated or misleading; enable async stack traces or long-stack support when frames look orphaned.
+- A line number can drift if the source was transpiled/minified — map back through source maps before trusting it.
+- Don't wrap the throw site in try/catch to make the trace disappear; that hides the bug.
+- If the trace is all library frames, the trigger is almost always the data or arguments you passed in.

package/skills/static-site/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: static-site
+description: Scaffold a fast, framework-free static site with shared partials, clean URLs, and a simple build step.
+category: html
+---
+
+# Static Site
+
+Reach for this when a site is mostly content (docs, blog, brochure) and a framework would be overkill. Plain HTML/CSS/JS deploys anywhere and stays fast for years.
+
+1. Lay out the tree: `index.html`, `/assets` (css, js, img), `/pages` for additional routes, and a `404.html`; keep one shared stylesheet.
+2. Factor repeated chrome (head, header, footer) into partials; assemble with a tiny tool (`eleventy`, `npx serve` + includes, or a 20-line build script) rather than copy-pasting.
+3. Write semantic, accessible markup with shared meta defaults; set `<html lang>`, viewport, and a single design-token CSS file using custom properties.
+4. Use clean URLs via directory `index.html` files (`/about/index.html` -> `/about/`); keep relative links portable.
+5. Optimize assets: minify CSS/JS, compress and size images, add `loading="lazy"`, and set long cache headers for hashed assets.
+6. Add a local dev loop (`python -m http.server` or `npx serve`) and a one-command build; output to a `dist/` folder for deploy.
+7. Generate `sitemap.xml` + `robots.txt` (see `sitemap` skill) and deploy to any static host (Netlify, Pages, S3, Cloudflare).
+
+## Rules
+- No framework unless a real need appears; ship HTML/CSS and progressively enhance with vanilla JS.
+- Keep the build reproducible and dependency-light; a script you can read beats a config you can't.
+- Use relative or root-absolute links consistently so the site works under any subpath.
+- Don't inline large data or base64 images into HTML; reference real asset files for caching.
+- Always include `<meta name="viewport">` and a `lang` attribute; test with JS disabled.

package/skills/structured-logging/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: structured-logging
+description: Adopt structured, leveled JSON logging with consistent fields and correlation IDs
+category: observability
+---
+
+# Structured Logging
+
+Reach for this when grep-on-plaintext logs stop scaling — you need to filter, aggregate, and correlate logs in a log backend.
+
+1. Pick a structured logger (pino, zap, structlog, slog) and configure JSON output to stdout; let the platform handle shipping.
+2. Define a base logger with always-present fields: `service`, `env`, `version`, and a `level`.
+3. Bind request-scoped context (`request_id`, `trace_id`, `user_id` if non-PII) via child loggers / context so every line in a request shares correlation keys.
+4. Use levels deliberately: `error` for actionable failures, `warn` for recoverable anomalies, `info` for lifecycle events, `debug` for diagnostics off by default in prod.
+5. Log events as `message` + structured fields, never string-concatenated values (`log.info('order placed', { order_id, amount })`).
+6. Set log level from an env var and confirm JSON parses and correlation IDs thread through a sample request.
+
+## Rules
+- Never log secrets, tokens, passwords, full card/PII; add a redaction list and apply it at the logger, not per call site.
+- One event per log line; don't split a single event across multiple lines.
+- Reuse field names consistently across the codebase (`user_id` everywhere, not `userId`/`uid`).
+- Don't log inside hot loops at `info`; guard expensive payloads behind level checks.
+- Include `trace_id` so logs join traces; emit it from the same context source.

package/skills/svelte-store/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: svelte-store
+description: Create and consume Svelte stores for shared cross-component state
+category: frameworks
+---
+
+# Svelte Store
+
+Use when state must be shared across components or live outside the component tree — reach for a store instead of prop-drilling.
+
+1. Create a module (e.g. `src/lib/stores.js`) and export a `writable(initial)` for mutable state or `readable` for external/read-only sources.
+2. For derived state, use `derived(source, ($source) => ...)` so it recomputes automatically.
+3. In components, subscribe with the `$store` auto-subscription in markup and script — Svelte handles unsubscribe.
+4. Update state via `store.set(value)` or `store.update(prev => next)`; for `$store = x` shorthand, ensure you're in a component.
+5. For encapsulated logic, wrap the store in a factory returning `{ subscribe, ...customMethods }` (the custom-store pattern).
+6. Verify reactivity across components and that no manual subscription leaks (prefer `$` over `.subscribe` in components).
+
+## Rules
+- Use the `$` prefix in components to auto-subscribe and auto-unsubscribe; only call `.subscribe()` manually outside components, and always clean it up.
+- `readable` needs a stop/cleanup function returned from its start callback for timers/listeners.
+- Don't put non-serializable or per-request state in a module-level store in SSR contexts — it's shared across requests.
+- Keep store mutation logic in the store module (custom stores), not scattered across components.
+- `derived` is read-only; never try to `set` a derived store.

package/skills/swiftui-view/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: swiftui-view
+description: Build a SwiftUI view with state and two-way bindings
+category: mobile
+---
+
+# SwiftUI View
+
+Reach for this when building a SwiftUI view that holds local state and drives child controls through two-way `Binding`s (toggles, text fields, sliders, sheets).
+
+1. Define a `struct` conforming to `View` and implement the `var body: some View` computed property.
+2. Pick the right property wrapper: `@State` for value-type state owned by this view, `@Binding` for state owned by a parent, `@Observable`/`@StateObject` for reference-type models.
+3. Pass mutable state down with the `$` projected value (e.g. `Toggle("On", isOn: $isOn)`) so child controls write back.
+4. Compose layout with `VStack`/`HStack`/`ZStack` and modifiers; keep `body` declarative and free of side effects.
+5. Add a `#Preview` (or `PreviewProvider`) covering the key states so you can iterate in the canvas without a full build.
+6. Drive side effects with `.task`, `.onAppear`, or `.onChange(of:)` — not from inside `body`.
+
+## Rules
+- Own a piece of state in exactly one place: `@State` at the source, `@Binding` for children — never duplicate it.
+- `@State` properties should be `private`; expose mutation through bindings, not public vars.
+- Keep `body` a pure function of state; do networking and persistence in `.task`/model methods.
+- Break large `body` blocks into smaller subviews or `@ViewBuilder` computed properties to keep the type-checker fast.
+- Use `@StateObject` to create an observable model once; use `@ObservedObject`/`@Bindable` only when it's injected from outside.