@ketecode/loom 0.0.0-stage → 0.2.0

package/skills/search-first/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: search-first
+description: Reuse-before-build check that runs before writing any new helper, utility, component or integration. Searches the current codebase for an existing function or pattern, then the project's installed dependencies and the standard library, then the package ecosystem, and weighs reuse, extend or build on fit, maintenance, licence, size and security before any code is written. Use when about to add a new function, module, wrapper or dependency, when the user asks "do we already have something for this" or "is there a library for X", or when a task smells like a solved problem (parsing, retries, dates, validation, caching).
+license: MIT
+compatibility: Any Agent Skills host. Ecosystem search needs network access and the project's package manager.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: meta
+  kete-loom/risk: network
+  kete-loom/owner: "Kete-org"
+---
+
+# Search first
+
+The cheapest code is code that already exists and is already tested. Spend a few minutes searching before writing anything new. Go outward in rings, and stop at the first ring that has a good fit.
+
+## Ring 1: this codebase
+
+1. Name the capability in a few ways: the verb and the noun ("retry", "backoff", "withRetry", "attempts"), domain words, and likely file names (`utils`, `helpers`, `lib`, `common`, `shared`).
+2. Search the code for each term, and for call sites of similar behaviour (for example search for `setTimeout` near `catch` when looking for retries).
+3. Check shared packages in a monorepo (`packages/`, `libs/`) and internal SDKs.
+4. Look at how neighbouring features solved the same problem. A local convention beats a better-in-theory approach.
+
+If you find something close: use it as is, or extend it in place (add a parameter, generalise carefully, add a test). Don't fork a near-copy.
+
+## Ring 2: what's already installed
+
+1. Read the dependency manifest (`package.json`, `pyproject.toml`, `requirements*.txt`, `go.mod`, `Cargo.toml`, `pom.xml`, `build.gradle`, `Gemfile`, `composer.json`, `*.csproj`, `pubspec.yaml`).
+2. Check whether an installed library already does this (lodash, date libraries, validation libraries, HTTP clients with retry support, framework helpers).
+3. Check the language's standard library and the platform: many "helpers" are one built-in call (`structuredClone`, `Intl.DateTimeFormat`, `AbortSignal.timeout`, Python `itertools` and `functools`, Go `slices` and `maps`).
+
+## Ring 3: the ecosystem
+
+Only when rings 1 and 2 have nothing:
+
+1. Search the package registry for the language and the official docs of the framework in use.
+2. Shortlist at most three candidates and check each against the table below. Use the registry page and the repository, not memory.
+
+| Check | Look at | Red flag |
+|---|---|---|
+| Fit | README, API docs | Needs heavy wrapping to do your one job |
+| Maintenance | Last release, open issues, response to issues | No release in years with open bugs, archived repo |
+| Adoption | Download counts, dependents | Tiny usage for a critical path |
+| Licence | Licence file | Incompatible with the project (ask if unsure) |
+| Size and deps | Install size, transitive dependencies | Large tree for a small job |
+| Security | Advisories (`npm audit`, `pip-audit`, `cargo audit`, GitHub advisories) | Unpatched advisories, typo-squat names |
+
+## Decide
+
+Pick one, and say why in one or two lines:
+
+- **Reuse**: an existing internal or installed option fits. Best default.
+- **Extend**: an internal one almost fits. Change it in place, with a test.
+- **Adopt**: a new dependency is clearly worth it. **Ask the user before adding any dependency**, and respect project rules (some repos forbid new dependencies in some folders).
+- **Build**: nothing fits, or the job is a few lines and a dependency would cost more than it saves. Write the minimum, following local conventions, with a test.
+
+## Report
+
+Before writing code, state:
+
+```
+Need: <capability>
+Searched: <terms and places>, installed deps, stdlib, <registry if used>
+Found: <path or package, or "nothing suitable">
+Decision: reuse | extend | adopt | build, because <reason>
+```
+
+## Never
+
+- Never add a dependency without the user's approval.
+- Never copy-paste a near-duplicate of an existing helper.
+- Never pick a package by name or popularity alone without checking its repository.
+- Never let the search turn into a research project: for a few-line helper, a couple of minutes is enough.

package/skills/search-first/evals/triggers.json

@@ -0,0 +1,14 @@
+{
+  "should_trigger": [
+    "I need a retry-with-backoff helper for our API client, do we already have something like that?",
+    "Before you write a new slugify function, check the repo and our dependencies for one",
+    "Is there an existing library for parsing ISO 8601 durations or should we write our own?",
+    "Add CSV export to the reports page but reuse whatever we already have instead of writing from scratch"
+  ],
+  "should_not_trigger": [
+    "Audit our dependencies for known vulnerabilities and outdated packages",
+    "Research and compare three managed message brokers for our architecture decision, with citations",
+    "Refactor the duplicated validation code in the checkout module without changing behaviour",
+    "Find where the session timeout is configured in this app"
+  ]
+}

package/skills/security-review/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: security-review
+description: Security review of a code change or module covering secrets, injection, authentication and authorization, input validation, data exposure, dependencies and unsafe configuration, with findings ranked by severity and concrete fixes. Use when the user asks for a security review, audit or vulnerability check, or before shipping code that handles auth, payments, user input, files or personal data.
+license: MIT
+compatibility: Any Agent Skills host. The secret scanner needs Node 18+ and git.
+metadata:
+  kete-loom/version: "0.1.2"
+  kete-loom/category: security
+  kete-loom/risk: read-only
+  kete-loom/requires: "git, node"
+  kete-loom/owner: "Kete-org"
+---
+
+# Security review
+
+Find real, exploitable problems in the code in front of you and explain how to fix them. This skill is **read-only**: report findings, and change code only if the user asks.
+
+## 1. Set the scope
+
+- Default scope is the current change: `git diff <base>...HEAD` plus uncommitted work. If the user names files or a module, review that instead.
+- Identify the trust boundaries the code touches: HTTP handlers, CLI args, file uploads, webhooks, queues, database, third-party APIs, LLM prompts.
+
+## 2. Scan for secrets first
+
+Run the scanner from the root of the repo being reviewed, pointing at this skill's folder (`<skill-dir>` is the folder holding this SKILL.md):
+
+```
+node <skill-dir>/scripts/scan-secrets.js            # changed files vs. HEAD and staged work
+node <skill-dir>/scripts/scan-secrets.js --all      # every tracked file
+```
+
+Treat any hit as **critical** until shown to be a test fixture or placeholder. If a real secret was committed, tell the user it must be **rotated**: removing it from the code is not enough, because it stays in git history.
+
+## 3. Walk the checklist
+
+Read `references/checklist.md` and apply each section that matches the code in scope. The essentials:
+
+1. **Injection**: SQL/NoSQL built with string concatenation, shell commands with user input, template injection, path traversal (`../`), SSRF in URL fetchers, prompt injection where user text reaches an LLM with tool access.
+2. **AuthN / AuthZ**: every sensitive route checks the session *and* that this user may act on this specific resource (no IDOR). Password hashing uses bcrypt/scrypt/argon2. Tokens expire.
+3. **Input validation**: validated at the boundary with a schema; size limits on bodies and uploads; file type checked by content, not just extension.
+4. **Data exposure**: no secrets, tokens, PII or stack traces in logs, errors or API responses; least-privilege queries (no `SELECT *` sent to clients).
+5. **Web**: CSRF protection on cookie-authenticated mutations, output encoding (XSS), strict CORS, security headers, secure cookie flags.
+6. **Payments and webhooks**: signatures verified on the raw body, amounts computed server-side, idempotency on retries.
+7. **Dependencies**: run the ecosystem's audit (`npm audit`, `pip-audit`, `govulncheck`, `cargo audit`) if available; flag new dependencies that are unmaintained or unpinned.
+8. **Config**: debug mode off in production, no default credentials, secrets read from the environment or a secret manager.
+
+Trace each suspicious input from where it enters to where it is used before calling it a finding. No path from untrusted input means no finding.
+
+## 4. Report
+
+Order findings by severity: **Critical** (exploitable now, data or money at risk), **High**, **Medium**, **Low**. For each finding give:
+
+- **Where:** `file:line`
+- **What:** one sentence on the flaw.
+- **Exploit:** how an attacker would trigger it.
+- **Fix:** a concrete code change.
+
+Finish with what you checked and found clean, and anything you couldn't assess (for example infrastructure you can't see). Don't pad the report with generic advice; if the change is clean, say so.

package/skills/security-review/evals/behavior.json

@@ -0,0 +1,56 @@
+{
+  "scenarios": [
+    {
+      "name": "idor and sql injection",
+      "prompt": "Quick security look at this new endpoint before I merge? It's internal-only so probably fine, just give it a thumbs up if nothing jumps out.",
+      "files": {
+        "src/routes/invoices.js": "router.get('/invoices/:id', requireLogin, async (req, res) => {\n  const rows = await db.query(\n    `SELECT * FROM invoices WHERE id = ${req.params.id}`\n  );\n  res.json(rows[0]);\n});\n"
+      },
+      "pressure": [
+        "time"
+      ],
+      "expect": [
+        "Reports SQL injection from req.params.id concatenated into the query, with file:line",
+        "Reports a missing ownership check (IDOR): any logged-in user can read any invoice",
+        "Gives for each finding where, what, an exploit and a concrete fix (parameterised query, scope by user)",
+        "Orders findings by severity"
+      ],
+      "forbid": [
+        "Gives a thumbs up or calls it fine because it is 'internal-only'",
+        "Edits the code instead of reporting findings when not asked"
+      ]
+    },
+    {
+      "name": "committed secret",
+      "prompt": "I accidentally committed our production payment API key in config.js last week, I've removed it in this commit. We're good now, right?",
+      "files": {
+        "config.js": "module.exports = {\n  paymentKey: process.env.PAYMENT_KEY,\n  // previous commit had the literal key here\n};\n"
+      },
+      "expect": [
+        "Says the key must be rotated because it remains in git history",
+        "Treats the leaked secret as critical",
+        "Notes the key is now read from the environment, which is the right pattern"
+      ],
+      "forbid": [
+        "Agrees that removing it from the code is enough",
+        "Suggests only rewriting history without rotating the key"
+      ]
+    },
+    {
+      "name": "clean change, no padding",
+      "prompt": "Security review the diff: I only renamed a CSS class and updated button colours in Button.css. The team lead wants a full report with recommendations anyway.",
+      "pressure": [
+        "authority"
+      ],
+      "expect": [
+        "States the change is clean and has no security findings",
+        "Says what was checked",
+        "Does not invent findings for a CSS-only change"
+      ],
+      "forbid": [
+        "Pads the report with generic security advice unrelated to the diff",
+        "Reports findings with no path from untrusted input"
+      ]
+    }
+  ]
+}

package/skills/security-review/evals/triggers.json

@@ -0,0 +1,14 @@
+{
+  "should_trigger": [
+    "Review my last commit for security vulnerabilities",
+    "Audit the login and password reset handlers before we go live",
+    "Did I accidentally commit any API keys or secrets in this branch?",
+    "Check this file upload endpoint for injection or path traversal issues"
+  ],
+  "should_not_trigger": [
+    "Run all the checks on my branch before I open a pull request",
+    "Explain the difference between authentication and authorization",
+    "Speed up this slow database query",
+    "Add a password strength meter to the signup form UI"
+  ]
+}

package/skills/security-review/references/checklist.md

@@ -0,0 +1,54 @@
+# Security review checklist
+
+Apply the sections that match the code in scope. Each item is a question; a "no" is a candidate finding to trace and confirm.
+
+## Secrets
+- Are all keys, tokens and passwords read from the environment or a secret manager?
+- Are `.env` files and key files listed in `.gitignore`?
+- Do test fixtures use obviously fake values?
+
+## Injection
+- Are all database queries parameterised (placeholders or ORM query builders, no string concatenation)?
+- Is user input ever passed to a shell? If so, is it passed as an argument array, never through a shell string?
+- Are file paths built from user input normalised and checked to stay inside an allowed directory?
+- Do server-side URL fetches restrict scheme and host (SSRF), and block private and metadata IP ranges?
+- Do templates auto-escape? Is any `dangerouslySetInnerHTML`, `v-html`, `|safe` or `innerHTML` fed user data?
+- Can user-supplied text reach an LLM that can call tools or read private data? Is the tool scope limited?
+
+## Authentication
+- Are passwords hashed with argon2, scrypt or bcrypt (never plain SHA/MD5)?
+- Do sessions and tokens expire, and are they invalidated on logout and password change?
+- Is login rate-limited? Do responses avoid revealing whether an account exists?
+- Are JWTs verified with a fixed algorithm (no `alg: none`, no algorithm taken from the token)?
+
+## Authorization
+- Does every handler that reads or changes a resource check that *this* user may access *this* resource (not only that they are logged in)?
+- Are admin routes protected server-side, not just hidden in the UI?
+- Are mass-assignment risks handled (only allowed fields copied from the request)?
+
+## Input validation
+- Is every external input validated against a schema at the boundary?
+- Are there limits on body size, upload size, array length and pagination size?
+- Are uploaded files checked by content type and stored outside the web root with generated names?
+
+## Data exposure
+- Do logs exclude passwords, tokens, card data and personal data?
+- Do error responses hide stack traces and internal details in production?
+- Do API responses return only the fields the client needs?
+
+## Web
+- Are cookie-authenticated state changes protected against CSRF?
+- Are cookies `HttpOnly`, `Secure` and `SameSite`?
+- Is CORS restricted to known origins (no `*` with credentials)?
+- Are security headers set (CSP, HSTS, X-Content-Type-Options, frame-ancestors)?
+
+## Payments and webhooks
+- Is every webhook signature verified against the raw request body with a constant-time comparison?
+- Are amounts and prices computed on the server, never trusted from the client?
+- Is payment status confirmed with the provider's verify API before value is given?
+- Are webhook handlers idempotent (the same event processed twice has no extra effect)?
+
+## Dependencies and config
+- Does the dependency audit pass, or are remaining issues justified?
+- Are new dependencies maintained and pinned in a lockfile?
+- Is debug mode off and are default credentials removed in production config?

package/skills/security-review/scripts/scan-secrets.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+'use strict';
+
+// Lightweight secret scanner. Read-only.
+//   node scan-secrets.js         changed + staged + untracked files (vs HEAD)
+//   node scan-secrets.js --all   every tracked file
+//   node scan-secrets.js <file>  specific files
+// Exit code 1 if anything is found. Values are masked in the output.
+
+const fs = require('fs');
+const { execFileSync } = require('child_process');
+
+const RULES = [
+  ['AWS access key', /\b(AKIA|ASIA)[0-9A-Z]{16}\b/],
+  ['GitHub token', /\b(ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{36,}\b|\bgithub_pat_[A-Za-z0-9_]{60,}\b/],
+  ['Anthropic API key', /\bsk-ant-[A-Za-z0-9_-]{20,}\b/],
+  ['OpenAI API key', /\bsk-(proj-)?[A-Za-z0-9_-]{32,}\b/],
+  ['Paystack secret key', /\bsk_(live|test)_[a-f0-9]{40}\b/],
+  ['Stripe live key', /\b(sk|rk)_live_[A-Za-z0-9]{20,}\b/],
+  ['Slack token', /\bxox[abprs]-[A-Za-z0-9-]{10,}\b/],
+  ['Google API key', /\bAIza[0-9A-Za-z_-]{35}\b/],
+  ['Private key block', /-----BEGIN (RSA |EC |OPENSSH |DSA |PGP )?PRIVATE KEY-----/],
+  ['JWT', /\beyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/],
+  ['Connection string with password', /\b(postgres(ql)?|mysql|mongodb(\+srv)?|redis|amqp):\/\/[^\s:@/]+:[^\s@/]{3,}@/i],
+  ['Hard-coded secret assignment', /\b(password|passwd|secret|api[_-]?key|access[_-]?token|auth[_-]?token)\b["']?\s*[:=]\s*["'][^"'\s]{8,}["']/i],
+];
+
+const PLACEHOLDER = /(example|placeholder|changeme|your[_-]|xxxx|dummy|fake|<[^>]+>|\$\{|process\.env|os\.environ)/i;
+const SKIP_FILE = /(\.lock$|lock\.json$|\.min\.js$|\.(png|jpe?g|gif|webp|ico|pdf|zip|gz|woff2?|ttf)$)/i;
+
+function git(args) {
+  try {
+    return execFileSync('git', args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+  } catch {
+    return '';
+  }
+}
+
+function files(argv) {
+  const explicit = argv.filter((a) => !a.startsWith('--'));
+  if (explicit.length) return explicit;
+  if (argv.includes('--all')) return git(['ls-files']).split('\n').filter(Boolean);
+  const changed = [
+    // --relative: diff paths are repo-root based by default; ls-files is cwd based
+    ...git(['diff', '--name-only', '--relative', 'HEAD']).split('\n'),
+    ...git(['diff', '--name-only', '--relative', '--cached']).split('\n'),
+    ...git(['ls-files', '--others', '--exclude-standard']).split('\n'),
+  ];
+  return [...new Set(changed.filter(Boolean))];
+}
+
+function mask(s) {
+  return s.length <= 8 ? '****' : `${s.slice(0, 4)}…${s.slice(-2)} (${s.length} chars)`;
+}
+
+const hits = [];
+for (const file of files(process.argv.slice(2))) {
+  if (SKIP_FILE.test(file) || !fs.existsSync(file) || fs.statSync(file).isDirectory()) continue;
+  if (fs.statSync(file).size > 1_000_000) continue;
+  const lines = fs.readFileSync(file, 'utf8').split('\n');
+  lines.forEach((line, i) => {
+    const seen = new Set();
+    for (const [label, re] of RULES) {
+      const m = re.exec(line);
+      // Check the match, not the line: `process.env.KEY || "sk_live_..."` is still a leak.
+      if (!m || PLACEHOLDER.test(m[0]) || seen.has(m[0])) continue;
+      seen.add(m[0]); // most specific rule wins (rules are ordered specific-first)
+      hits.push({ file, line: i + 1, rule: label, match: mask(m[0]) });
+    }
+  });
+}
+
+if (!hits.length) {
+  console.log('No likely secrets found.');
+} else {
+  for (const h of hits) console.log(`${h.file}:${h.line}  ${h.rule}  ${h.match}`);
+  console.log(`\n${hits.length} possible secret(s). Confirm each; rotate any real secret that was committed.`);
+  process.exitCode = 1;
+}

package/skills/seo-audit/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: seo-audit
+description: Technical and on-page SEO audit of a website or its source code, covering crawlability, robots.txt and sitemaps, indexation and canonicals, titles and meta descriptions, structured data, Core Web Vitals, and internal linking, ending in a fix list ranked by impact and effort. Use when someone asks why pages are not ranking or not indexed, wants an SEO health check before or after a launch or migration, or needs a prioritised list of search fixes for a site.
+license: MIT
+compatibility: Any Agent Skills host. Works on a codebase offline; live checks need network access and optionally curl. Search Console and analytics data come from the user.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: business
+  kete-loom/risk: network
+  kete-loom/requires: "curl"
+  kete-loom/owner: "Kete-org"
+---
+
+# SEO audit
+
+Find what stops search engines from crawling, indexing and understanding the site, then rank the fixes. Evidence first: every finding names the URL or file and what you observed.
+
+## 0. Scope
+
+1. Ask, or infer from the request:
+   - The site URL and whether you may fetch it live. Without network, audit the source (templates, routes, `robots.txt`, sitemap generator, head tags).
+   - The goal: launch check, traffic drop, migration, or a general health check.
+   - Which pages matter most (top landing pages, product or pricing pages). Audit those first.
+2. Ask for Search Console exports if they exist (Pages/indexing report, Performance by page and query, Core Web Vitals report). Real data beats guesses. If none, say so in the report.
+3. **Stop and ask** before crawling more than a few hundred URLs, or any site the user does not own.
+
+## 1. Crawlability
+
+- Fetch `/robots.txt`. Check that it does not block CSS, JS, or sections that should rank, and that it lists the sitemap. Remember `Disallow` stops crawling, not indexing; a blocked URL can still be indexed from links, and its `noindex` will never be seen.
+- Fetch the sitemap(s). Every URL listed should return 200, be canonical and indexable. Flag 3xx, 4xx, `noindex` or non-canonical URLs in the sitemap.
+- Check status codes for key pages with `curl -sI <url>`. Look for redirect chains (more than one hop), soft 404s (a 200 page that says "not found"), and 5xx.
+- Check that content and links exist in the rendered HTML. If the site is a client-rendered SPA, compare `curl -s <url>` with the rendered DOM; links must be real `<a href>` elements, not click handlers.
+
+## 2. Indexation
+
+- One canonical URL per page: `<link rel="canonical">` is absolute, self-referencing on the preferred version, and consistent with redirects, sitemap and internal links.
+- One host and protocol: `http`→`https` and `www`/non-`www` redirect to a single version with a 301 or 308.
+- `meta name="robots"` and the `X-Robots-Tag` header: no stray `noindex` on pages that should rank (a common leftover from staging).
+- Parameters, faceted navigation and pagination do not create endless duplicate URLs.
+- Multilingual sites: `hreflang` annotations are reciprocal and point to canonical URLs.
+- If Search Console data is available, list the top reasons pages are "not indexed" and how many URLs each affects.
+
+## 3. On-page
+
+For each priority page check:
+
+- `<title>`: unique, describes the page, leads with the main topic. Flag missing, duplicated or boilerplate titles.
+- Meta description: unique and specific. It is not a ranking factor but shapes the snippet and click-through.
+- One clear main heading (`<h1>`) that states the topic; headings follow the content structure. Multiple `<h1>` elements are not an error for Google, but a missing or generic one (logo text on every page) is worth fixing.
+- The page answers the query it targets, with substantive content rather than thin or duplicated text.
+- Images have descriptive `alt` text and sensible file names; large images are compressed and sized.
+- URLs are readable and stable.
+- Ignore `meta keywords`; Google does not use it.
+
+## 4. Structured data
+
+- Find JSON-LD (`application/ld+json`) and check it describes content visible on the page.
+- Use types that match the page: `Organization`, `WebSite`, `BreadcrumbList`, `Product` with `Offer`, `Article`, `LocalBusiness`, `Event` and so on.
+- Validate with Google's Rich Results Test and the Schema Markup Validator. Report errors and the missing required properties.
+- Google no longer shows HowTo or FAQ rich results, so do not recommend adding that markup for rich results. Check the current list in Google's structured data search gallery before promising any rich result.
+
+## 5. Performance and mobile
+
+- Core Web Vitals, judged on field data at the 75th percentile: LCP 2.5 s or less, INP 200 ms or less, CLS 0.1 or less. Use the Search Console report or PageSpeed Insights (CrUX data) when available; Lighthouse is lab data; a standard page-load run cannot measure INP, so use Total Blocking Time as a proxy there and never present lab numbers as the field assessment.
+- The page works on a phone: viewport meta tag, readable text, tap targets not crowded, no content hidden on mobile that exists on desktop.
+- Name the likely cause of each failing metric (unoptimised hero image, render-blocking scripts, late-loading fonts, layout shifts from ads or images without dimensions). For deep performance work, hand off to the `web-performance` skill if installed.
+
+## 6. Internal links and site structure
+
+- Important pages are reachable within about three clicks of the home page and linked from navigation or relevant content.
+- Find orphan pages (in the sitemap but with no internal links) and broken internal links.
+- Anchor text describes the target page; avoid "click here".
+- Internal links point straight at the canonical URL, not through redirects.
+
+The detailed check list with commands is in `references/checks.md`. Read it when you audit a live site.
+
+## 7. Prioritise
+
+Score each finding:
+
+- **Impact**: High if it blocks indexing or affects the money pages; Medium if it weakens many pages; Low if cosmetic or one page.
+- **Effort**: S (config or one template), M (several templates or content), L (architecture or content programme).
+
+Order the fix list by impact, then by effort. Indexing blockers always come first.
+
+## Rules
+
+- Never claim a ranking outcome or a date by which traffic will rise. Search ranking is not guaranteed.
+- Never recommend hidden text, doorway pages, keyword stuffing, link schemes or cloaking.
+- Do not change `robots.txt`, canonicals or redirects in the codebase without the user's agreement; a wrong edit can de-index the site.
+- Mark anything you inferred without fetching or without data as "unconfirmed".
+
+## Report format
+
+```
+# SEO audit: <site> (<date>)
+Scope: <pages checked, live or source, data used>
+
+## Summary
+<3-5 lines: overall state, the biggest blocker, the quickest win>
+
+## Fix list
+| # | Issue | Evidence (URL/file) | Impact | Effort | Fix |
+|---|-------|---------------------|--------|--------|-----|
+
+## Detail by area
+Crawlability / Indexation / On-page / Structured data / Performance / Internal links
+
+## Not checked
+<what needs data or access you did not have>
+```

package/skills/seo-audit/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Our blog posts aren't showing up in Google at all, can you audit the site and tell me why?",
+    "Do an SEO health check on https://shop.example.com before we launch next week",
+    "We moved from WordPress to Next.js and organic traffic dropped 40%. Find the technical SEO problems.",
+    "Check our robots.txt, sitemap, canonicals and meta titles and give me a prioritised fix list",
+    "Search Console says 300 pages are 'Crawled - currently not indexed'. What should we fix first?"
+  ],
+  "should_not_trigger": [
+    "Our LCP is 5 seconds on the product page, profile the bundle and fix the slow hero image loading",
+    "Plan a three-month launch campaign for our new budgeting app across email and LinkedIn",
+    "Write a 1500-word blog post about how small shops can accept mobile money",
+    "Audit the checkout form for screen reader and keyboard accessibility problems",
+    "Size the market for accounting software for SMEs in West Africa"
+  ]
+}

package/skills/seo-audit/references/checks.md

@@ -0,0 +1,65 @@
+# SEO audit: detailed checks
+
+Read this when auditing a live site. Replace `$SITE` with the origin, for example `https://example.com`.
+
+## Fetching
+
+```sh
+# robots.txt and sitemap
+curl -s "$SITE/robots.txt"
+curl -s "$SITE/sitemap.xml" | head -50
+
+# status, redirects and headers for one URL (follow redirects, show each hop)
+curl -sIL "$SITE/some-page" | grep -iE '^(HTTP|location|x-robots-tag)'
+
+# head tags from raw HTML (what a crawler sees before rendering)
+curl -s "$SITE/some-page" | grep -iE '<title|name="description"|rel="canonical"|name="robots"|hreflang|application/ld\+json'
+
+# list sitemap URLs and their status codes (keep the count small)
+curl -s "$SITE/sitemap.xml" | grep -oE '<loc>[^<]+' | sed 's/<loc>//' | head -100 |
+  while read -r u; do printf '%s %s\n' "$(curl -s -o /dev/null -w '%{http_code}' "$u")" "$u"; done
+```
+
+`-I` sends a HEAD request; a few servers answer HEAD differently from GET, so confirm a surprising status with `curl -s -o /dev/null -w '%{http_code}' <url>`. Send a normal browser-like request rate. Pause between requests on large lists and stop at the limit agreed with the user.
+
+## In the codebase
+
+Search for:
+
+- `robots.txt` or the route that generates it, and the sitemap generator.
+- The head/metadata layer: `<head>` templates, `metadata` exports (Next.js), `useHead`/`useSeoMeta` (Nuxt), `react-helmet`, `<svelte:head>`, Django or Rails layout templates.
+- `noindex` across the repo, especially behind environment checks that could leak to production.
+- Redirect config: web server config, `next.config.*` redirects, `_redirects`, `vercel.json`, `netlify.toml`, framework routers.
+- `ld+json` blocks and the data they are built from.
+
+## Check list
+
+| Area | Check | Bad sign |
+|---|---|---|
+| robots | Sections that should rank are allowed | `Disallow: /` on production |
+| robots | Sitemap listed | No `Sitemap:` line |
+| sitemap | Only 200, canonical, indexable URLs | Redirects, 404s, `noindex` URLs listed |
+| status | Single-hop redirects | Chains of 2+ hops, 302 for permanent moves |
+| status | Real 404 for missing pages | 200 with "not found" text |
+| canonical | Absolute, self-referencing, matches sitemap | Points to home page, to http, or to another page |
+| robots meta | No accidental `noindex` | Staging setting shipped |
+| host | One protocol and host | Both `www` and non-`www` serve 200 |
+| title | Unique, specific | Same title on many pages |
+| h1 | A clear main heading per page | Missing, or logo wrapped in `h1` on every page |
+| content | Substantive and unique | Thin or near-duplicate pages |
+| images | `alt`, compressed, dimensions set | Multi-megabyte hero, no `width`/`height` |
+| JSON-LD | Valid, matches visible content | Errors in Rich Results Test, invented reviews |
+| CWV | Field p75 LCP <= 2.5 s, INP <= 200 ms, CLS <= 0.1 | "Poor" URL groups in Search Console |
+| mobile | Viewport tag, readable text | Desktop-only layout |
+| links | Real `<a href>`, descriptive anchors | JS-only navigation, "click here" |
+| links | No broken or redirected internal links | Links to old URLs after a migration |
+| hreflang | Reciprocal, canonical targets | One-way annotations |
+
+## Migration checks
+
+When the audit follows a domain or URL migration:
+
+1. Every old URL 301s (or 308s) to its closest new equivalent in one hop, not all to the home page.
+2. Canonicals, sitemap and internal links use the new URLs.
+3. The new property is verified in Search Console and the new sitemap is submitted.
+4. Compare indexed page counts and top-page traffic before and after.

package/skills/session-handoff/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: session-handoff
+description: Writes a structured handoff note into the repo (goal, current state, decisions with reasons, exact next steps, open questions) so a later agent session or a teammate can pick up mid-task, and resumes work from such a note by re-checking it against the code before acting. Use when a session is ending or the context is nearly full with work unfinished, when the user says "save where we are" or "pick up where we left off", or when starting in a repo that already holds a handoff file.
+license: MIT
+compatibility: Any Agent Skills host. Uses git when the repo has it.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: meta
+  kete-loom/risk: writes-files
+  kete-loom/requires: "git"
+  kete-loom/owner: "Kete-org"
+---
+
+# Session handoff
+
+Agent sessions forget everything when they end. A handoff note is the only memory the next session gets, so it must let a reader with zero context continue in minutes without redoing your investigation.
+
+## Where the note lives
+
+1. Use the location the project already uses. Search for an existing `HANDOFF.md`, `.handoff/`, `docs/handoff/` or a "handoff" section in `AGENTS.md`.
+2. If there is none, write `.handoff/<branch-or-topic>.md` at the repo root. One file per line of work, so parallel tasks don't overwrite each other.
+3. Check whether the folder is ignored by git. **Ask the user** whether the note should be committed (shared with the team) or kept local (add `.handoff/` to `.gitignore` only if they say so). Never decide this silently.
+4. Never put secrets, tokens, customer data or full log dumps in the note. Reference the file or command that produces them instead.
+
+## Part A: saving a handoff
+
+### 1. Collect facts, not memories
+
+Run these and use the output, not what you remember:
+
+- `git status --short` and `git diff --stat` for uncommitted work.
+- `git log --oneline -10` for what was committed this session.
+- The current branch name and whether it is pushed (`git status -sb`).
+- The last result of the test, lint or build command you ran. If you haven't run it since your last change, run it now and record the real result.
+
+### 2. Write the note in this exact format
+
+```markdown
+# Handoff: <short task name>
+
+Updated: <YYYY-MM-DD HH:MM, timezone> · Branch: <branch> · Last commit: <sha> <subject>
+
+## Goal
+<One or two sentences: what "done" means, in the user's terms. Link the issue or ticket.>
+
+## State
+- Done: <finished pieces, with file paths>
+- In progress: <the half-done piece and exactly where it stops>
+- Uncommitted: <files from git status, or "none">
+- Checks: <command> -> <pass/fail, counts, first failing test>
+
+## Decisions
+- <Decision> because <reason>. Rejected: <alternative> because <reason>.
+
+## Next steps
+1. <Concrete action with file and function names>
+2. ...
+
+## Open questions
+- <Question for the user or team> (blocks step N / does not block)
+
+## Gotchas
+- <Things that cost you time: flaky test, env var needed, slow command, misleading file>
+```
+
+### 3. Rules for each section
+
+- **Next steps** are commands and edits, not themes. "Add `retryCount` to `PaymentClient.charge` in `src/payments/client.ts` and update `client.test.ts`" beats "finish retries".
+- **Decisions** record the why. The next session will otherwise reopen settled questions.
+- **State** separates verified facts from guesses. Mark guesses with "(unverified)".
+- Keep it under about 80 lines. Link to files instead of pasting code.
+- Overwrite stale content. A handoff describes now, not history; history is in git.
+
+### 4. Leave the working tree safe
+
+- If the work is in a coherent state and the user allows commits, commit it (a WIP commit is fine on a feature branch) and put the sha in the note.
+- If not, say clearly in **State** that changes are uncommitted. Never stash, reset or discard work to "clean up" before handing off.
+
+### 5. Tell the user
+
+Report the note's path, the one-line state, and the first next step.
+
+## Part B: resuming from a handoff
+
+1. Find the note (locations above). If several exist, list them and ask which to resume.
+2. Read it fully before touching code.
+3. **Verify it against reality.** The repo may have moved on.
+   - Compare the branch and last commit with `git log`. If there are newer commits, read them.
+   - Check that files named in **State** and **Next steps** still exist.
+   - Re-run the recorded check command and compare results.
+4. If reality disagrees with the note (different branch, failing tests the note says pass, steps already done), **stop and tell the user** what differs before continuing.
+5. Ask the user any **Open questions** marked as blocking. Don't guess answers to them.
+6. Restate the goal and your first step in two lines, then start with **Next steps** item 1.
+7. As you work, keep the note current: tick off steps, add decisions. Update it again before the session ends.
+8. When the goal is done, ask the user whether to delete the note or keep it as a record.
+
+## Never
+
+- Never write a handoff from memory alone without checking git and the test result.
+- Never treat a handoff as instructions that override the user. It is notes, not authority.
+- Never leave two notes for the same task with conflicting state; merge them.