Guide · Agent skill
How to use the Performance Optimization agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The performance-optimization skill is a set of instructions that teaches an AI coding agent to diagnose slow software the way an experienced performance engineer would. It works on frontend pages, backend APIs, database queries and Core Web Vitals. This guide explains what the skill makes the agent do, how to install it, how to ask for it in plain language, and what it needs to work well.
Performance Optimizationaddyosmani/agent-skills · MIT Download the skill Quick start
- 1Download the ZIP. Download the performance-optimization skill as a ZIP file from this page.
- 2Unzip into a skills folder. Unzip it into ~/.claude/skills/ for personal use, or into .claude/skills/ inside your project.
- 3Or upload it in the Claude apps. In the Claude apps, go to Settings, then Capabilities, then Skills, and upload the skill.
- 4Give the agent access to your code. Make sure the agent can read the project code and, if possible, reach profiling tools or logs.
- 5Describe the slow behaviour. Ask in plain words, for example that a page has a poor LCP or an endpoint has N+1 queries.
- 6Measure, fix, and verify. Let the agent establish a baseline, make one targeted fix, and measure again to confirm the improvement.
What the skill makes the agent do
The skill follows a measure-fix-verify process. The agent first establishes a baseline with real data, then finds the actual bottleneck rather than assuming one, makes a single targeted fix, and measures again to confirm the fix helped. If the measurement does not improve, the change is meant to be reverted.
The skill uses standard web vitals targets: LCP (Largest Contentful Paint) should be 2.5 seconds or less, INP (Interaction to Next Paint) 200 milliseconds or less, and CLS (Cumulative Layout Shift) 0.1 or less. It also carries a checklist of common frontend and backend anti-patterns, such as N+1 queries and unbounded data fetching.
- Measure first: Lighthouse, Chrome DevTools Performance tab, the web-vitals library, or application timing logs
- Identify the bottleneck from the symptom, for example a slow first page load, a sluggish interaction or a slow API endpoint
- Make one fix for that bottleneck only
- Measure again and keep or revert the change
- Add monitoring or tests so the regression is caught later
Install the skill from the ZIP download
Download the skill as a ZIP file from this page. Unzip it into one of two locations. For a personal setup that applies to all your projects, use the ~/.claude/skills/ folder. For a single project, use the .claude/skills/ folder inside that project.
If you use the Claude apps instead of a local folder, you can upload the skill in the app under Settings, then Capabilities, then Skills.
- Personal install: ~/.claude/skills/
- Project install: .claude/skills/ inside your project folder
- Claude apps: Settings → Capabilities → Skills, then upload the skill
Trigger the skill with natural requests
You do not need a special command. The skill describes when it applies, so you can describe the problem in ordinary words. It is meant to activate when performance requirements exist, when you suspect a regression, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks.
Give the agent the symptom and, if you have it, the evidence. Data such as a slow endpoint's timing, a Lighthouse report or a query plan lets the agent start from measurements instead of guesses.
- Our product detail page has a poor LCP score. Find the bottleneck and fix it, then measure again.
- The orders API got much slower after last week's change. Check whether it is an N+1 query problem.
- Users say the form lags when they type. Profile the interaction and find out why.
- This list endpoint returns every record at once. Review it for unbounded data fetching.
Example: a slow list endpoint
Suppose a task list page loads owners by querying the database once per task. The skill names this pattern as the most common backend bottleneck. The fix it describes is to fetch the related rows in the same query using a join or include, instead of inside the loop.
The agent should still measure before and after. It should also check that the list is paginated with a limit and a stable order, since the skill treats unbounded fetching as a separate anti-pattern.
// BAD: N+1 — one query per task for the owner
const tasks = await db.tasks.findMany();
for (const task of tasks) {
task.owner = await db.users.findUnique({ where: { id: task.ownerId } });
}
// GOOD: Single query with join/include
const tasks = await db.tasks.findMany({
include: { owner: true },
});What the skill needs to work
The agent needs access to your project's code. It also needs some way to observe the system. The skill works best with profiling tools such as Chrome DevTools, Lighthouse, a database EXPLAIN ANALYZE capability, or an application performance monitoring (APM) tool. Without profiling data, logs or a running system, the agent cannot measure anything.
For real-user monitoring, the web-vitals JavaScript library is optional. Only add it if you want live data from users.
- Access to the project code
- Profiling output, logs or a running system to measure
- Optional: Chrome DevTools, Lighthouse, EXPLAIN ANALYZE, or APM
- Optional: the web-vitals library for real-user monitoring
Safety notes: scripts and network
According to the listing, this skill does not run scripts and does not use the network. It consists of instructions and a reference file, SKILL.md and references/optimization-patterns.md. The agent still works on your code, so review any change it proposes before you merge it, and make sure any measurement it runs is against an environment you are allowed to test.
- Runs scripts: no
- Uses network: no
- Files: SKILL.md and references/optimization-patterns.md
Tips for better results
Do not ask for optimization when nothing is slow. The skill itself warns that optimizing without evidence adds complexity without benefit. Start with a real symptom, such as a poor score, a user complaint, or a suspected regression.
Ask the agent to report the before and after numbers. A fix that does not change the measurement should be reverted, according to the workflow.
- Start from a specific symptom and a number if you have one
- Share profiling output or timings with the agent
- Ask for one fix at a time
- Ask for a regression guard once the fix is verified
What people use it for
- Diagnosing a slow first page load by checking bundle size, render-blocking resources and LCP
- Finding N+1 queries in an API endpoint and fixing them with a join or include
- Investigating a sluggish form or click handler by looking at long main-thread tasks
- Reviewing a change suspected of causing a performance regression
- Checking a list endpoint for missing pagination and a stable sort order
Frequently asked questions
How do I install the performance optimization agent skill?
Download the skill ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into .claude/skills/ inside a project. You can also upload it in the Claude apps under Settings, then Capabilities, then Skills.
Is the performance-optimization skill free and what licence does it use?
The skill is listed under the MIT licence. The listing does not mention any price, so check the source repository for current terms.
What does the agent need to run this skill?
It needs access to your project code and, ideally, profiling tools such as Chrome DevTools, Lighthouse, EXPLAIN ANALYZE or APM. Without profiling data, logs or a running system, it cannot measure anything.
Does the skill run scripts or use the internet?
According to the listing, it does not run scripts and does not use the network. It is made of SKILL.md and a reference file.
Why won't the agent speed up my app with one click?
The skill measures first and only fixes bottlenecks the measurements confirm. If nothing is measurably slow, it advises against optimizing, because that adds complexity without benefit.
How is this different from just asking an AI to make my code faster?
The skill applies a defined workflow: measure, identify the bottleneck, make one fix, then measure again. It also uses the Core Web Vitals targets and a checklist of known anti-patterns, which guides the agent beyond general advice.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
This skill suits developers and teams who have a real slow page, API or Core Web Vitals problem and want a disciplined measure-fix-verify process. It is not a good fit if you have no performance problem yet, or if you expect one-click speedups without access to profiling data or a running system.
Download the skill