How do I install the Perf skill?

Run npx skillmds@latest add lidessen/perf in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Perf?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

lidessen (@lidessen) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Perf by lidessen — Agent Skill

Name: Perf
Author: lidessen

Perf

Run web UI performance tests for the agent-worker project. Automates build, daemon restart, cache-bust version bump, Lighthouse audit, and metric reporting — all in one command. Use this skill when the user says "run perf", "check performance", "lighthouse", "perf test", "why is it slow", "check TBT", "性能测试", "跑一下性能", or wants to measure/compare web UI performance. Also trigger after making changes to semajsx/style, render, or any web UI component when performance impact needs verification.

lidessen 8e38a26 2 files · 10.0 KB Updated Sep 17, 2026

File contents

Web UI Performance Testing

One-command performance test for the agent-worker web UI.

Usage

Run the full pipeline (build → restart → Lighthouse → report):

bash ~/.claude/skills/perf/scripts/run-perf.sh

Options

Flag	Effect
(none)	Full pipeline: bump version, build, restart daemon, run Lighthouse
`--no-build`	Skip build + version bump (test current deployed code)
`--no-restart`	Skip daemon restart
`--quick`	Skip Lighthouse, do a fast agent-browser DOM check instead

Quick check (no Lighthouse, ~3s)

bash ~/.claude/skills/perf/scripts/run-perf.sh --quick

Returns DOM node count, style element count, list items, buttons — useful for verifying a change didn't break rendering without waiting for a full Lighthouse run.

What the metrics mean

Metric	Target	Why it matters
TBT (Total Blocking Time)	<200ms	Time the main thread is blocked — directly causes "can't click"
TTI (Time to Interactive)	<1s	When the page first becomes fully interactive
FCP (First Contentful Paint)	<0.5s	When the user first sees content
LCP (Largest Contentful Paint)	<1.5s	When the main content is visible
Style & Layout	<100ms	CSS style recalculation + layout — the main bottleneck in this app
Long Tasks	0 >500ms	Tasks that block the event loop — causes UI freezes

Comparing runs

The script automatically saves the previous Lighthouse report and shows deltas:

  TBT  ✗ 4,290 ms  (-2000ms)    ← improved by 2 seconds
  Style & Layout: 2000ms  (-6000ms)  ← big improvement

Common performance issues in this project

semajsx/style CSS injection — Each rule() call injects CSS. If injectStyles() modifies <style>.textContent N times synchronously, it causes N CSSOM rebuilds. Fix: batch into buffer, flush once per microtask.
Signal-driven DOM replacement — computed signal updates call renderValueToNode which creates an entire new DOM subtree and replaces the old one. No diffing. Large lists (50+ channel messages, event lists) cause heavy layout work.
Channel message history — loadChannelHistory fetches all messages and sets them at once on the signal, triggering synchronous DOM creation for every message. Fix: limit initial fetch, implement virtual scrolling, or defer rendering.
Build cache — semajsx/style resolves to the umbrella package's pre-built dist/. After changing semajsx source, must rebuild both packages/style AND packages/semajsx:
```
cd vendor/semajsx/packages/style && bun run build
cd vendor/semajsx/packages/semajsx && bun run build
```

Workflow

Typical performance debugging cycle:

bash ~/.claude/skills/perf/scripts/run-perf.sh — baseline
Make a change
bash ~/.claude/skills/perf/scripts/run-perf.sh — compare
Read the delta — did TBT/Style&Layout improve?
Repeat

---name: perfdescription: Run web UI performance tests for the agent-worker project. Automates build, daemon restart, cache-bust version bump, Lighthouse audit, and metric reporting — all in one command. Use this skill when the user says "run perf", "check performance", "lighthouse", "perf test", "why is it slow", "check TBT", "性能测试", "跑一下性能", or wants to measure/compare web UI performance. Also trigger after making changes to semajsx/style, render, or any web UI component when performance impact needs verification.---# Web UI Performance TestingOne-command performance test for the agent-worker web UI.## UsageRun the full pipeline (build → restart → Lighthouse → report):```bashbash ~/.claude/skills/perf/scripts/run-perf.sh```### Options| Flag | Effect || -------------- | ------------------------------------------------------------------ || (none) | Full pipeline: bump version, build, restart daemon, run Lighthouse || `--no-build` | Skip build + version bump (test current deployed code) || `--no-restart` | Skip daemon restart || `--quick` | Skip Lighthouse, do a fast agent-browser DOM check instead |### Quick check (no Lighthouse, ~3s)```bashbash ~/.claude/skills/perf/scripts/run-perf.sh --quick```Returns DOM node count, style element count, list items, buttons — useful for verifyinga change didn't break rendering without waiting for a full Lighthouse run.## What the metrics mean| Metric | Target | Why it matters || ---------------------------------- | -------- | ------------------------------------------------------------------ || **TBT** (Total Blocking Time) | <200ms | Time the main thread is blocked — directly causes "can't click" || **TTI** (Time to Interactive) | <1s | When the page first becomes fully interactive || **FCP** (First Contentful Paint) | <0.5s | When the user first sees content || **LCP** (Largest Contentful Paint) | <1.5s | When the main content is visible || **Style & Layout** | <100ms | CSS style recalculation + layout — the main bottleneck in this app || **Long Tasks** | 0 >500ms | Tasks that block the event loop — causes UI freezes |## Comparing runsThe script automatically saves the previous Lighthouse report and shows deltas:``` TBT ✗ 4,290 ms (-2000ms) ← improved by 2 seconds Style & Layout: 2000ms (-6000ms) ← big improvement```## Common performance issues in this project1. **semajsx/style CSS injection** — Each `rule()` call injects CSS. If `injectStyles()` modifies `<style>.textContent` N times synchronously, it causes N CSSOM rebuilds. Fix: batch into buffer, flush once per microtask.2. **Signal-driven DOM replacement** — `computed` signal updates call `renderValueToNode` which creates an entire new DOM subtree and replaces the old one. No diffing. Large lists (50+ channel messages, event lists) cause heavy layout work.3. **Channel message history** — `loadChannelHistory` fetches all messages and sets them at once on the signal, triggering synchronous DOM creation for every message. Fix: limit initial fetch, implement virtual scrolling, or defer rendering.4. **Build cache** — `semajsx/style` resolves to the umbrella package's pre-built `dist/`. After changing semajsx source, must rebuild both `packages/style` AND `packages/semajsx`: ```bash cd vendor/semajsx/packages/style && bun run build cd vendor/semajsx/packages/semajsx && bun run build ```## WorkflowTypical performance debugging cycle:1. `bash ~/.claude/skills/perf/scripts/run-perf.sh` — baseline2. Make a change3. `bash ~/.claude/skills/perf/scripts/run-perf.sh` — compare4. Read the delta — did TBT/Style&Layout improve?5. Repeat

Frequently asked questions