claudekit/skills/performance-optimization/SKILL.md

name, argument-hint, description

name	argument-hint	description
performance-optimization	[file or function]	Use when analyzing or optimizing code performance — including profiling, benchmarking, fixing N+1 queries, reducing bundle size, eliminating memory leaks, or improving algorithm complexity. Trigger for keywords like "slow", "performance", "optimize", "profiling", "memory leak", "bundle size", "N+1", "re-render", "benchmark", "latency", "throughput", or any request to make code faster. Also activate when investigating production performance issues or when code review flags performance concerns.

Performance Optimization

When to Use

• Profiling slow code to find bottlenecks
• Fixing N+1 query problems
• Reducing JavaScript bundle size
• Eliminating memory leaks
• Improving algorithm complexity
• Benchmarking before/after optimization
• Investigating production latency issues

When NOT to Use

• Premature optimization — profile first, optimize second
• Caching strategy design — use caching
• Database schema/index design — use databases
• Code structure improvement — use refactoring

---

Quick Reference

Topic	Reference	Key content
Profiling tools	references/profiling.md	Python (cProfile, py-spy, Scalene) and JS/TS (DevTools, Lighthouse, clinic.js)
Anti-patterns	references/anti-patterns.md	N+1 queries, unnecessary re-renders, event loop blocking, memory leaks

---

Optimization Workflow

1. Measure first — profile to find the actual bottleneck
2. Set a target — "reduce p95 latency from 500ms to 100ms"
3. Optimize the hot path — fix the #1 bottleneck, not everything
4. Benchmark before/after — prove the improvement with numbers
5. Check for regressions — ensure correctness wasn't sacrificed

---

Profiling Quick Start

Python

# CPU profiling
python -m cProfile -o output.prof script.py
# Visualize: pip install snakeviz && snakeviz output.prof

# Live profiling (attach to running process)
py-spy top --pid 12345

# Line-by-line profiling
kernprof -lv script.py  # requires @profile decorator

JavaScript/TypeScript

# Bundle analysis
npx webpack-bundle-analyzer stats.json
# or: ANALYZE=true next build

# Node.js profiling
node --prof app.js
clinic doctor -- node app.js

# Benchmarking
npx vitest bench

---

Common Anti-Patterns

Anti-Pattern	Detection	Fix
N+1 queries	django-debug-toolbar, prisma.$on('query')	select_related/joinedload/include
Unnecessary re-renders	React DevTools Profiler	useMemo, useCallback, React.memo
Blocking event loop	clinic doctor, high event loop lag	worker_threads, async variants
Memory leaks	Heap snapshots, growing process.memoryUsage()	Remove listeners, clear refs, bound caches
Unbounded lists	No pagination, full table scans	Cursor pagination, LIMIT
Heavy imports	Bundle analyzer showing large deps	Tree-shaking, import { x }, code splitting

---

Best Practices

1. Profile before optimizing — intuition about bottlenecks is often wrong.
2. Optimize the hot path — 80% of time is spent in 20% of code.
3. Measure, don't guess — use benchmarks with statistical significance.
4. Set clear targets — "faster" is not measurable; "p95 < 100ms" is.
5. Avoid premature optimization — correctness and readability come first.

Common Pitfalls

1. Optimizing cold paths — spending time on code that runs once.
2. Micro-benchmarking without context — 10ns vs 20ns doesn't matter if the DB call takes 50ms.
3. Sacrificing readability — an unreadable optimization is a future bug.
4. Caching without invalidation — stale data is worse than slow data.
5. Ignoring algorithmic complexity — no amount of micro-optimization fixes O(n^2) on large inputs.

---

Related Skills

• systematic-debugging — Investigating slow paths with root-cause rigor
• testing — Benchmarking and perf regression tests
• devops — Deploy-time perf checks