performance-engineer

Overview of performance-engineer skill

What the performance-engineer skill does

The performance-engineer skill is a focused troubleshooting and optimization workflow for diagnosing slow systems, finding bottlenecks, and turning vague complaints like “this endpoint is slow” into measurable fixes. It is built for performance optimization work rather than general code review, so its value is in forcing a baseline-measure-profile-verify loop instead of guessing.

Who should use performance-engineer

This skill fits developers, SREs, backend engineers, and AI-agent users who already have a system to inspect and want help narrowing down where time, memory, or throughput is being lost. It is especially useful when you have a reproducible slowdown, latency target, or suspected hotspot but do not want to start from a blank prompt.

The real job-to-be-done

Most users do not just want “faster code.” They need to answer practical questions:

• What metric is actually bad?
• Where is the bottleneck: database, API, frontend, network, or runtime?
• What should be measured before changing code?
• How do we prove the optimization helped and did not regress behavior?

The performance-engineer skill is strongest when used to structure that investigation.

Why this skill is different from a generic prompt

A generic prompt often jumps straight to speculative fixes. This skill is better for performance optimization because it explicitly centers:

• baseline metrics and targets
• profiling before optimization
• bottleneck location by layer
• validation after changes
• lightweight reporting and profiling templates from scripts/

That makes it more usable for real engineering work, not just idea generation.

What to check before installing

This skill is a good fit if you can provide:

• a codebase or endpoint to inspect
• a reproducible slow path
• at least one measurable performance target
• permission to run profiling, logs, or benchmark commands

It is a weaker fit if your issue is mainly correctness, architecture selection, or cost estimation without any observed performance symptoms.

How to Use performance-engineer skill

How to install performance-engineer

Install from the repository collection with:

npx skills add https://github.com/zhaono1/agent-playbook --skill performance-engineer

If you are evaluating the skill before install, inspect:

• skills/performance-engineer/SKILL.md
• skills/performance-engineer/README.md
• skills/performance-engineer/references/checklist.md
• skills/performance-engineer/references/monitoring.md
• skills/performance-engineer/references/optimization.md
• skills/performance-engineer/scripts/profile.py
• skills/performance-engineer/scripts/perf_report.py

What inputs the performance-engineer skill needs

The performance-engineer skill works best when you give it operational context, not just code. Strong inputs include:

• the slow endpoint, query, page, job, or command
• current versus target latency, throughput, memory, or CPU
• environment details such as language, framework, runtime, and infra
• how to reproduce the issue
• any existing profiler output, traces, or logs
• suspected layer: DB, API, frontend, network, caching, or compute

Without that, the skill can still suggest a process, but output quality drops because it must infer too much.

Turn a vague request into a strong prompt

Weak:

Optimize this code.

Better:

Use the performance-engineer skill on this Python API endpoint. Current p95 latency is 1.4s, target is under 500ms. Traffic spikes at 50 concurrent requests. We use PostgreSQL and Redis. Please identify what to measure first, likely bottlenecks, profiling commands to run, and the order of fixes to test.

Why this is better:

• it defines the metric
• it gives the target
• it names the workload
• it narrows the likely bottleneck layers
• it asks for an investigation sequence, not random tweaks

Recommended workflow in practice

A good performance-engineer usage pattern is:

1. Define the affected user path or system operation.
2. Record baseline metrics.
3. Profile or inspect the slow path.
4. Map findings to likely bottleneck layers.
5. propose the smallest high-impact fix first.
6. Re-measure after each change.
7. Document findings and regression checks.

This mirrors the skill's own phase structure and keeps optimization grounded in evidence.

Repository files to read first

Read these in order if you want the fastest adoption path:

1. SKILL.md for activation cues and the analysis phases
2. references/checklist.md for the minimum process discipline
3. references/optimization.md for common optimization levers
4. references/monitoring.md for what to track after rollout
5. README.md for sample targets and helper scripts

The scripts are not profilers themselves; they are templates that help standardize investigation output.

Built-in scripts that support usage

Two support scripts add practical value to this performance-engineer guide:

• python scripts/profile.py generates a profile template with environment, workload, and hotspot fields.
• python scripts/perf_report.py generates a markdown report for summary, ownership, baseline metrics, findings, recommendations, and validation.

Example:

python scripts/profile.py --name "checkout latency" --tool "cProfile" --command "python app.py" --duration "60s"
python scripts/perf_report.py --name "checkout API" --owner "payments-team"

These are useful when you want repeatable investigation notes instead of one-off chat output.

What the skill is optimized to detect

The source material points users toward common bottleneck locations such as:

• database issues like N+1 queries, missing indexes, or large result sets
• API over-fetching or inefficient serialization
• runtime hotspots found via profiler output
• payload and network inefficiencies
• caching gaps on hot paths

That means the skill is most valuable when there is an actual bottleneck to isolate, not just a broad desire to “make everything faster.”

Practical prompt pattern for better results

Use this structure when invoking performance-engineer for Performance Optimization:

Use the performance-engineer skill.

System:
- Service/page/job:
- Language/framework:
- Infra/dependencies:

Problem:
- Symptom:
- Current metric:
- Target metric:
- Reproduction steps:

Evidence:
- Logs/traces/profile snippets:
- Suspected bottleneck layer:

Task:
- Define measurement plan
- Identify likely root causes
- Recommend ordered fixes
- Specify how to validate improvement

This prompt pattern usually produces more actionable output than a plain “why is this slow?” request.

Common adoption blockers

Before relying on the performance-engineer install, note the main limitations:

• it does not replace real profilers or APM tools
• it needs measurable symptoms to be effective
• it is less helpful when the workload cannot be reproduced
• it cannot validate gains unless you provide a benchmark path

In other words, the skill improves the investigation method; it does not magically generate trustworthy measurements on its own.

When to use ordinary prompts instead

If you just need quick code-style cleanup, micro-optimizations in a tiny script, or language-specific tuning advice without investigation, a standard prompt may be enough. Use the performance-engineer skill when stakes are higher and you need a structured path from symptom to verified fix.

performance-engineer skill FAQ

Is performance-engineer good for beginners?

Yes, if the beginner already has a concrete slow scenario. The skill provides a disciplined sequence—baseline, profile, bottleneck, validate—that helps avoid premature optimization. It is less beginner-friendly if you expect it to teach full observability or benchmarking fundamentals from scratch.

What makes performance-engineer better than asking an AI to optimize code?

The main difference is process control. A normal prompt often suggests caching, indexing, async work, or refactors immediately. The performance-engineer skill is more useful when you need to first determine whether the problem is in the database, API layer, memory behavior, payload size, or runtime hotspot.

Does the skill include real tooling?

Partially. The repository includes template generators in scripts/profile.py and scripts/perf_report.py, plus reference docs for checklist, monitoring, and optimization levers. You still need your own runtime profilers, logs, benchmarks, and environment-specific commands.

Is performance-engineer only for backend services?

No. The README includes performance targets that span APIs and page-load style metrics, and the references mention payload and network efficiency. Still, the examples skew more toward application and service investigation than deep frontend rendering analysis.

When should I not use performance-engineer?

Skip it when:

• there is no measurable performance problem yet
• you only want broad architecture brainstorming
• the issue is reliability or correctness rather than speed
• you cannot reproduce the workload or collect any metrics

In those cases, the structure of the skill adds less value.

Can performance-engineer help with monitoring after fixes?

Yes. references/monitoring.md pushes users to track percentiles, throughput, error rates, and alerts on regressions. That is useful if you want the skill to support rollout validation, not just one-time tuning.

How to Improve performance-engineer skill

Give better baselines, not just bigger prompts

The fastest way to improve performance-engineer usage is to provide:

• current p50, p95, or p99 latency
• throughput and error rate
• memory or CPU symptoms
• exact benchmark or request path
• before-and-after comparison plan

This is more valuable than adding long narrative context.

Include environment and workload shape

Performance advice changes with workload. Tell the skill:

• request concurrency
• dataset size
• cache warm or cold state
• CPU and memory constraints
• local, staging, or production environment

The included scripts/profile.py template is a good reminder of what to capture: environment, workload, command, duration, and hotspots.

Ask for ranked fixes with validation steps

A strong follow-up prompt is:

Use the performance-engineer skill to rank the top three likely bottlenecks by expected impact and confidence. For each, give the measurement to confirm it, the smallest fix to test, and the benchmark to verify improvement.

This reduces vague “try everything” output and makes iteration cheaper.

Avoid common failure modes

The most common ways users get weak results from performance-engineer are:

• no baseline metrics
• no reproducible workload
• no profiler or trace evidence
• asking for fixes before isolating the bottleneck
• combining multiple systems into one vague request

If your first result feels generic, one of those is usually missing.

Use the checklist as a quality gate

references/checklist.md is short but important. Treat it as the minimum standard:

• baseline metrics recorded
• bottlenecks identified
• fixes verified with benchmarks
• regression tests added

That checklist is where this skill becomes operational rather than advisory.

Document findings so the next iteration is better

After the first pass, generate a report with scripts/perf_report.py and feed it back into the next run. This helps the performance-engineer skill refine recommendations using actual findings, ownership, and validation notes instead of starting fresh each time.

Improve prompts with evidence snippets

Instead of saying “DB seems slow,” paste a compact evidence block such as:

• query duration sample
• profiler top functions
• trace span summary
• endpoint timings by percentile

Even partial evidence sharply improves output quality because the skill can connect recommendations to observed hotspots rather than defaults.

Know the boundary between diagnosis and implementation

The performance-engineer for Performance Optimization workflow is strongest at diagnosis, prioritization, and validation planning. It becomes more effective when paired with a second pass that focuses on implementing the chosen fix in your stack. Use it first to decide what matters, then use coding help to apply the change safely.