# perf-analyzer
A Claude Code skill that delivers comprehensive frontend performance audits with actionable improvement plans.
This isn't a checklist. It's a methodology for diagnosing performance issues and fixing them systematically.
## What you get
When you invoke `/perf-expert`, you receive:
1. **Current state assessment** with Lighthouse scores and Core Web Vitals
2. **Issues found** categorized by severity (critical, moderate, minor)
3. **Specific fixes** with file paths, line numbers, and code changes
4. **Expected impact** for each fix
5. **Priority order** for maximum impact with minimum effort
## Skill structure
```
perf-expert/
├── SKILL.md # Core instructions (~180 lines)
├── references/
│ ├── performance.md # Scripts, fonts, images, bundles
│ ├── accessibility.md # Focus, ARIA, keyboard, contrast
│ ├── browser-gotchas.md # Safari bugs, minifier issues
│ └── report-template.md # Audit summary format
├── README.md
└── LICENSE
```
## Installation
**Claude Code**: Add this folder as a skill.
```bash
mkdir -p .claude/skills/perf-expert
curl -o .claude/skills/perf-expert/SKILL.md \
https://raw.githubusercontent.com/hardikpandya/perf-analyzer/main/SKILL.md
```
Download reference files for deep dives:
```bash
mkdir -p .claude/skills/perf-expert/references
curl -o .claude/skills/perf-expert/references/performance.md \
https://raw.githubusercontent.com/hardikpandya/perf-analyzer/main/references/performance.md
curl -o .claude/skills/perf-expert/references/accessibility.md \
https://raw.githubusercontent.com/hardikpandya/perf-analyzer/main/references/accessibility.md
curl -o .claude/skills/perf-expert/references/browser-gotchas.md \
https://raw.githubusercontent.com/hardikpandya/perf-analyzer/main/references/browser-gotchas.md
curl -o .claude/skills/perf-expert/references/report-template.md \
https://raw.githubusercontent.com/hardikpandya/perf-analyzer/main/references/report-template.md
```
**Claude Projects**: Upload `SKILL.md` and reference files to project knowledge.
**API calls**: Include `SKILL.md` in your system prompt. Reference files load on demand.
## Usage
```bash
/perf-expert # Full audit
/perf-expert performance # Performance focus
/perf-expert a11y # Accessibility focus
/perf-expert seo # SEO focus
```
## What makes this different
### It delivers actionable fixes, not vague advice
Generic advice like "optimize images" is useless. This skill tells you:
- Which files to change and what line numbers
- The exact code to add or remove
- How much improvement to expect
### It's battle-tested
Every recommendation comes from real production issues:
- The Safari bug where CSS variables in `@keyframes` silently fail
- The Jekyll minifier that breaks `calc()` expressions
- The invisible CLS from web fonts that only shows on slow 3G
### It knows the targets
| Metric | Good | Needs work | Poor |
|--------|------|------------|------|
| LCP | < 2.5s | 2.5-4s | > 4s |
| INP | < 200ms | 200-500ms | > 500ms |
| CLS | < 0.1 | 0.1-0.25 | > 0.25 |
| TTFB | < 800ms | 800ms-1.8s | > 1.8s |
Lighthouse scores are vanity metrics. Core Web Vitals are what Google ranks you on.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | Core instructions and audit methodology |
| `references/performance.md` | Scripts, fonts, images, bundle optimization |
| `references/accessibility.md` | Focus states, ARIA, keyboard navigation |
| `references/browser-gotchas.md` | Safari bugs, minifier issues, edge cases |
| `references/report-template.md` | Audit report format |
## Real results
Developed while optimizing [hvpandya.com](https://hvpandya.com):
- **Font bundle**: 74MB → 3MB (excluded 48 unused font families)
- **LCP**: 4.2s → 2.3s (font preloading + `font-display: swap`)
- **Accessibility score**: 88 → 98 (focus states, ARIA labels, keyboard nav)
- **Fixed**: Safari animation bug that silently broke emoji reactions
## When to skip this
- **Prototypes**: Ship fast, optimize later
- **Internal tools**: User tolerance is higher
- **MVP validation**: Learn first, polish second
Performance optimization has diminishing returns. Know when good enough is good enough.
## Contributing
Found a technique that's not covered? Discovered a browser quirk? Open a PR.
The best contributions include:
- The problem you encountered
- Why the obvious solution didn't work
- What actually fixed it
- How to verify the fix
## License
MIT
## Author
[Hardik Pandya](https://hvpandya.com)