@ketecode/loom 0.0.0-stage → 0.2.0

package/skills/vue-patterns/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: vue-patterns
+description: Vue 3 Composition API guidance for writing and fixing single-file components with script setup, covering ref versus reactive, reactivity lost by destructuring, computed and watch rules, composables with cleanup, typed defineProps, defineEmits and defineModel, Pinia stores with storeToRefs, and component tests with Vue Test Utils. Use when building or refactoring a Vue 3 component, writing a composable or Pinia store, or debugging a value that stopped updating in a Vue view.
+license: MIT
+compatibility: Any Agent Skills host. Targets Vue 3.4+ with script setup and TypeScript; notes call out 3.5-only APIs. Tests assume Vitest and @vue/test-utils.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: writes-files
+  kete-loom/owner: "Kete-org"
+---
+
+# Vue 3 patterns
+
+Write Vue 3 components whose state stays reactive, whose side effects clean up, and whose contracts (props, emits, models) are typed. For Nuxt-specific concerns (useFetch, server routes, SSR), use `nuxt-patterns` alongside this skill.
+
+## 0. Before you write
+
+1. Read `package.json` for the Vue version, Pinia, Vue Router, Vitest and `@vue/test-utils`. APIs marked 3.5 below need Vue 3.5 or later.
+2. Match the house style: `<script setup lang="ts">` versus Options API, store layout, file naming. Do not convert a codebase's Options API components to Composition API unless asked.
+3. Find an existing component or composable that does something similar and copy its structure.
+
+## 1. Reactivity rules
+
+| Situation | Use |
+|---|---|
+| Primitive, or a value you replace wholesale | `ref()` |
+| Object you only mutate in place, never reassign | `reactive()` (or just `ref()` everywhere for consistency) |
+| Large immutable data (API payloads, lists you replace) | `shallowRef()` and assign a new value |
+| Derived value | `computed()`, never a watcher that writes another ref |
+| Side effect when something changes | `watch()` / `watchEffect()` |
+
+Reactivity breaks in predictable places. Check each one:
+
+1. **Destructuring a `reactive` object** gives plain values: `const { count } = state` never updates. Use `toRefs(state)` or keep `state.count`.
+2. **Reassigning a `reactive` variable** (`state = reactive({...})`) disconnects the template. Mutate fields or switch to `ref`.
+3. **Destructuring a Pinia store** loses reactivity for state and getters. Use `const { items, total } = storeToRefs(store)`; take actions directly from the store.
+4. **Passing `props.x` into a composable** passes a snapshot. Pass `() => props.x` or `toRef(props, 'x')` and read it with `toValue()` inside.
+5. **Props destructure**: on Vue 3.5+, `const { size = 'md' } = defineProps<...>()` stays reactive, but `watch(size, ...)` does not work; watch `() => size`. On earlier versions, do not destructure props.
+6. **`.value`**: needed in script, never in templates for top-level refs. A ref nested inside a plain object in the template is not unwrapped.
+
+## 2. Computed and watchers
+
+- `computed` getters must be pure: no requests, no mutation, no writes to other refs.
+- Prefer `watch(source, cb)` with an explicit source over `watchEffect` when the effect does async work, so the dependencies are obvious.
+- Cancel stale async work. Use the `onCleanup` argument (`watch(id, async (v, _old, onCleanup) => { const ctl = new AbortController(); onCleanup(() => ctl.abort()); ... })`), or `onWatcherCleanup()` on 3.5+.
+- Watchers created synchronously in `setup` stop with the component. A watcher created after an `await` or inside a timeout does not: keep the returned stop handle and call it in `onUnmounted`.
+- Use `{ immediate: true }` instead of calling the handler once by hand. Use `{ deep: true }` only when you truly need nested changes; it walks the whole object.
+
+## 3. Composables
+
+1. Name them `useX`, put them in `composables/`, and return an object of refs (not a `reactive`) so callers can destructure.
+2. Accept `MaybeRefOrGetter<T>` arguments and read them with `toValue()` inside a `watch` or `computed`.
+3. Every listener, interval, observer or subscription a composable starts gets torn down in `onUnmounted` (or `onScopeDispose` when it may run outside a component).
+4. Call composables synchronously at the top of `setup`, never inside an event handler, `if`, or after `await`.
+5. Keep shared module-level state deliberate: a `ref` declared outside the function is a singleton across every component and, under SSR, across every request. For SSR apps put shared state in Pinia instead.
+
+## 4. Component contracts
+
+```vue
+<script setup lang="ts">
+const props = withDefaults(defineProps<{ items: Item[]; pageSize?: number }>(), { pageSize: 20 })
+const emit = defineEmits<{ select: [id: string]; close: [] }>()
+const query = defineModel<string>('query', { default: '' })
+</script>
+```
+
+- Never mutate a prop. To edit a parent's value, use `defineModel` (3.4+) or emit an event. For a local editable copy, `const draft = ref(structuredClone(toRaw(props.item)))` and say when it resyncs.
+- Type emits so callers get checked payloads. Emit names are camelCase in script, listened to as `@select` or `@update:query`.
+- Use `v-for` with a stable `:key` from the data, never the index for lists that reorder.
+- Never put `v-if` and `v-for` on the same element; filter with a `computed` first.
+- Use `useTemplateRef('name')` (3.5+) or a `ref(null)` with a matching `ref="name"` for DOM access, and only touch it after `onMounted`.
+- Render untrusted HTML only after sanitising it; `v-html` with user content is an XSS bug.
+
+## 5. Pinia
+
+- Prefer setup stores (`defineStore('cart', () => { ... return { items, total, add } })`) when the codebase has no preference. Return every piece of state, or SSR hydration and devtools miss it.
+- Keep server calls in actions, not in components, and handle errors there.
+- Use `storeToRefs` when destructuring (rule 1.3).
+- Do not call `useCartStore()` at module top level; call it inside `setup`, a composable, an action, or a function that runs after `app.use(pinia)`. Under SSR, a top-level call shares one store across requests.
+
+## 6. Tests
+
+1. Use Vitest with `@vue/test-utils` (`mount`, or `shallowMount` only when children are heavy).
+2. Test through the rendered output and emitted events: `wrapper.find('[data-test="save"]').trigger('click')`, then `await nextTick()` or `await flushPromises()`, then assert on `wrapper.text()` or `wrapper.emitted('select')`.
+3. For components using Pinia, mount with `global: { plugins: [createTestingPinia({ createSpy: vi.fn })] }` from `@pinia/testing`, or a fresh `createPinia()` per test.
+4. Test composables by calling them inside a tiny host component, or directly when they use no lifecycle hooks.
+5. Mock the network at the boundary (fetch or the API module), not the component under test.
+
+## Stop and ask the user
+
+- The fix requires switching state management (Vuex to Pinia, Options to Composition API).
+- A prop needs two-way binding but the parent is outside the files you were asked to touch.
+- Upgrading Vue to get a 3.5 API would be the simplest fix.
+
+## Never
+
+- Never mutate props or a store's state from a template expression.
+- Never silence a reactivity bug with `forceUpdate`, `key` bumping or `setTimeout`; find the lost reference.
+- Never leave a listener, interval or watcher without a teardown path.
+
+## Report back
+
+List the files changed, which reactivity or contract rule each change applies, the test command you ran and its result, and anything you could not verify in a browser.

package/skills/vue-patterns/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "My Vue component stops updating after I destructure the reactive state object, why?",
+    "Write a useDebouncedSearch composable in Vue 3 that cancels stale requests",
+    "Convert this Vue child component to defineModel instead of mutating the prop",
+    "Set up a Pinia setup store for the cart and use it from a script setup component",
+    "Add Vue Test Utils tests for the dropdown component's select event"
+  ],
+  "should_not_trigger": [
+    "My Nuxt page shows a hydration mismatch warning after useFetch",
+    "Review this Vue pull request for watcher leaks and prop mutation",
+    "Migrate this Svelte 4 store to Svelte 5 runes",
+    "Convert this Angular component to signals and standalone",
+    "Write a React custom hook that debounces search input"
+  ]
+}

package/skills/web-accessibility/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: web-accessibility
+description: Builds and fixes web UI so it meets WCAG 2.2 Level AA, starting from semantic HTML and adding keyboard support, focus management, labelled forms with announced errors, sufficient colour contrast and ARIA only where native elements fall short, then checks the result with axe and a screen reader. Use when writing or changing components, forms, dialogs, menus or pages that people must be able to use with a keyboard, screen reader, zoom or voice control.
+license: MIT
+compatibility: Any Agent Skills host. Works on any HTML-producing stack (plain HTML, React, Vue, Svelte, Angular, server templates). Automated checks need Node and a browser.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: writes-files
+  kete-loom/owner: "Kete-org"
+---
+
+# Web accessibility (WCAG 2.2 AA)
+
+Goal: every user can perceive, operate and understand the UI. Fix the markup first; ARIA and JavaScript come last.
+
+## 0. Before you start
+
+1. Find what the project already has: a component library (does it ship accessible primitives?), an a11y lint plugin (`eslint-plugin-jsx-a11y`, `eslint-plugin-vuejs-accessibility`, `@angular-eslint` template rules), axe in tests (`@axe-core/playwright`, `jest-axe`, `vitest-axe`, `cypress-axe`).
+2. Reuse the project's accessible primitives (dialog, menu, tabs, combobox) instead of building new ones.
+3. If the design requires something that cannot meet AA (text over a busy image with no overlay, a drag-only interaction, a hover-only reveal), **stop and tell the user** which criterion it fails and propose an alternative. Do not ship it silently.
+
+## 1. Semantic HTML first
+
+Decision rule: if a native element does the job, use it. It brings role, name, keyboard behaviour and focus for free.
+
+| Need | Use | Never |
+|---|---|---|
+| Action | `<button type="button">` | `<div onclick>`, `<a href="#">` |
+| Navigation | `<a href="/path">` | `<button>` that changes location |
+| Page regions | `<header> <nav> <main> <aside> <footer>`, one `<main>` | div soup |
+| Headings | `<h1>`–`<h6>` in order, no skipped levels for styling | bold `<div>` as heading |
+| Lists, tables | `<ul>/<ol>`, `<table>` with `<th scope>` and `<caption>` | grid of divs for tabular data |
+| Toggle | `<input type="checkbox">` or `<button aria-pressed>` | clickable span |
+| Disclosure | `<details><summary>` | custom JS when native fits |
+| Modal | `<dialog>` opened with `showModal()` | positioned div without focus trap |
+
+- Set `<html lang="...">` and a unique, descriptive `<title>` per page or route.
+- Images: meaningful → `alt` describing purpose; decorative → `alt=""`. Icon-only buttons need an accessible name (visible text, `aria-label`, or visually hidden text).
+- Add a "Skip to main content" link as the first focusable element on pages with repeated navigation.
+
+## 2. Keyboard and focus
+
+1. Everything that works with a mouse works with the keyboard: Tab/Shift+Tab to move, Enter/Space to activate, Escape to close, arrow keys inside composite widgets (tabs, menus, listboxes, radio groups).
+2. Tab order follows visual order. Never use positive `tabindex`. Use `tabindex="0"` only on custom interactive elements, `tabindex="-1"` for elements you focus from script.
+3. Focus is always visible. Never `outline: none` without a replacement; prefer `:focus-visible` styles with at least 3:1 contrast against the background.
+4. Focused elements must not be fully hidden by sticky headers, cookie banners or chat widgets (WCAG 2.4.11). Use `scroll-padding-top` for sticky headers.
+5. Focus management in dynamic UI:
+   - Opening a dialog moves focus into it; Tab stays inside; Escape closes; closing returns focus to the trigger.
+   - After client-side route changes, move focus to the new page's `<h1>` (or main) and update `<title>`.
+   - When an item is deleted, move focus to a sensible neighbour, not `<body>`.
+6. No keyboard traps, no actions that fire on focus alone.
+
+## 3. ARIA only when needed
+
+Rules, in order:
+1. No ARIA is better than wrong ARIA. Don't add `role="button"` to a `<button>`.
+2. If you build a custom widget, follow the matching WAI-ARIA Authoring Practices pattern completely: role, states (`aria-expanded`, `aria-selected`, `aria-checked`), keyboard model, and focus handling.
+3. Names: prefer visible text or `<label>`; then `aria-labelledby`; `aria-label` last. The accessible name must contain the visible label text (WCAG 2.5.3).
+4. Live updates (toasts, async results, form status): an `aria-live="polite"` region (or `role="status"`) that exists in the DOM **before** the message is inserted. Use `role="alert"` only for urgent errors.
+5. `aria-hidden="true"` never on focusable elements or their ancestors. Use `inert` to disable background content behind a non-native modal.
+
+## 4. Forms and errors
+
+- Every input has a programmatic label: `<label for>` or wrapping `<label>`. Placeholder is not a label.
+- Group related controls (radios, checkboxes, address parts) in `<fieldset>` with `<legend>`.
+- Use correct `type` and `autocomplete` tokens (`email`, `tel`, `given-name`, `current-password`, `one-time-code`) so browsers and password managers can fill fields.
+- Mark required fields in text or with a visible symbol explained on the page, plus `required` or `aria-required="true"`.
+- Errors:
+  1. Show the error text next to the field, linked with `aria-describedby`; set `aria-invalid="true"`.
+  2. Say what is wrong and how to fix it ("Enter a date like 31/12/2026"), not just "Invalid".
+  3. On submit with errors, move focus to the first invalid field or to an error summary that links to each field.
+  4. Never rely on colour alone (add an icon or text).
+- Don't ask again for information the user already entered in the same flow; prefill or offer to reuse it (3.3.7).
+- Login must not require a cognitive test such as solving a puzzle or transcribing characters unless there is an alternative; allow paste and password managers (3.3.8).
+
+## 5. Visual: contrast, size, zoom, motion
+
+- Text contrast at least 4.5:1; large text (at least 24px, or 18.66px bold) at least 3:1.
+- UI component boundaries, focus indicators, icons and chart lines that carry meaning: at least 3:1 against adjacent colours.
+- Pointer targets at least 24×24 CSS px, or enough spacing that a 24px circle around each does not overlap another (2.5.8). Inline links in sentences are exempt.
+- Content reflows at 320 CSS px wide (400% zoom) without two-dimensional scrolling; text resizes to 200% without loss. Use relative units and avoid fixed heights on text containers.
+- Respect `prefers-reduced-motion`: disable parallax, autoplay and large transitions. Anything that moves for more than 5 seconds needs pause/stop.
+- Dragging (sliders, sortable lists, maps) needs a single-pointer alternative such as buttons or inputs (2.5.7).
+- Check both light and dark themes, and hover, focus, disabled and error states.
+
+## 6. Test
+
+Run all three; automated tools catch only part of the problems.
+
+1. **Automated**: run the project's a11y lint, then axe against rendered pages or components. Example with Playwright:
+   ```ts
+   import AxeBuilder from '@axe-core/playwright';
+   const results = await new AxeBuilder({ page }).withTags(['wcag2a','wcag2aa','wcag21aa','wcag22aa']).analyze();
+   expect(results.violations).toEqual([]);
+   ```
+   Lighthouse's accessibility category also runs axe rules.
+2. **Keyboard pass**: unplug the mouse. Tab through the changed flow end to end. Check visible focus, order, traps, Escape, and return focus.
+3. **Screen reader pass** on the changed flow: VoiceOver (macOS/iOS), NVDA (Windows, free) or TalkBack (Android). Check names, roles, states, headings list, landmarks, and that errors and status messages are announced.
+4. Zoom to 200% and 400%, and check at 320px width.
+
+If you cannot run a screen reader in this environment, say so in the report; don't claim it passed.
+
+## Never
+
+- Never remove focus outlines without a visible replacement.
+- Never hide content from assistive tech that sighted users get, or the reverse, unless it is purely decorative.
+- Never disable zoom (`user-scalable=no`, `maximum-scale=1`).
+- Never add an accessibility overlay script as the fix.
+- Never claim "WCAG compliant" from an automated scan alone.
+
+## Report back
+
+```
+Changed: <files and components>
+Fixed:   <WCAG criterion> — <what was wrong> → <what changed>   (one line each)
+Checks:  axe <n violations before → after>, keyboard pass <done/not done>, screen reader <which one / not run>
+Open:    <issues needing design or product decisions>
+```

package/skills/web-accessibility/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Make this custom dropdown work with the keyboard and screen readers",
+    "Our signup form errors aren't announced by VoiceOver, fix the markup so they are",
+    "Build an accessible modal dialog component that traps focus and returns it on close",
+    "The grey button text fails contrast, help me get this page to WCAG 2.2 AA",
+    "Add axe checks to our Playwright tests and fix whatever violations they find"
+  ],
+  "should_not_trigger": [
+    "Audit this pull request for accessibility problems and list findings, don't change anything",
+    "Our LCP is 4 seconds on mobile, find out why the hero image loads so late",
+    "Set up design tokens and dark mode theming for our stylesheet",
+    "Write Playwright end-to-end tests for the checkout flow",
+    "Review this React component for unnecessary re-renders"
+  ]
+}

package/skills/web-performance/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: web-performance
+description: Measures and improves page speed against Core Web Vitals (LCP, INP, CLS) using field data from CrUX or real-user monitoring and lab runs in Lighthouse and DevTools, then fixes the actual bottleneck, whether that is image and font delivery, render-blocking resources, HTTP caching, or too much JavaScript on the main thread. Use when a site or page feels slow, a Lighthouse or PageSpeed Insights score dropped, Search Console flags poor Core Web Vitals, or a bundle or asset change needs a before-and-after measurement.
+license: MIT
+compatibility: Any Agent Skills host. Lab measurement needs Node and Chrome (Lighthouse CLI). Field data needs network access to PageSpeed Insights or the project's RUM tool.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: runs-commands
+  kete-loom/owner: "Kete-org"
+---
+
+# Web performance
+
+Measure, find the one thing that dominates, fix it, measure again. Never optimise from intuition.
+
+## Targets
+
+Core Web Vitals, judged at the 75th percentile of real page loads, split by mobile and desktop:
+
+| Metric | What it measures | Good | Poor |
+|---|---|---|---|
+| LCP (Largest Contentful Paint) | when the main content appears | ≤ 2.5 s | > 4.0 s |
+| INP (Interaction to Next Paint) | delay from input to the next frame | ≤ 200 ms | > 500 ms |
+| CLS (Cumulative Layout Shift) | unexpected movement of content | ≤ 0.1 | > 0.25 |
+
+TTFB and FCP are diagnostics for LCP, not goals on their own. A Lighthouse navigation run (the default, and what PageSpeed Insights' lab section shows) cannot measure INP because nobody interacts; use Total Blocking Time as the lab proxy, record a Lighthouse user-flow timespan or a DevTools Performance trace of the interaction to debug it, and confirm INP in the field.
+
+## 1. Measure first
+
+1. **Field data** (what users get): PageSpeed Insights for the URL and origin (CrUX), Search Console's Core Web Vitals report, or the project's RUM. If the project has none, suggest the `web-vitals` library sending `onLCP`, `onINP`, `onCLS` to an analytics endpoint.
+2. **Lab data** (to debug): `npx lighthouse <url> --preset=desktop` or the default mobile throttling, run 3–5 times and take the median. Use a production build, never the dev server.
+3. Record a baseline: metric values, page, device, build commit. Without a baseline, **stop**: you cannot prove the fix.
+4. If field and lab disagree, trust the field and find which pages, devices or interactions are slow.
+
+## 2. Diagnose by metric
+
+### LCP
+Break it into: TTFB → resource load delay → resource load time → render delay (DevTools Performance panel shows the LCP element and phases).
+- Slow TTFB: cache HTML at the CDN, fix slow server work, avoid redirect chains.
+- LCP image discovered late: put it in the HTML as `<img>` (not a CSS background or JS-inserted), add `fetchpriority="high"`, never `loading="lazy"` on it. Preload only if it can't be in the markup.
+- Large image: serve AVIF/WebP, `srcset` and `sizes` sized to the slot, compress.
+- Render delay: inline critical CSS or keep CSS small; `defer` or `async` non-critical scripts; avoid client-only rendering of above-the-fold content.
+
+### INP
+Find the slow interaction (RUM attribution or DevTools Performance with CPU throttling). Split it into input delay, processing time, presentation delay.
+- Long tasks (> 50 ms) block input: break work up and yield (`await scheduler.yield()` where supported, otherwise `setTimeout`), move heavy work to a Web Worker.
+- Do the visible update first, defer analytics and non-urgent work.
+- Large DOM and expensive re-renders: virtualise long lists, avoid layout thrash (read layout, then write), use `content-visibility: auto` for off-screen sections.
+- Third-party scripts (tag managers, chat, A/B tools) are frequent culprits: load them later or remove them.
+
+### CLS
+DevTools "Layout shift" track or RUM attribution names the shifting element.
+- Images, video, iframes and ads: set `width`/`height` attributes or `aspect-ratio`; reserve space for embeds and banners.
+- Web fonts: `font-display: swap` or `optional`, preload only the one or two critical font files, and use metric overrides (`size-adjust`, `ascent-override`) on the fallback to reduce reflow.
+- Never insert content above existing content after load unless it responds to user input.
+- Animate `transform` and `opacity`, not `top`, `height` or `margin`.
+- Make pages eligible for the back/forward cache (no `unload` handlers, no `Cache-Control: no-store` on HTML unless required).
+
+## 3. Common fixes across metrics
+
+**Images**: modern formats, responsive `srcset`, explicit dimensions, `loading="lazy"` and `decoding="async"` below the fold only.
+
+**Fonts**: self-host WOFF2, subset, limit families and weights, `preconnect` if a font CDN is used.
+
+**Caching**:
+- Fingerprinted static assets (`app.3f9a1c.js`): `Cache-Control: public, max-age=31536000, immutable`.
+- HTML: short `max-age` or `no-cache` with revalidation (`ETag`), so deploys show up.
+- Enable Brotli or gzip compression and HTTP/2 or HTTP/3 at the server or CDN.
+- `preconnect` to critical third-party origins, and no more than a few.
+
+**JavaScript cost**:
+1. Measure bundles with the build tool's analyzer (`vite-bundle-visualizer`, `webpack-bundle-analyzer`, `next build` output, `source-map-explorer`).
+2. Code-split by route and load rarely used features with dynamic `import()`.
+3. Replace heavy dependencies with smaller ones or platform APIs; check tree shaking works (ES modules, `sideEffects` set).
+4. Ship less hydration: server-render static parts and hydrate only interactive islands where the framework supports it.
+5. Set a budget (for example, JS per route in KB compressed) and fail CI when it is exceeded, if the project agrees.
+
+## 4. Verify
+
+1. Rebuild for production and repeat the exact measurement from step 1 (same URL, device, run count).
+2. Report before → after per metric. If a change didn't move the target metric, revert it unless it has another justification.
+3. Field data takes up to 28 days to show changes in CrUX; say so instead of claiming a field win from lab results.
+
+## Stop and ask the user
+
+- Before removing or delaying a third-party script (analytics, consent, ads, chat): it is usually a business decision.
+- Before changing CDN, cache headers on HTML, or server config you can't test locally.
+- Before swapping a framework or major dependency.
+
+## Never
+
+- Never optimise for the Lighthouse score while field metrics get worse.
+- Never lazy-load the LCP image or hide content to "improve" LCP.
+- Never measure on the dev server or with browser extensions active.
+- Never cache HTML as `immutable`.
+
+## Report back
+
+```
+Page/route:   <url>   Device: <mobile|desktop>   Data: <field|lab>
+Baseline:     LCP <s>  INP/TBT <ms>  CLS <n>   (commit <sha>)
+Bottleneck:   <metric> — <element or task> — <cause>
+Changes:      <file> — <what changed>   (one line each)
+After:        LCP <s>  INP/TBT <ms>  CLS <n>
+Not verified: <e.g. field INP pending CrUX update>
+```

package/skills/web-performance/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "PageSpeed Insights says our INP is poor on mobile, what is blocking the main thread?",
+    "The product page jumps around while loading, fix the layout shift",
+    "Our Lighthouse performance score dropped from 92 to 61 after the last release",
+    "Set long-lived cache headers for our hashed JS bundles and check the fonts aren't render-blocking",
+    "Search Console flags 300 URLs with poor Core Web Vitals, where do we start?"
+  ],
+  "should_not_trigger": [
+    "Benchmark these two JSON parsers in Node and tell me which is faster",
+    "Optimise this slow SQL query that powers the dashboard",
+    "Our page fails colour contrast and keyboard navigation checks",
+    "Reorganise our CSS with cascade layers so we can stop using !important",
+    "Reduce re-renders in this React list using memo and useCallback"
+  ]
+}

package/skills/web-scraping/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: web-scraping
+description: Responsible, reliable website scraping and crawling, checking robots.txt and the site's terms before fetching, looking for an official API or feed first, throttling requests with backoff and an identifying User-Agent, parsing static HTML with selectors versus driving a headless browser only when the page needs JavaScript, walking pagination, detecting layout changes, and storing raw responses separately from parsed records. Use when writing or fixing a scraper or crawler, extracting listings, prices or tables from web pages, a scraper suddenly returns empty fields or gets 429 or 403 responses, or deciding whether a site may be scraped at all.
+license: MIT
+compatibility: Any Agent Skills host. Needs network access to the target site and the project's language runtime; examples name Python (httpx, BeautifulSoup/lxml, Playwright) and Node (fetch, cheerio, Playwright) libraries.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: data
+  kete-loom/risk: network
+  kete-loom/owner: "Kete-org"
+---
+
+# Web scraping
+
+Collect data from websites in a way the site owner would tolerate, that keeps working when the page changes, and that never loses what was fetched.
+
+## 1. May we scrape this? (do this first)
+
+1. **Look for an official route**: a public API, data export, RSS/Atom feed, sitemap, or open-data download. If one exists, use it and stop here.
+2. **Read `robots.txt`** (`https://<host>/robots.txt`, format in RFC 9309). Follow the groups whose `User-agent` matches your crawler's product token (several matching groups are combined); use the `*` group only if no group matches. The longest matching path rule wins, and `Allow` should win a tie. If robots.txt returns 4xx, it places no restrictions; if it returns 5xx or cannot be reached, treat the whole site as disallowed. Fetch robots.txt separately for each scheme and host (with port): each serves its own file. Do not cache it for more than 24 hours. Honour `Crawl-delay` if present, even though RFC 9309 does not define it.
+3. **Read the terms of service** for clauses on automated access, scraping or reuse.
+4. **Stop and ask the user** before going further if any of these hold:
+   - robots.txt disallows the paths, or the terms forbid automated access;
+   - the data sits behind a login, paywall or CAPTCHA;
+   - the pages contain personal data (names, emails, phone numbers, profiles);
+   - the user plans to republish or sell the content, or to scrape at large volume.
+   These raise legal questions (contract terms, copyright and database rights, computer-misuse laws, data-protection laws such as GDPR) that vary by country. This skill does not give legal advice; tell the user a lawyer should review commercial or large-scale use.
+
+**Never**: bypass CAPTCHAs, logins you were not given, IP bans or other access controls; rotate proxies or spoof browsers to evade a block; collect personal data without a lawful reason the user has confirmed; or ignore a site's request to stop.
+
+## 2. Be polite
+
+- Identify yourself: a `User-Agent` such as `ExampleBot/1.0 (+https://example.com/bot; ops@example.com)`. Ask the user for the contact details.
+- One request at a time per host by default, with a delay (start at 1 to 2 seconds or the `Crawl-delay`). Never run parallel workers against one small site.
+- On `429` or `503`, honour `Retry-After`; otherwise back off exponentially with jitter, and stop after a few attempts. On repeated `403`, stop and report: it usually means you are blocked, and evading it is off the table.
+- Use conditional requests (`If-None-Match` / `If-Modified-Since` with the stored `ETag` / `Last-Modified`) and cache responses so reruns do not re-download.
+- Scrape off-peak for the site's time zone when volume is large.
+
+## 3. Choose the fetch method
+
+Decide in this order and take the first that works:
+
+1. **JSON behind the page**: open the browser's network panel; many sites load data from an XHR/fetch endpoint. If it is public and allowed, request it directly.
+2. **Static HTML**: if the data is in the raw response (`curl -s <url> | grep '<a known value>'`), use an HTTP client plus a parser (Python `httpx` + `selectolax`, `lxml` or BeautifulSoup; Node `fetch` + `cheerio`).
+3. **Embedded data**: look for `<script type="application/ld+json">`, `__NEXT_DATA__` or similar JSON in the HTML; parse that instead of the markup.
+4. **Headless browser** (Playwright) only when content is rendered by JavaScript and none of the above work. Wait for a specific selector, not a fixed sleep; block images and fonts to cut load; close pages and contexts.
+
+## 4. Parse robustly
+
+- Prefer stable hooks: `id`, `data-*` attributes, semantic tags, structured data. Avoid long positional XPaths and generated class names like `css-1x2y3z`.
+- Parse each record into a typed schema (dataclass, Pydantic, zod) and validate it; a missing required field is an error, not an empty string.
+- Normalize as a separate step: trim whitespace, parse prices into integer minor units plus currency, dates into ISO 8601 with time zone, resolve relative URLs against the page URL.
+- Keep the source URL and fetch timestamp on every record.
+
+## 5. Pagination and crawling
+
+- Follow the site's own next link or cursor parameter; stop when it disappears, a page returns zero items, or a page repeats the previous one's items.
+- Set a hard maximum page count and total request budget per run.
+- For crawls, keep a visited set keyed by normalized URL (lowercase host, drop fragments and tracking parameters), stay within the allowed host and path prefix, and prefer the sitemap for discovery.
+- Make runs resumable: persist the frontier and the last cursor.
+
+## 6. Store raw and parsed separately
+
+- **Raw**: the response body, status, headers, URL and fetch time, written once to object storage or disk (for example `raw/<host>/<YYYY-MM-DD>/<sha256 of URL>.html.gz`). Never overwrite it. Parser bugs are then fixed by re-parsing, not re-fetching.
+- **Parsed**: validated records in a table with a natural key (the site's item ID or canonical URL), upserted so reruns do not duplicate. Keep `first_seen` and `last_seen`.
+- Set a retention period for raw pages with the user, especially if they contain personal data.
+
+## 7. Detect change and breakage
+
+- After each run, compare against the previous run: record count, share of records with each required field, and new parse errors. Alert when they move beyond a threshold (for example count down 30% or a field's fill rate below 90%).
+- Keep a few saved HTML fixtures per page type and unit-test the parser against them; when the site changes, add the new page as a fixture before fixing the parser.
+- For content change monitoring, hash the normalized extracted content, not the whole page (ads and timestamps change every load).
+
+## Report back
+
+- Target site, permission findings (official API, robots.txt result, terms, personal data) and what the user decided.
+- Fetch method chosen and why; rate limit and User-Agent used.
+- Output schema, storage locations for raw and parsed data.
+- A sample run: pages fetched, records parsed, errors, and how long it took.
+- Known fragile selectors and the change-detection checks in place.

package/skills/web-scraping/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Scrape job listings from this careers site into a CSV, including all pages",
+    "My BeautifulSoup scraper suddenly returns empty titles since the site redesign",
+    "Am I allowed to scrape this marketplace, and how do I check robots.txt properly?",
+    "The crawler keeps getting HTTP 429 from the target site, how should I throttle it?",
+    "This page renders its table with JavaScript, should I use Playwright to extract it?"
+  ],
+  "should_not_trigger": [
+    "Click through our staging site and report any broken forms before the release",
+    "Audit our website's robots.txt and sitemap so Google indexes the right pages",
+    "Write Playwright end-to-end tests for our signup flow",
+    "Research and compare three vector databases with cited sources",
+    "Schedule the ingestion of our vendor's SFTP drop files into the warehouse every night"
+  ]
+}