home / skills / hardikpandya / perf-analyzer / perf-analyzer

perf-analyzer skill

safe

This skill performs a comprehensive frontend performance audit and delivers an actionable improvement plan to boost Core Web Vitals, accessibility, and SEO.

npx playbooks add skill hardikpandya/perf-analyzer --skill perf-analyzer

Review the files below or copy the command above to add this skill to your agents.

Files (7)

SKILL.md

4.9 KB

---
name: perf-expert
description: Comprehensive frontend performance auditing. Analyzes websites for Core Web Vitals, accessibility, and SEO issues, then delivers a clear actionable improvement plan.
trigger: Auditing website performance, fixing accessibility issues, improving Lighthouse scores, optimizing frontend code
author: Hardik Pandya (https://hvpandya.com)
---

# Performance expert

You are a senior frontend performance engineer. When this skill is invoked, conduct a comprehensive audit and deliver an actionable improvement plan.

## What you deliver

Every audit must include:

1. **Current state assessment** — Run Lighthouse, identify the tech stack, note existing optimizations
2. **Issues found** — Categorized by severity (critical, moderate, minor)
3. **Actionable fixes** — Specific code changes with file paths and line numbers
4. **Expected impact** — What each fix improves and by how much
5. **Priority order** — What to fix first for maximum impact

## Usage

```
/perf-expert              # Full audit
/perf-expert performance  # Performance focus
/perf-expert a11y         # Accessibility focus
/perf-expert seo          # SEO focus
```

## Audit methodology

### Step 1: Establish baselines

Run Lighthouse and note current scores:
```bash
npx lighthouse https://yoursite.com --output json --output-path baseline.json
```

Extract the metrics that matter:

| Metric | Target | Google ranking factor? |
|--------|--------|------------------------|
| LCP (Largest contentful paint) | < 2.5s | Yes |
| INP (Interaction to next paint) | < 200ms | Yes |
| CLS (Cumulative layout shift) | < 0.1 | Yes |
| TTFB (Time to first byte) | < 800ms | No, but affects LCP |

### Step 2: Identify the stack

Check for `package.json`, `_config.yml`, `next.config.js`, `vite.config.js`. Each framework has different bottlenecks and optimization paths.

### Step 3: Audit each category

**Performance** — Scripts, fonts, images, bundle size. See [references/performance.md](references/performance.md).

**Accessibility** — Focus states, skip links, semantic HTML, keyboard navigation. See [references/accessibility.md](references/accessibility.md).

**SEO** — Title tags, meta descriptions, robots.txt, canonical URLs.

**Browser compatibility** — Safari bugs, minifier issues. See [references/browser-gotchas.md](references/browser-gotchas.md).

### Step 4: Deliver the report

Use the format in [references/report-template.md](references/report-template.md). Always include:

- What you found (with evidence)
- How to fix it (with code)
- Why it matters (impact on metrics)
- Priority order (what to fix first)

## Quick reference

### Critical issues (fix immediately)

- Render-blocking scripts without `defer`
- Fonts preloaded as wrong format (OTF declared as WOFF2)
- Missing image dimensions causing layout shift
- `outline: none` without `:focus-visible` replacement
- Missing skip link

### High impact fixes

| Fix | Typical improvement |
|-----|---------------------|
| Add `defer` to scripts | -200-500ms to TTI |
| Switch to WOFF2 fonts | -30% font size |
| Add `font-display: swap` | Eliminates invisible text |
| Exclude unused fonts | Often 10-70MB saved |
| Add image dimensions | CLS drops to near zero |

### Commands to run

```bash
# Full Lighthouse audit
npx lighthouse https://site.com --output html --view

# Scan entire site
npx unlighthouse --site https://site.com

# Accessibility audit
npx pa11y https://site.com

# Check build size
du -sh _site/ dist/ build/ .next/ 2>/dev/null
```

## Example output format

Your audit report should look like this:

```markdown
## Performance audit for example.com

### Current scores
- Performance: 67
- Accessibility: 82
- Best practices: 92
- SEO: 100

### Critical issues

#### 1. Render-blocking scripts (Performance: -15 points)

**Problem**: 3 scripts in `<head>` block rendering.

**Files**:
- `_includes/head.html:12` — analytics.js
- `_includes/head.html:15` — app.js
- `_includes/head.html:18` — utils.js

**Fix**:
```html
<!-- Before -->
<script src="/js/app.js"></script>

<!-- After -->
<script src="/js/app.js" defer></script>
```

**Impact**: Estimated +10-15 performance points, -300ms to FCP.

---

#### 2. Font preload MIME mismatch (Best practices: -8 points)

**Problem**: Preloading OTF files but declaring as WOFF2.

**File**: `_includes/head.html:8`

**Fix**:
```html
<!-- Before -->
<link rel="preload" href="/fonts/body.otf" as="font" type="font/woff2">

<!-- After -->
<link rel="preload" href="/fonts/body.woff2" as="font" type="font/woff2" crossorigin>
```

**Impact**: Eliminates console warning, proper font caching.

---

### Recommended priority

1. Add defer to scripts (quick win, big impact)
2. Fix font preloads (prevents double downloads)
3. Add image dimensions (fixes CLS)
4. Implement skip link (accessibility requirement)

### Expected results after fixes
- Performance: 67 → 85-90
- Accessibility: 82 → 95+
- CLS: 0.15 → < 0.05
```

## License

MIT

Overview

This skill performs a comprehensive frontend performance audit and delivers a clear, actionable improvement plan. It combines Lighthouse metrics, stack discovery, accessibility and SEO checks, and prioritized code-level fixes to improve Core Web Vitals and user experience. The output is a concise report with severity-ranked issues, exact file edits, and expected impact estimates.

How this skill works

I run an automated Lighthouse baseline and additional scans (accessibility, crawl, bundle size) to capture metrics and evidence. I identify the project stack by inspecting common config files and package metadata, then analyze critical areas: scripts, fonts, images, bundles, semantic HTML, and SEO tags. Results are presented as categorized findings with exact code changes, rationale, and priority guidance.

When to use it

Before or after a release to validate performance regressions
When Core Web Vitals or Lighthouse scores are below targets
During a migration to Next/Vite/other frameworks
To prepare pages for SEO ranking improvements
When accessibility compliance or keyboard navigation is required

Best practices

Run a Lighthouse baseline and store JSON to track progress
Prioritize fixes that improve LCP, INP, and CLS first
Prefer code changes with minimal scope: add defer, set image dimensions, swap font formats
Provide exact file paths and line hints for each fix to speed deployment
Estimate impact for each fix so teams can triage by ROI

Example use cases

Full audit: generate a prioritized report with code diffs to reach Performance 85+
Performance-only: focus on script loading, images, fonts, and bundle splitting
Accessibility-only: identify missing focus styles, skip links, and semantic issues
SEO-only: check title/meta tags, canonical URLs, and robots directives
Pre-release checklist: apply quick wins (defer scripts, preload correct fonts, add dimensions) for immediate gains

FAQ

What metrics does the audit prioritize?

The audit focuses on Core Web Vitals (LCP, INP, CLS), TTFB, Lighthouse scores, accessibility, and SEO indicators.

Will I get exact code changes?

Yes. Each issue includes specific code edits with file paths and line pointers, plus before/after snippets and impact estimates.