elixir-performance-review — Claude Code skill: what it does
elixir-performance-review is a Claude Code skill that checks Elixir code for GenServer, memory and concurrency bottlenecks when a service slows under load, with findings backed by measurement.
Apache-2.0 107 installs ★ 89 updated 2026-09-15
npx skills add existential-birds/beagle --skill elixir-performance-review -a claude-codeWhat elixir-performance-review does
The skill walks Elixir code through a four-part checklist: GenServer, memory, concurrency, database. Each part points to a reference file (references/genserver-bottlenecks.md, references/ets-patterns.md, references/memory.md, references/concurrency.md), so the agent reads focused notes instead of improvising.
A Valid Patterns section lists what to leave alone. A single GenServer under light load, synchronous calls on a critical path, Enum over Stream for small collections. Context-Sensitive Rules set the thresholds: flag a GenServer bottleneck only above 1000 requests per second or with blocking I/O in callbacks, suggest streams past 10k items, reach for ETS when the read-to-write ratio is above 10:1.
Gates come before any report. Every finding needs a locator such as path:line or Module.function/arity with a quoted snippet, and a claim about a bottleneck or N+1 needs a measured fact or an artifact like profiler output. The first gate sends the agent to review-verification-protocol in the same collection; skip that skill and the review never clears its checks.
What it helps with
- find blocking calls inside
handle_call - decide when GenServer state belongs in ETS
- catch N+1 queries around preloads
- check whether large binaries get copied between processes
- add backpressure to a message producer
Example prompts for the agent
- Review
lib/orders/queue.exfor performance, starting with the GenServer callbacks and binary handling. - Audit the worker for concurrency issues, especially unbounded process spawning.
- Look at
Stats.Cacheand tell me if reads should move to ETS.
How to install elixir-performance-review
1Skills CLI (Vercel)
npx skills add existential-birds/beagle --skill elixir-performance-review -a claude-code2Manually: put the files in place
~/.claude/skills/elixir-performance-review/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/elixir-performance-review/
1Skills CLI (Vercel)
npx skills add existential-birds/beagle --skill elixir-performance-review -a codex2Manually: put the files in place
.agents/skills/elixir-performance-review/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add existential-birds/beagle --skill elixir-performance-review -a cursor2Manually: put the files in place
.cursor/skills/elixir-performance-review/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install existential-birds/beagle plugins/beagle-elixir/skills/elixir-performance-review2Manually: put the files in place
.github/skills/elixir-performance-review/SKILL.md1Skills CLI (Vercel)
npx skills add existential-birds/beagle --skill elixir-performance-review -a gemini-cli2Platform CLI
gemini skills install https://github.com/existential-birds/beagle --path plugins/beagle-elixir/skills/elixir-performance-reviewManually: put the files in place
.devin/skills/elixir-performance-review/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add existential-birds/beagle --skill elixir-performance-review -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about elixir-performance-review
How to install elixir-performance-review in Claude Code?
Run npx skills add existential-birds/beagle --skill elixir-performance-review -a claude-code. The skill then lives at ~/.claude/skills/elixir-performance-review/SKILL.md.
What does elixir-performance-review do?
It runs Elixir code through a performance checklist covering GenServer, memory, concurrency and database access. Each finding has to point at a file location and rest on a measurement.
What does the skill need to work?
The review-verification-protocol skill from the same repository, since its checks are a mandatory gate before the report. Claims about load also need measurements or profiler output.
Source text
SKILL.md · Apache-2.0
--- name: elixir-performance-review description: Reviews Elixir code for performance issues including GenServer bottlenecks, memory usage, and concurrency patterns. Use when reviewing high-throughput code or investigating performance issues. --- # Elixir Performance Review ## Quick Reference | Issue Type | Reference | |------------|-----------| | Mailbox overflow, blocking calls | [references/genserver-bottlenecks.md](references/genserver-bottlenecks.md) | | When to use ETS, read/write concurrency | [references/ets-patterns.md](references/ets-patterns.md) | | Binary handling, large messages | [references/memory.md](references/memory.md) | | Task patterns, flow control | [references/concurrency.md](references/concurrency.md) | ## Review Checklist ### GenServer - [ ] Not a single-process bottleneck for all requests - [ ] No blocking operations in handle_call/cast - [ ] Proper timeout configuration - [ ] Consider ETS for read-heavy state ### Memory - [ ] Large binaries not copied between processes - [ ] Streams used for large data transformations - [ ] No unbounded data accumulation ### Concurrency - [ ] Task.Supervisor for dynamic tasks (not raw Task.async) - [ ] No unbounded process spawning - [ ] Proper backpressure for message producers ### Database - [ ] Preloading to avoid N+1 queries - [ ] Pagination for large result sets - [ ] Indexes for frequent queries ## Valid Patterns (Do NOT Flag) - **Single GenServer for low-throughput** - Not all state needs horizontal scaling - **Synchronous calls for critical paths** - Consistency may require it - **In-memory state without ETS** - ETS has overhead for small state - **Enum over Stream for small collections** - Stream overhead not worth it ## Context-Sensitive Rules | Issue | Flag ONLY IF | |-------|--------------| | GenServer bottleneck | Handles > 1000 req/sec OR blocking I/O in callbacks | | Use streams | Processing > 10k items OR reading large files | | Use ETS | Read:write ratio > 10:1 AND concurrent access | ## Gates — before reporting Do these **in order** for the performance review. Do not publish findings until each step passes. 1. **Protocol loaded** — Read [review-verification-protocol](../review-verification-protocol/SKILL.md) and apply its checks for each finding (hot paths, concurrency, resource use). **Pass:** For every substantive finding, you can name which protocol subsection you satisfied or state **N/A** with reason (e.g. pure reference to this skill’s Valid Patterns). 2. **Anchored evidence** — **Pass:** Each finding includes a concrete locator: `path:line` (or line range), or `Module.function/arity` plus a short quoted snippet from the file. 3. **Performance claims** — For anything under [Context-Sensitive Rules](#context-sensitive-rules), or any claim of bottleneck, N+1, unbounded growth, or heavy memory/binary cost, **Pass:** You state the **observed or measured** fact that meets “Flag ONLY IF” (e.g. rate, item count, ratio), or attach an artifact (profiler output, SQL/log excerpt, `grep`/search scope)—otherwise downgrade to **question** / **suspected** with what was not verified. ## Before Submitting Findings Complete **Gates — before reporting** (section above) first; the verification protocol is mandatory input to those gates.
© existential-birds · Apache-2.0 · existential-birds/beagle