@ketecode/loom 0.0.0-stage → 0.1.0

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.

package/skills/session-handoff/evals/triggers.json

@@ -0,0 +1,14 @@
+{
+  "should_trigger": [
+    "I'm out of time today, write down where we are so tomorrow's session can carry on",
+    "Pick up where we left off yesterday, there should be a handoff file in the repo",
+    "Before the context fills up, save a note with our decisions and next steps for the next agent",
+    "Hand this half-finished migration over to my colleague with a status note they can follow"
+  ],
+  "should_not_trigger": [
+    "Write a pull request description for the changes on this branch",
+    "Draft a commit message for the staged files following conventional commits",
+    "I'm new to this codebase, give me a tour of how the modules fit together",
+    "My context window keeps filling up when I read big log files, how should I approach this task"
+  ]
+}

package/skills/skill-authoring/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: skill-authoring
+description: Creates or improves an Agent Skill (a SKILL.md folder) so it loads reliably and works unchanged in Claude Code, Codex, OpenCode, Cursor, Gemini CLI, GitHub Copilot and Kete Code, including portable frontmatter, a tight trigger description, short instructions, helper scripts and trigger evals. Use when the user wants to write a new skill, turn a repeated workflow into a skill, or fix a skill that triggers at the wrong time.
+license: MIT
+compatibility: Any Agent Skills host.
+metadata:
+  kete-loom/version: "0.1.1"
+  kete-loom/category: meta
+  kete-loom/risk: writes-files
+  kete-loom/owner: "Kete-org"
+---
+
+# Skill authoring
+
+A good skill is found at the right moment and followed exactly. Two things decide that: the **description** (routing) and the **body** (execution).
+
+## 1. Capture the workflow
+
+Ask, or extract from the conversation:
+
+- What task does the skill handle, and what does "done" look like?
+- 3–5 real requests that should load it, and 3–5 similar requests that should **not**.
+- The steps an expert follows, the decisions they make, and where they stop and ask.
+- Which parts are deterministic (better as a script) and which need judgment (instructions).
+
+If the workflow is a single fact or a one-line rule, it belongs in `AGENTS.md`, not a skill. Say so.
+
+## 2. Write the frontmatter
+
+Use exactly this shape; it is the subset every host accepts. Details are in `references/frontmatter.md`.
+
+```yaml
+---
+name: kebab-case-name            # equals the folder name, max 64 chars
+description: <What it does, in one sentence>. Use when <the situations and phrasings that should load it>.
+license: MIT
+compatibility: <tools, network or OS it needs>
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding     # coding | testing | security | integrations | devops | data | ai | docs | business | compliance | meta
+  kete-loom/risk: read-only      # read-only | writes-files | runs-commands | network
+  kete-loom/requires: "git"      # optional, comma-separated CLIs
+---
+```
+
+The description is the only thing a host reads before deciding to load the skill. Make it:
+
+- **Specific**: name the task, the objects and the outputs ("Paystack webhooks", not "payments stuff").
+- **Triggerable**: list the situations and words users actually say after "Use when".
+- **Distinct**: if another skill's description overlaps, sharpen both so a router can tell them apart.
+- One line, 80–1024 characters.
+
+## 3. Write the body
+
+- Under 300 lines. Put long material in `references/` and say exactly when to read each file.
+- Numbered steps for procedures; checklists for reviews; a fixed format for the final report.
+- Say where to stop and ask the user, and what never to do.
+- Describe actions by capability ("run the test command", "search the codebase"), not by one host's tool names, so every host can follow them.
+- Move deterministic work into `scripts/`: one task per script, clear output, non-zero exit on failure, only tools listed in `kete-loom/requires`, with a shebang and `chmod +x`.
+
+## 4. Write trigger evals
+
+Create `evals/triggers.json` with at least 3 `should_trigger` and 3 `should_not_trigger` prompts. Make the negatives **near misses**: same domain, different job. These are what catch an over-broad description.
+
+## 5. Check it
+
+In a Kete Loom checkout:
+
+```
+npm run lint        # spec checks: frontmatter, length, references, evals
+npm run eval        # eval file checks
+npm run eval:live   # routes every prompt through a model, like a host does
+```
+
+Outside the repo, apply the checklist in `references/frontmatter.md` by hand. Then install locally and try the real prompts in at least two hosts:
+
+```
+npx @ketecode/loom install --project --skill <name> --link
+```
+
+## 6. Iterate on misses
+
+- Skill didn't load → the description is missing the user's words or the situation. Add them.
+- Loaded when it shouldn't → the description is too broad. Narrow it and add the prompt as a negative eval.
+- Loaded but did the wrong thing → the body is ambiguous at that step. Add a rule or an example there.
+
+Bump `kete-loom/version` on every change: patch for wording, minor for new steps, major when behaviour changes.

package/skills/skill-authoring/evals/triggers.json

@@ -0,0 +1,14 @@
+{
+  "should_trigger": [
+    "Turn our release checklist into a skill the coding agent can follow",
+    "Write a SKILL.md that teaches the agent our database migration conventions",
+    "My deploy skill keeps loading when I just ask about Docker, fix its description",
+    "Make this skill work in Codex and Cursor as well as Claude Code"
+  ],
+  "should_not_trigger": [
+    "Add a discount-code field to the checkout service, test first please",
+    "Write an AGENTS.md describing the repo's folder structure",
+    "Set up an MCP server that exposes our Jira tickets",
+    "Write onboarding docs for new engineers joining the team"
+  ]
+}

package/skills/skill-authoring/references/frontmatter.md

@@ -0,0 +1,40 @@
+# Portable frontmatter rules
+
+These rules are the strictest subset accepted by every major Agent Skills host as of October 2026. A skill that follows them installs unchanged everywhere.
+
+| Rule | Reason |
+|---|---|
+| Frontmatter starts on line 1 between `---` lines | Required by every host |
+| `name` matches `^[a-z0-9]+(-[a-z0-9]+)*$`, max 64 chars | OpenCode and Codex reject other names |
+| `name` equals the folder name | OpenCode requires it; others use the folder name for display |
+| `description` is one line, 1–1024 chars (Kete Loom: at least 80) | Spec limit; multi-line YAML scalars are parsed inconsistently |
+| Only `name`, `description`, `license`, `compatibility`, `metadata` at the top level | Unknown keys are rejected or ignored depending on the host |
+| `metadata` is a flat map of string to string | OpenCode requires string values |
+| Quote values that contain `:` or start with a special character | Plain YAML would misparse them |
+| Host-specific settings go under `metadata` with a host prefix, e.g. `opencode/slash: "true"` | Keeps the top level portable |
+
+## Where hosts look for skills
+
+| Host | User folder | Project folder |
+|---|---|---|
+| Shared standard (Codex, OpenCode, Cursor, Gemini CLI, Copilot) | `~/.agents/skills` | `.agents/skills` |
+| Claude Code | `~/.claude/skills` | `.claude/skills` |
+| OpenCode (own folder) | `~/.config/opencode/skills` | `.opencode/skills` |
+| Cursor (own folder) | `~/.cursor/skills` | `.cursor/skills` |
+| Gemini CLI (own folder) | `~/.gemini/skills` | `.gemini/skills` |
+| GitHub Copilot (own folder) | `~/.copilot/skills` | `.github/skills` |
+
+Installing into `~/.agents/skills` plus `~/.claude/skills` reaches all of them.
+
+## Optional Codex UI file
+
+Codex and the ChatGPT apps read an optional `agents/openai.yaml` inside the skill folder for a display name, icon, brand colour, default prompt, and `allow_implicit_invocation: false` (load only when invoked by name). Other hosts ignore it.
+
+## Manual checklist
+
+- [ ] Frontmatter follows every rule above
+- [ ] Description says what it does and contains "Use when"
+- [ ] Body under 300 lines; every referenced file exists
+- [ ] Scripts have a shebang, are executable and need only the listed tools
+- [ ] `evals/triggers.json` has 3+ positives and 3+ near-miss negatives
+- [ ] Tried in at least two hosts

package/skills/slack-app-integration/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: slack-app-integration
+description: Builds Slack apps on the Bolt framework (JavaScript, Python or Java), from the app manifest and minimal bot scopes through Events API subscriptions, slash commands and shortcuts acknowledged within three seconds, Block Kit messages and modals with interactive actions, and v0 HMAC request signing checks, to tiered Web API rate limits with Retry-After, Socket Mode versus HTTP endpoints, and OAuth v2 installs for distributing an app to other workspaces. Use when creating or fixing a Slack bot, slash command, modal or interactive message, choosing Slack scopes, debugging dispatch_failed or invalid signature errors, or preparing a Slack app for multi-workspace distribution.
+license: MIT
+compatibility: Any Agent Skills host. Live calls need network access to slack.com. Examples use Bolt for JavaScript; Bolt for Python and Java use the same concepts.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: integrations
+  kete-loom/risk: network
+  kete-loom/owner: "Kete-org"
+---
+
+# Slack app integration
+
+Build a Slack app that asks for the fewest scopes, acknowledges every request in time, verifies that each request really came from Slack, and survives rate limits. Posting a one-off message with an incoming webhook needs none of this; use the webhook URL and stop.
+
+## Ground rules
+
+1. **Use Bolt** unless the project already has its own Slack stack. Bolt verifies signatures, answers `url_verification` and gives every handler an `ack()`. It does not dedupe retried events; you do.
+2. **Secrets from the environment:** `SLACK_BOT_TOKEN` (`xoxb-`), `SLACK_SIGNING_SECRET`, `SLACK_APP_TOKEN` (`xapp-`, Socket Mode only), `SLACK_CLIENT_ID` / `SLACK_CLIENT_SECRET` (distribution). Never commit or log them.
+3. **Least scopes.** Every scope shows on the install screen and widens what a leaked token can do. Add scopes only when a method you call needs them.
+4. **`ack()` within 3 seconds**, then do slow work. Slash commands, shortcuts, actions and view submissions fail with a timeout error for the user otherwise; Events API deliveries are retried.
+5. **Keep the app definition in a manifest** (`manifest.json` or `.yml`) under version control.
+
+## Set up
+
+1. Create the app at api.slack.com/apps from a manifest. Declare `oauth_config.scopes.bot`, `features` (bot user, slash commands, shortcuts), `settings.event_subscriptions.bot_events` and `settings.interactivity`.
+2. Pick the connection:
+
+| Situation | Use |
+|---|---|
+| Local development, internal app behind a firewall | Socket Mode: `socketMode: true` and an app-level token with `connections:write`. No public URL |
+| Production app, or one listed in the Slack Marketplace | HTTP: a public HTTPS request URL for events, commands and interactivity (Marketplace apps cannot use Socket Mode) |
+
+3. Install to a development workspace and copy the bot token.
+
+Common bot scopes: `chat:write` (post), `commands` (slash commands), `app_mentions:read`, `channels:history` / `groups:history` / `im:history` (read messages in public / private / DMs), `users:read`, `reactions:write`. Add `chat:write.public` only if the bot must post in channels it was not invited to.
+
+## Events, commands and interactivity
+
+```js
+const { App } = require('@slack/bolt');
+const app = new App({ token: process.env.SLACK_BOT_TOKEN, signingSecret: process.env.SLACK_SIGNING_SECRET });
+
+app.command('/ticket', async ({ ack, body, client }) => {
+  await ack();                                   // within 3 s
+  await client.views.open({ trigger_id: body.trigger_id, view: ticketModal() }); // trigger_id expires after ~3 s
+});
+
+app.view('ticket_submit', async ({ ack, view, body }) => {
+  const title = view.state.values.title_block.title_input.value;
+  if (!title) return ack({ response_action: 'errors', errors: { title_block: 'Required' } });
+  await ack();
+  queue.push({ user: body.user.id, title });     // slow work after ack
+});
+
+app.event('app_mention', async ({ event, say }) => { await say({ text: 'On it', thread_ts: event.ts }); });
+```
+
+Rules:
+
+- On a FaaS host (AWS Lambda and similar) with the HTTP receiver, set `processBeforeResponse: true` and keep handlers fast; the function may be frozen as soon as the response is sent, so work after `ack()` is not guaranteed to run. Hand slow work to a queue.
+- Events: Slack retries a delivery up to three times if you do not return `2xx` in 3 seconds, sending `X-Slack-Retry-Num` and `X-Slack-Retry-Reason`. Dedupe on `event_id`. Ignore messages from your own bot (`bot_id` set) to avoid loops.
+- Slash command replies: `respond()` (via `response_url`, usable up to 5 times within 30 minutes) for ephemeral or follow-up replies; `client.chat.postMessage` for a normal message.
+- Block Kit: always include top-level `text` as the notification and accessibility fallback. Give every input and action a stable `block_id` / `action_id`. Messages allow up to 50 blocks; modals and Home tabs up to 100. Build with Block Kit Builder and validate before shipping.
+- Use `private_metadata` on a view to carry context (up to 3,000 characters), never hidden user-editable inputs.
+- Use `views.update` with the `hash` from the previous view to avoid race conditions.
+
+## Request signature verification
+
+Only needed if you are not using Bolt's receiver (custom framework, serverless handler):
+
+1. Read `X-Slack-Request-Timestamp`; reject if it differs from now by more than 5 minutes.
+2. Build `v0:{timestamp}:{raw body}` from the **raw** body before any JSON or form parsing.
+3. HMAC-SHA256 it with the signing secret (as UTF-8), hex-encode, prefix `v0=`.
+4. Compare with `X-Slack-Signature` using a constant-time compare. Reject with 401 on mismatch.
+
+Never use the deprecated verification token instead.
+
+## Rate limits
+
+- Web API methods are tiered per method, per workspace, per app: Tier 1 (1+ per minute), Tier 2 (20+), Tier 3 (50+), Tier 4 (100+), plus special limits. `chat.postMessage` allows about one message per second per channel.
+- On `HTTP 429`, wait `Retry-After` seconds. The official SDK clients retry for you; do not stack your own retry loop on top.
+- Events API deliveries are capped at 30,000 per workspace per app per hour; past that Slack sends `app_rate_limited`.
+- Since 29 May 2025, commercially distributed apps that are not Marketplace-approved get Tier 1 limits on `conversations.history` and `conversations.replies` (1 request per minute, `limit` at most 15) for apps created from that date and for new installs of older apps. Internal (custom) apps and Marketplace apps are not affected. Check docs.slack.dev for the current rule before designing anything that reads history in bulk.
+- Paginate list methods with `cursor` and `response_metadata.next_cursor`; keep `limit` at or below 200.
+
+## Distribution
+
+1. Turn on public distribution in the app settings; set redirect URLs.
+2. Implement OAuth v2: send users to `https://slack.com/oauth/v2/authorize?client_id=...&scope=...&state=...`, exchange the code with `oauth.v2.access`, store the bot token per `team.id` (and `enterprise.id` for Enterprise Grid). Bolt's `installationStore` and `stateSecret` do this.
+3. Handle `app_uninstalled` and `tokens_revoked` events by deleting the stored tokens.
+4. Consider token rotation (refresh tokens, 12-hour access tokens) for distributed apps.
+5. Marketplace listing needs a review by Slack; check their current guidelines and expect scope justifications.
+
+## Reviewing an existing app
+
+Look for: slow work before `ack()`; signature checks on a parsed body, with `==`, or missing; a handler that skips verification when headers are absent; scopes nobody uses; tokens stored in plain config; no `event_id` dedupe; bot replying to itself; `trigger_id` used after a slow call; messages with blocks but no `text`; tight loops on `chat.postMessage` with no pacing.
+
+## Stop and ask the user
+
+- Before adding a scope that reads messages (`*:history`) or user data (`users:read.email`); these change what the install asks for and need a reason.
+- Before enabling public distribution or submitting to the Marketplace.
+- Before posting to real channels from tests; use a dev workspace.
+
+## Before you finish
+
+Test in a development workspace: a slash command that opens a modal, a view submission with a validation error, an interactive button, an event delivered twice (handled once), a request with a stale timestamp and a forged signature (both rejected), and a burst of posts that triggers a 429 (handled). Slack's docs at docs.slack.dev are the final word on scopes, limits and payloads.

package/skills/slack-app-integration/evals/triggers.json

@@ -0,0 +1,17 @@
+{
+  "should_trigger": [
+    "Build a Slack bot with Bolt that answers when someone mentions it in a channel",
+    "Our /deploy slash command shows operation_timeout in Slack, fix the handler",
+    "Add a Block Kit modal with a form that opens from a message shortcut",
+    "Verify X-Slack-Signature in our serverless function that receives Slack events",
+    "Which Slack bot scopes do we need to post messages and read reactions?",
+    "Let other companies install our Slack app with OAuth v2 and store each workspace token"
+  ],
+  "should_not_trigger": [
+    "Make an animated GIF for our team Slack channel",
+    "Post one deploy notice to Slack from a shell script with an incoming webhook URL",
+    "Send a Discord webhook message when a build fails",
+    "Create a Jira ticket from a form submission",
+    "Write the internal announcement for the new release"
+  ]
+}