performance-optimization

Performance Optimization

Supporting files: This skill has a companion performance checklist. Use text_editor:read with the full path shown in the file tree when this skill is loaded to open performance-checklist.md (sibling to this SKILL.md).

Overview

Measure before optimizing. Performance work without measurement is guessing — and guessing leads to premature optimization that adds complexity without improving what matters. Profile first, identify the actual bottleneck, fix it, measure again. Optimize only what measurements prove matters.

When to Use

• Performance requirements exist in the spec (load time budgets, response time SLAs)
• Users or monitoring report slow behavior
• Core Web Vitals scores are below thresholds
• You suspect a change introduced a regression
• Building features that handle large datasets or high traffic

When NOT to use: Don't optimize before you have evidence of a problem. Premature optimization adds complexity that costs more than the performance it gains.

Core Web Vitals Targets

Metric	Good	Needs Improvement	Poor
LCP (Largest Contentful Paint)	≤ 2.5s	≤ 4.0s	> 4.0s
INP (Interaction to Next Paint)	≤ 200ms	≤ 500ms	> 500ms
CLS (Cumulative Layout Shift)	≤ 0.1	≤ 0.25	> 0.25

The Optimization Workflow

1. MEASURE  → Establish baseline with real data
2. IDENTIFY → Find the actual bottleneck (not assumed)
3. FIX      → Address the specific bottleneck
4. VERIFY   → Measure again, confirm improvement
5. GUARD    → Add monitoring or tests to prevent regression

Step 1: Measure

Frontend — using Agent Zero's browser tool:

1. browser: open → navigate to the page
2. browser: evaluate → inject web-vitals library or read performance entries
3. browser: screenshot → capture visual state
4. Use browser: action=content to read console output for perf logs

For synthetic Lighthouse-style profiling:

# Run via code_execution_tool
npx lighthouse https://localhost:3000 --output=json --quiet