@damiangilgonzalez/harness 1.3.7

package/skills/electron/scripts/verify.sh

@@ -0,0 +1,143 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# ============================================================================
+# NAME
+#   verify.sh — Electron insecure-pattern gate
+#
+# USAGE
+#   ./verify.sh [TARGET_DIR]
+#
+#   With TARGET_DIR: scans that Electron project's source for insecure
+#   patterns and exits non-zero if any are found.
+#   With no argument: self-checks THIS skill's own example code fences — the
+#   recommended ("Good") snippets must be clean and must contain the secure
+#   baseline. Fences flagged with a `// Bad` comment are intentional
+#   counter-examples and are skipped; prose, tables, and checklists (which
+#   legitimately NAME the banned patterns) are not scanned.
+#
+# WHAT IT FLAGS (each = FAIL)
+#   nodeIntegration: true            renderer gets full Node → XSS becomes RCE
+#   contextIsolation: false          page can rewrite the preload bridge
+#   sandbox: false                   renderer escapes the OS sandbox
+#   @electron/remote                 direct renderer→main escalation path
+#   new BrowserView                  deprecated since Electron 30
+#   exposeInMainWorld(..., ipcRenderer)  universal IPC weapon (empty obj now)
+#
+# GUARANTEES
+#   - Read-only: never writes to or modifies the target.
+#   - Exits 0 on an empty or clean target (no false failure).
+#   - Portable to stock macOS bash 3.2 (no mapfile/associative arrays).
+#
+# EXIT CODES
+#   0  clean (or empty target)
+#   1  at least one insecure pattern found
+#   2  bad usage (target path does not exist)
+# ============================================================================
+
+if [ -t 1 ] && [ -z "${NO_COLOR:-}" ]; then
+  RED=$'\033[31m'; GRN=$'\033[32m'; YLW=$'\033[33m'; RST=$'\033[0m'
+else
+  RED=''; GRN=''; YLW=''; RST=''
+fi
+
+FAILED=0
+ok()   { printf '%sPASS%s %s\n' "$GRN" "$RST" "$1"; }
+bad()  { printf '%sFAIL%s %s\n' "$RED" "$RST" "$1"; FAILED=1; }
+info() { printf '%s•%s    %s\n' "$YLW" "$RST" "$1"; }
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SKILL_DIR="$(dirname "$SCRIPT_DIR")"
+
+PAT_NODEINT='nodeIntegration[[:space:]]*:[[:space:]]*true'
+PAT_CTXISO='contextIsolation[[:space:]]*:[[:space:]]*false'
+PAT_SANDBOX='sandbox[[:space:]]*:[[:space:]]*false'
+PAT_REMOTE='@electron/remote'
+PAT_BROWSERVIEW='new[[:space:]]+BrowserView'
+PAT_EXPOSE='exposeInMainWorld\([^,]*,[[:space:]]*ipcRenderer[[:space:]]*\)'
+
+scan_lines() { # $1=label $2=pattern $3=haystack ; runs in the CURRENT shell so
+               # FAILED mutations stick (a pipe would fork a subshell and lose them)
+  local label="$1" pat="$2" hits
+  hits="$(printf '%s\n' "$3" | grep -nE "$pat" || true)"
+  if [ -n "$hits" ]; then
+    bad "$label"
+    printf '%s\n' "$hits" | sed 's/^/       /'
+  else
+    ok "$label"
+  fi
+}
+
+# ---------------------------------------------------------------------------
+if [ "$#" -ge 1 ]; then
+  # ---- TARGET MODE: scan a real Electron project's source files ----------
+  TARGET="$1"
+  if [ ! -e "$TARGET" ]; then
+    printf '%sverify.sh: target does not exist: %s%s\n' "$RED" "$TARGET" "$RST" >&2
+    exit 2
+  fi
+  printf 'Scanning %s (target mode)\n\n' "$TARGET"
+
+  SRC="$(
+    find "$TARGET" \
+      \( -name node_modules -o -name .git -o -name dist -o -name out \) -prune -o \
+      \( -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.mjs' -o -name '*.cjs' \) \
+      -type f -print 2>/dev/null || true
+  )"
+  if [ -z "$SRC" ]; then
+    info "no Electron source files found under $TARGET"
+    ok "clean (nothing to check)"
+    exit 0
+  fi
+
+  # Concatenate source as file:line so findings point somewhere useful.
+  ALL="$(printf '%s\n' "$SRC" | while IFS= read -r f; do
+    [ -n "$f" ] || continue
+    grep -nH '' "$f" 2>/dev/null || true
+  done)"
+
+  scan_lines "no nodeIntegration: true"                 "$PAT_NODEINT"     "$ALL"
+  scan_lines "no contextIsolation: false"               "$PAT_CTXISO"      "$ALL"
+  scan_lines "no sandbox: false"                        "$PAT_SANDBOX"     "$ALL"
+  scan_lines "no @electron/remote"                      "$PAT_REMOTE"      "$ALL"
+  scan_lines "no new BrowserView (use WebContentsView)" "$PAT_BROWSERVIEW" "$ALL"
+  scan_lines "no ipcRenderer over contextBridge"        "$PAT_EXPOSE"      "$ALL"
+
+else
+  # ---- SELF MODE: vet the skill's own "Good" code fences -----------------
+  printf 'Self-checking %s (self mode)\n\n' "$SKILL_DIR"
+  DOCS="$(find "$SKILL_DIR" -type f \( -name 'SKILL.md' -o -path '*/references/*.md' \) 2>/dev/null || true)"
+
+  # Extract only code-fence bodies, dropping any fence that is marked as a
+  # `// Bad` counter-example. Prose/tables/checklists are never scanned.
+  GOOD="$(
+    printf '%s\n' "$DOCS" | while IFS= read -r f; do
+      [ -n "$f" ] || continue
+      awk '
+        /^```/      { infence = !infence; if (infence) { buf=""; bad=0 } else { if (!bad) printf "%s", buf }; next }
+        infence     { if ($0 ~ /\/\/[[:space:]]*Bad/) bad=1; buf = buf $0 "\n" }
+      ' "$f"
+    done
+  )"
+
+  scan_lines "Good snippets: no nodeIntegration: true"   "$PAT_NODEINT"     "$GOOD"
+  scan_lines "Good snippets: no contextIsolation: false" "$PAT_CTXISO"      "$GOOD"
+  scan_lines "Good snippets: no sandbox: false"          "$PAT_SANDBOX"     "$GOOD"
+  scan_lines "Good snippets: no @electron/remote import" "$PAT_REMOTE"      "$GOOD"
+  scan_lines "Good snippets: no new BrowserView"         "$PAT_BROWSERVIEW" "$GOOD"
+  scan_lines "Good snippets: no exposed ipcRenderer"     "$PAT_EXPOSE"      "$GOOD"
+
+  # Positive assertion: the secure baseline must actually appear somewhere.
+  for tok in 'nodeIntegration: false' 'contextIsolation: true' 'sandbox: true'; do
+    if printf '%s\n' "$GOOD" | grep -qF "$tok"; then ok "baseline present: $tok"
+    else bad "baseline missing from example snippets: $tok"; fi
+  done
+fi
+
+echo
+if [ "$FAILED" -eq 0 ]; then
+  ok "no insecure Electron patterns found"
+else
+  printf '%sinsecure patterns present — fix before shipping%s\n' "$RED" "$RST" >&2
+fi
+exit "$FAILED"

package/skills/eli5/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: eli5
+description: "Use when a topic must be explained from zero to someone who knows nothing about it: one page, big pictures, very few words, everyday analogies, no jargon and nothing assumed. NOT the smallest in-conversation visual for someone already following (that is `show-me`), NOT a course with exercises (that is `course-builder`)."
+tags: [eli5, explain, beginner, simple, analogy, no-jargon, explicame]
+recommends: [show-me, technical-writing, course-builder]
+profiles: [minimal, core, ui, full]
+origin: risco
+---
+
+# eli5 — explain it to someone who knows nothing
+
+The topic is whatever the user named. With no topic named, it is the one the conversation is already
+on. The audience is someone with **zero** background: no vocabulary, no context, no patience for a
+definition that needs another definition.
+
+## The contract
+
+1. **A page, not a paragraph.** The output is one self-contained HTML page, big visuals first, words
+   second. Open it when it is written.
+2. **Picture carries the idea, words label it.** If the page still makes sense with the text removed,
+   it is working. Aim for a caption per picture, not a paragraph per picture.
+3. **Everyday objects only.** Compare to things a person has physically handled: boxes, keys, queues
+   at a counter, post, a light switch. Never explain one unknown with another unknown.
+4. **Zero jargon, and zero smuggled jargon.** No term appears without being shown first. "It caches"
+   is jargon; "it keeps a copy nearby so it doesn't have to walk back" is the same fact.
+5. **Simple, never false.** When the simplification would make something untrue, say what got left
+   out, in one line, at the end. A comfortable lie is worse than a hard truth.
+6. **No condescension.** Simple words, adult tone. The reader is new to the topic, not a child.
+
+## The shape of the page
+
+```text
+one sentence: what this thing is, in words a stranger would use
+big picture 1 : the thing, drawn
+big picture 2 : the thing doing its job, step by step
+one line      : the part people get wrong
+one line      : what this explanation left out (only if it left something out)
+```
+
+Three to five visuals is the whole page. Inline SVG or plain HTML boxes beat any chart library here:
+the drawing has to be readable on a phone, at a glance, with no legend to study.
+
+```bash
+open path/to/eli5-<topic>.html
+```
+
+## Anti-patterns
+
+| Anti-pattern | Why it fails | Do this instead |
+| --- | --- | --- |
+| Define a term with two more terms | The reader loses the thread on line one | Show the thing, then name it |
+| A wall of text with one decorative image | That is a blog post with a picture | Picture first, caption second |
+| "Imagine you're a packet travelling…" | Cute framing, still abstract | Compare to an object the reader has held |
+| Simplify until it is wrong | The reader now has to unlearn it | Keep it true and name what you dropped |
+| Baby talk, emoji, exclamation marks | Talks down to the reader | Plain adult words, short sentences |
+| Five diagrams of the same idea | Repetition reads as padding | One picture per genuinely new idea |
+
+## Where this ends
+
+- Someone already following the conversation who needs the shape of one mechanism: `show-me`.
+- A structured curriculum with exercises, assessment and progression: `course-builder`.
+- Documentation an informed reader will keep coming back to: `technical-writing`.
+- Making an existing text sound human rather than simpler: `bro`.

package/skills/eli5/evals/README.md

@@ -0,0 +1,22 @@
+# Evals — eli5
+
+Two claims: that a from-zero request routes here instead of to the in-conversation visual skill or to
+teaching material, and that the loaded skill produces a page a genuine beginner can follow.
+
+## Triggering
+
+Load only `eli5` and run every prompt in 3–5 fresh sessions. A positive passes when `eli5` loads in a
+majority of trials; a negative passes when it stays quiet and the declared `route_to` skill is the
+real owner. Require at least 90% accuracy.
+
+`show-me` is the negative that matters: both are "explain it visually". The discriminator is the
+reader's starting knowledge, and it must survive any description edit on either side.
+
+## Capability
+
+Run the scenario without the skill and with it, same topic and one grader, three trials. The
+with-skill condition must satisfy at least 80% of the rubric and beat the baseline by at least 20
+percentage points.
+
+Grade the jargon point strictly: a baseline answer almost always keeps one unexplained term, which is
+exactly the failure the skill exists to prevent.

package/skills/eli5/evals/cases.yaml

@@ -0,0 +1,54 @@
+skill: eli5
+
+# `eli5` owns one move: a from-zero explanation of one topic, as a page of big
+# pictures and few words, for someone with no background at all. It does not own
+# in-conversation diagrams for someone already following, curricula, or docs.
+should_trigger:
+  - prompt: "Explícame qué es una API como si tuviera cinco años."
+    why: "The canonical from-zero request, named outright, in the user's own language."
+
+  - prompt: "My mum asked me what a VPN is. I need something she can actually look at."
+    why: "A named audience with zero background and an explicit ask for something visual."
+
+  - prompt: "eli5 how a blockchain works"
+    why: "The bare skill name plus a topic is the shortest form of the same request."
+
+  - prompt: "No tengo ni idea de esto. Empieza por lo más básico, sin palabras raras."
+    why: "Zero background plus an explicit no-jargon constraint, with no topic named: the topic is the current one."
+
+  - prompt: "Can you explain what an index is in a database, but for someone who has never programmed?"
+    why: "A technical topic aimed at a non-technical reader is the audience this skill is written for."
+
+  - prompt: "Necesito explicarle a mi cliente, que no es técnico, qué es un webhook. Que lo entienda de una."
+    why: "Explaining to a named non-technical third party is the same job, one step removed."
+
+should_not_trigger:
+  - prompt: "Show me the call order when the form is submitted, I'm lost in the code."
+    route_to: "show-me"
+    why: "The user is already inside the topic and needs one mechanism drawn, not a from-zero page."
+
+  - prompt: "Build a four-week course on SQL with exercises and a final project."
+    route_to: "course-builder"
+    why: "Curriculum, progression and assessment are course-builder; eli5 is a single explanation."
+
+  - prompt: "Write the getting-started docs for our SDK, with runnable examples."
+    route_to: "technical-writing"
+    why: "Reference and tutorial documentation is technical-writing, even when it must be beginner-friendly."
+
+  - prompt: "Make this paragraph sound less robotic before I send it."
+    route_to: "bro"
+    why: "A register and tone pass over existing text is bro; nothing here needs explaining from zero."
+
+  - prompt: "Design the hero section for our homepage so it feels premium."
+    route_to: "design-loop"
+    why: "Visual identity is the design area; eli5's visuals serve comprehension, not brand."
+
+capability:
+  - scenario: "A non-technical business owner asks what a webhook is, after two failed explanations that used the words 'endpoint', 'payload' and 'HTTP POST'."
+    must_include:
+      - "produces one self-contained page with three to five large visuals, not a wall of text"
+      - "uses an everyday physical analogy the reader has handled, not another abstraction"
+      - "introduces no term without showing the thing first, and never uses endpoint, payload or POST unexplained"
+      - "keeps the explanation true, and names in one line whatever was left out"
+      - "stays adult in tone: no baby talk, no emoji, no exclamation marks"
+      - "opens the page for the user instead of only writing the file"

package/skills/elixir/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: elixir
+description: "Use when writing or refactoring Elixir/OTP on the BEAM — GenServers, supervision trees and restart strategies, pattern matching, mix projects and releases — or when processes misbehave (restart loops, mailbox growth, call timeouts). NOT a Phoenix web app, LiveView, Ecto or channels (that is `phoenix`)."
+tags: [elixir, otp, genserver, supervision, beam, mix, concurrency, functional]
+recommends: [phoenix, postgresdb, docker]
+origin: risco
+---
+
+# Elixir
+
+You are writing Elixir on the BEAM. The runtime gives you cheap isolated processes, preemptive scheduling, and supervision. The single mental shift that separates idiomatic Elixir from ported imperative code: **let it crash and supervise it, do not defend every call**. A process that hits an impossible state should die and be restarted clean by its supervisor — that is more correct than a `try/rescue` that limps on with corrupt state.
+
+Default to **pure functions**. Most of your code is data transformation and needs no process at all. Reach for a process only when you need state, concurrency, or fault isolation. Target Elixir **v1.19.5** (stable, requires Erlang/OTP 28.1+) or **v1.20-rc** (full type inference, OTP 27+/29). Use the modern stdlib: built-in `JSON`, set-theoretic type warnings, `mix format`.
+
+## Decision: do you even need a process?
+
+A process is not "an object": spawning one to hold a value you could pass as an argument is the most common beginner mistake, and it adds a serialization bottleneck and a failure mode for nothing.
+
+| Situation | Use | Why |
+|---|---|---|
+| Pure transform of input -> output | plain function / module | No state, no concurrency: a process only adds overhead and a mailbox |
+| Hold mutable state behind an API | `GenServer` (or `Agent` for trivial state) | Serializes access, owns a lifecycle, supervisable |
+| Run N independent jobs concurrently | `Task.async_stream` / `Task.Supervisor` | Bounded fan-out, results collected, crashes isolated |
+| Isolate a risky/external boundary | a supervised process | A crash there restarts clean without taking down callers |
+| Shared read-heavy cache | `:ets` table | Concurrent lock-free reads, no single-process bottleneck |
+
+Rule: if two pieces of code never run at the same time and share no mutable state, they are functions, not processes.
+
+## The functional core
+
+**Match in function heads, not with `if`** — branches become exhaustive and self-documenting, and a non-match crashes loudly instead of silently falling through.
+
+```elixir
+# Bad - imperative branching, easy to miss a case
+def area(shape) do
+  if shape.type == :circle do
+    :math.pi() * shape.r * shape.r
+  else
+    shape.w * shape.h
+  end
+end
+
+# Good - one clause per shape, unmatched input crashes (which a supervisor handles)
+def area(%Circle{r: r}), do: :math.pi() * r * r
+def area(%Rect{w: w, h: h}), do: w * h
+```
+
+**Return tagged tuples `{:ok, value}` / `{:error, reason}`** — the caller pattern-matches the outcome; this is the protocol the whole ecosystem speaks.
+
+```elixir
+# Good
+def fetch(id) do
+  case Repo.get(id) do
+    nil -> {:error, :not_found}
+    record -> {:ok, record}
+  end
+end
+```
+
+**Chain fallible steps with `with`** — it reads as the happy path and short-circuits on the first non-match, no nested `case` pyramids.
+
+```elixir
+# Good - any step returning a non-{:ok, _} falls straight to else
+with {:ok, user} <- fetch_user(id),
+     {:ok, acct} <- fetch_account(user),
+     :ok <- authorize(acct) do
+  {:ok, acct}
+else
+  {:error, reason} -> {:error, reason}
+end
+```
+
+**Use guards to constrain clauses** (`when is_integer(n) and n > 0`) — keeps validation declarative and lets the compiler reason about types.
+
+**Pipe left-to-right for data flowing through transforms** — `data |> step1() |> step2()`. Do not pipe just to avoid an intermediate variable; if a step needs the value in a non-first argument, name it.
+
+**There is no mutation.** Rebinding `x = f(x)` makes a new binding; data you passed elsewhere is unchanged. Stop reaching for mutable accumulators — use `Enum.reduce/3`, comprehensions, or recursion.
+
+## Processes and message passing
+
+Raw `spawn`/`send`/`receive` exists and is fine for a throwaway fire-and-forget where supervision genuinely does not matter, but in production you almost always want an OTP behaviour (GenServer/Task/Agent) so you get `child_spec`, supervision, and shutdown handling for free.
+
+- **Link** (`spawn_link`) couples lifetimes: if one dies abnormally, the other gets an exit signal. This is how supervision works.
+- **Monitor** (`Process.monitor/1`) is one-directional and non-fatal: you get a `{:DOWN, ...}` message but you do not die. Use it when you care *that* something died but should survive it.
+
+## GenServer
+
+Split the **client API** (runs in the caller) from the **server callbacks** (run in the GenServer process). Callers never touch state directly.
+
+```elixir
+defmodule Counter do
+  use GenServer
+
+  # --- Client API (caller's process) ---
+  def start_link(opts) do
+    GenServer.start_link(__MODULE__, opts[:start] || 0, name: opts[:name] || __MODULE__)
+  end
+
+  @spec increment(GenServer.server()) :: :ok
+  def increment(server \\ __MODULE__), do: GenServer.cast(server, :increment)
+
+  @spec value(GenServer.server()) :: integer()
+  def value(server \\ __MODULE__), do: GenServer.call(server, :value)
+
+  # --- Server callbacks (GenServer's process) ---
+  @impl true
+  def init(start), do: {:ok, start, {:continue, :warm_up}}
+
+  @impl true
+  def handle_continue(:warm_up, state) do
+    # heavy/slow init goes here, AFTER start_link has returned
+    {:noreply, state}
+  end
+
+  @impl true
+  def handle_cast(:increment, count), do: {:noreply, count + 1}
+
+  @impl true
+  def handle_call(:value, _from, count), do: {:reply, count, count}
+end
+```
+
+- **Never block in `init/1`.** `start_link` blocks until `init` returns, so a slow `init` stalls the whole supervision tree boot. Return `{:ok, state, {:continue, term}}` and do the work in `handle_continue/2`.
+- **`use GenServer` auto-defines `child_spec/1`** — you rarely write one by hand; override only to change `:restart` or `:shutdown`.
+- **`call` is synchronous (with a 5s default timeout), `cast` is fire-and-forget.** Use `call` when the caller needs the result or backpressure; `cast` when it does not. A flood of `cast`s with no backpressure is the classic mailbox-growth bug — timeouts and backpressure recipes in `references/otp-patterns.md`.
+- **Name via `Registry`, not a global atom**, when you have many dynamic instances — atoms are never garbage-collected (see anti-patterns).
+
+## Supervision trees
+
+The supervision tree starts in `lib/<app>/application.ex`, wired via the `mod:` key in `mix.exs`. `mix new <app> --sup` scaffolds this.
+
+```elixir
+defmodule MyApp.Application do
+  use Application
+
+  @impl true
+  def start(_type, _args) do
+    children = [
+      {Registry, keys: :unique, name: MyApp.Registry},
+      {DynamicSupervisor, name: MyApp.WorkerSup, strategy: :one_for_one},
+      Counter
+    ]
+
+    Supervisor.start_link(children, strategy: :one_for_one, name: MyApp.Supervisor)
+  end
+end
+```
+
+**Restart strategy** — how siblings react when one child dies:
+
+| Strategy | On a child crash | Use when |
+|---|---|---|
+| `:one_for_one` | restart only that child | children are independent (the default, most common) |
+| `:one_for_all` | restart all children | children depend on each other and shared state is invalidated |
+| `:rest_for_one` | restart that child and the ones started after it | later children depend on earlier ones |
+
+**Restart value** per child — `:permanent` (always restart, the default), `:transient` (restart only on abnormal exit), `:temporary` (never restart). A pool worker is often `:transient`; a one-shot job is `:temporary`.
+
+**Let it crash**: do not wrap business logic in `try/rescue` to keep a process alive. Validate inputs at the boundary, then trust the happy path; if an invariant breaks, crashing and restarting from a known-good `init` state is the recovery mechanism. Reserve `rescue` for boundaries where you must convert an exception into a tagged tuple for a caller.
+
+For runtime-spawned children (a worker per connection/job) use `DynamicSupervisor` + `Registry` for lookup. Full recipe — plus `Task`, `Agent`, `:ets` and how to choose an OTP behaviour — in `references/otp-patterns.md`.
+
+## mix project
+
+```text
+my_app/
+  mix.exs               # project, deps, application/0 with mod: callback
+  config/
+    config.exs          # compile-time config (read once, at build)
+    runtime.exs         # runtime config — reads System.get_env at boot
+  lib/
+    my_app.ex
+    my_app/
+      application.ex     # supervision tree
+  test/
+```
+
+- **`config.exs` is compile-time; `runtime.exs` is runtime.** Anything coming from the environment of the running release (DB URL, secrets, ports) goes in `runtime.exs` — it is the only config evaluated inside the built release at boot. Putting secrets in `config.exs` bakes build-time values into the artifact.
+- **`mix release`** produces a self-contained tarball with its own ERTS; no Elixir/Erlang needed on the target. Run it with `bin/<app> start`.
+
+```bash
+MIX_ENV=prod mix release
+_build/prod/rel/my_app/bin/my_app start
+```
+
+`mix.exs` anatomy, deps, environments, env vars, releases and the umbrella decision live in `references/mix-and-releases.md`.
+
+## Types and modern stdlib
+
+- **Add `@spec` to public functions.** The set-theoretic type system (gradual, sound; v1.18 inferred patterns/calls, v1.19 added protocol + anonymous-fn inference, v1.20 targets full inference) uses them and surfaces warnings at compile time — **treat type warnings as bugs**, they catch real mismatches before runtime.
+- **Use built-in `JSON`** (`JSON.encode!/1`, `JSON.decode!/1`, since v1.18) for basic encoding/decoding — no Jason/Poison dependency needed unless you require their extras.
+- **`mix format`** is the canonical formatter; run it and gate CI on `mix format --check-formatted`.
+- **`mix compile --warnings-as-errors`** in CI. Dialyzer and Credo are optional add-ons, not required for correct OTP code.
+- v1.19 perf: lazy module loading (>2x faster compiles on large projects) and `MIX_OS_DEPS_COMPILE_PARTITION_COUNT` for parallel dep compilation.
+
+## Anti-patterns
+
+| Bad | Why it bites | Do instead |
+|---|---|---|
+| `String.to_atom(user_input)` | Atoms are never garbage-collected; attacker-controlled input exhausts the atom table and crashes the VM | `String.to_existing_atom/1`, or keep it a string / map key |
+| One god GenServer all calls route through | Serializes everything into one mailbox — a hard concurrency ceiling and a single point of failure | Split by responsibility; use a `Registry` of per-entity processes or `Task` for parallel work |
+| Heavy work inside `init/1` | `start_link` blocks until `init` returns, stalling the supervision tree boot | `{:ok, state, {:continue, msg}}` + `handle_continue/2` |
+| `try/rescue` wrapping all logic | Defeats let-it-crash; the process limps on with corrupt state | Validate at the boundary, trust the path, let the supervisor restart |
+| A new process per trivial call | Spawn + mailbox + scheduling overhead for nothing | A plain function; processes are for state/concurrency/isolation |
+| Unbounded `cast` into a slow GenServer | Producer outruns consumer, mailbox grows without bound, OOM | Use `call` for backpressure, or a bounded queue / `GenStage` |
+
+## Verify
+
+Run `scripts/verify.sh` from your mix project root (the directory containing `mix.exs`). It checks `mix format --check-formatted` and `mix compile --warnings-as-errors`, and skips cleanly with exit 0 when Elixir/mix is not installed so it never blocks a toolchain-free CI.

package/skills/elixir/evals/README.md

@@ -0,0 +1,3 @@
+# Evals: elixir
+
+These cases are illustrative, not an automated grader. To run them by hand, read each `should_trigger` prompt and confirm the skill would fire (especially the non-obvious mailbox-growth and blocking-init cases and the Catalan/Spanish phrasings); then read each `should_not_trigger` prompt and confirm you would instead route to the named sibling (`phoenix` for web/LiveView/Ecto, `go` for goroutines, `postgresdb` for DB tuning) rather than answering as Elixir. For the `capability` case, give the scenario to the agent and check the produced code against the `must_include` rubric line by line — every item should be present and idiomatic (client/server split, DynamicSupervisor + Registry, child_spec, `@spec`, no blanket `try/rescue`, tagged tuples, a real mix layout). Score it as pass only if nothing in the rubric is missing or faked.

package/skills/elixir/evals/cases.yaml

@@ -0,0 +1,41 @@
+skill: elixir
+
+should_trigger:
+  - prompt: "Write me a GenServer that keeps a counter and supports increment and get."
+    why: Core GenServer authoring — client API + callbacks + child_spec, the central capability.
+  - prompt: "Design a supervision tree for a worker pool that restarts crashed workers."
+    why: Supervision strategy and restart values, the OTP design layer this skill owns.
+  - prompt: "How do I structure 'let it crash' instead of wrapping everything in try/rescue?"
+    why: BEAM failure philosophy; the mental shift the skill is built around.
+  - prompt: "Set up a mix release so I can deploy my Elixir app to production."
+    why: mix project, runtime.exs vs config.exs, and `mix release` packaging.
+  - prompt: "Els meus processos d'Elixir acumulen missatges al mailbox i acaben petant, com ho arreglo?"
+    why: Catalan, non-obvious symptom — unbounded mailbox growth from cast flooding / slow handlers.
+  - prompt: "Mi GenServer entra en un bucle de reinicios al arrancar, creo que el init bloquea."
+    why: Spanish, non-obvious — blocking init stalling the supervisor; route to handle_continue.
+
+should_not_trigger:
+  - prompt: "Build a LiveView page with a form and live validation."
+    route_to: phoenix
+    why: Web/LiveView is the Phoenix layer that builds its own tree on top of OTP.
+  - prompt: "Write an Ecto schema and a query with preloads for my users table."
+    route_to: phoenix
+    why: Ecto schemas/queries ship with the Phoenix sibling, not the bare language/OTP skill.
+  - prompt: "Use goroutines and channels to fan out work across CPUs."
+    route_to: go
+    why: Different runtime and concurrency model; the request names Go primitives.
+  - prompt: "Tune Postgres indexes and analyze a slow query plan."
+    route_to: postgresdb
+    why: Database tuning, unrelated to the BEAM or OTP.
+
+capability:
+  - scenario: "Build a token-bucket rate limiter as a supervised OTP service, one bucket process per API key, created on demand and addressable by key."
+    must_include:
+      - GenServer with a clear client API separated from server callbacks
+      - supervised under application.ex, with buckets started via DynamicSupervisor at runtime
+      - Registry-based naming ({:via, Registry, ...}) instead of dynamic global atoms
+      - child_spec via `use GenServer` (or an explicit override only if changing restart/shutdown)
+      - "@spec on the public functions"
+      - "let-it-crash: no blanket try/rescue around the bucket logic; supervisor restarts on crash"
+      - mix project structure (mix.exs application/0 with mod:, lib/ layout)
+      - tagged tuple returns ({:ok, _} / {:error, :rate_limited})

package/skills/elixir/references/mix-and-releases.md

@@ -0,0 +1,91 @@
+# mix project and releases
+
+Depth offloaded from SKILL.md.
+
+## mix.exs anatomy
+
+```elixir
+defmodule MyApp.MixProject do
+  use Mix.Project
+
+  def project do
+    [
+      app: :my_app,
+      version: "0.1.0",
+      elixir: "~> 1.19",
+      start_permanent: Mix.env() == :prod,
+      deps: deps()
+    ]
+  end
+
+  # application/0 — `mod:` names the Application module + start args.
+  # Omit `mod:` for a library that has no supervision tree of its own.
+  def application do
+    [
+      extra_applications: [:logger],
+      mod: {MyApp.Application, []}
+    ]
+  end
+
+  defp deps do
+    [
+      {:req, "~> 0.5"},
+      {:credo, "~> 1.7", only: [:dev, :test], runtime: false}
+    ]
+  end
+end
+```
+
+- `elixir: "~> 1.19"` pins the language line; `~>` allows patch/minor within the constraint.
+- Dev/test-only tooling uses `only:` and `runtime: false` so it is not shipped in a release.
+
+## Common mix tasks
+
+```bash
+mix deps.get                         # fetch deps
+mix compile --warnings-as-errors     # gate CI on this
+mix format                           # canonical formatter (write)
+mix format --check-formatted         # CI check (no write)
+mix test                             # run ExUnit
+mix release                          # build a self-contained release
+```
+
+## Config: config.exs vs runtime.exs
+
+| File | Evaluated | Put here |
+|---|---|---|
+| `config/config.exs` | compile time (at build) | static, non-secret, compile-time settings; `import_config "#{config_env()}.exs"` |
+| `config/runtime.exs` | runtime (release boot) | anything from `System.get_env/1` — DB URLs, secrets, ports, hostnames |
+
+`runtime.exs` is the **only** config evaluated inside a built release at startup. Build-time `config.exs` values are frozen into the artifact, so secrets and per-environment values belong in `runtime.exs`:
+
+```elixir
+# config/runtime.exs
+import Config
+
+if config_env() == :prod do
+  config :my_app, MyApp.Repo,
+    url: System.fetch_env!("DATABASE_URL"),
+    pool_size: String.to_integer(System.get_env("POOL_SIZE", "10"))
+end
+```
+
+## mix release
+
+`mix release` bundles your app, its deps, and the Erlang runtime (ERTS) into a tarball that runs on a target with no Elixir/Erlang installed.
+
+```bash
+MIX_ENV=prod mix release
+_build/prod/rel/my_app/bin/my_app start    # foreground
+_build/prod/rel/my_app/bin/my_app daemon   # background
+_build/prod/rel/my_app/bin/my_app remote   # connect a remote IEx shell
+```
+
+Set runtime env vars (read in `runtime.exs`) in the deployment environment, not baked into the image. A release plus a small Docker base image is a common production shape.
+
+## Umbrella projects: when and when not
+
+An umbrella is multiple in-repo apps under one `apps/` directory sharing config and deps.
+
+- **Use** when you have genuinely separate deployables/bounded contexts that you still want versioned and built together.
+- **Do not** reach for it to organize one app — plain `lib/` directories and module namespacing handle that, and umbrellas add ceremony (per-app mix.exs, cross-app dep wiring) you will regret for a single service. Start as one app; split to an umbrella only when a real boundary appears.