python-performance-optimization

Overview of python-performance-optimization skill

What the python-performance-optimization skill does

The python-performance-optimization skill helps an agent diagnose why Python code is slow or memory-heavy, then propose targeted fixes grounded in profiling rather than guesswork. It is built for practical performance work: finding bottlenecks, separating CPU vs memory vs I/O issues, and choosing improvements that actually match the code path under load.

Who should install it

This skill is best for developers, data engineers, backend teams, and agent workflows that need more than generic “make this faster” advice. It is especially useful when you have a real script, service, notebook, or pipeline that already works functionally but needs better latency, throughput, or memory behavior.

Real job-to-be-done

Most users do not need a lecture on Big O alone—they need a repeatable way to answer:

• what is slow
• how to measure it correctly
• which optimization is worth doing first
• how to avoid changing code that is not the bottleneck

That is where the python-performance-optimization skill is stronger than a normal prompt. It pushes the workflow toward profiling first, then optimization.

What makes this skill different

The repository covers multiple profiling modes and optimization layers instead of treating performance as one problem. It spans:

• CPU profiling
• memory profiling
• line-level analysis
• call-graph thinking
• implementation patterns like caching
• advanced paths such as NumPy vectorization, async I/O, and parallelization

The practical differentiator is breadth with a profiling-first mindset.

Best-fit and misfit cases

Good fit:

• slow Python endpoints, jobs, CLI tools, ETL, or data processing
• memory growth or unexplained RAM spikes
• choosing between caching, algorithm changes, vectorization, or concurrency
• preparing optimization plans before touching production code

Poor fit:

• codebases where the real bottleneck is infrastructure, network topology, or database schema and no measurements are available
• teams looking for fully automated benchmarking scripts out of the box
• situations where you only want style cleanup, not performance diagnosis

How to Use python-performance-optimization skill

Install context for python-performance-optimization install

Install the skill from the wshobson/agents repository:

npx skills add https://github.com/wshobson/agents --skill python-performance-optimization

After installation, use it when your prompt clearly involves Python performance diagnosis, profiling, memory usage, latency reduction, throughput improvement, or bottleneck analysis.

Read these repository files first

For fastest understanding, start here:

1. plugins/python-development/skills/python-performance-optimization/SKILL.md
2. plugins/python-development/skills/python-performance-optimization/references/advanced-patterns.md

SKILL.md gives the main workflow and tool categories. references/advanced-patterns.md is the useful second read when the first-pass diagnosis points toward vectorization, caching, memory tuning, async I/O, or database-heavy work.

What input the skill needs to work well

The python-performance-optimization usage quality depends heavily on the evidence you provide. Give the agent:

• the slow function, file, endpoint, or job
• expected workload size
• actual symptoms: latency, CPU saturation, memory growth, timeout, high query count
• profiling output if available
• constraints: cannot add dependencies, must preserve API, production-safe only, etc.
• environment details: Python version, framework, OS, single process vs multi-process

Without those inputs, the skill can still suggest profiling steps, but recommendations will be less specific.

Turn a rough request into a strong prompt

Weak prompt:

• “Optimize this Python code.”

Better prompt:

• “Use the python-performance-optimization skill to analyze this Django view. P95 latency is 1.8s under ~200 requests/min. CPU is high, memory is stable. Here is the view code and a cProfile summary. Identify the top bottlenecks, explain whether the issue is Python execution, DB access, or serialization, and propose fixes ranked by expected impact and implementation risk.”

This works better because it supplies workload, symptom type, evidence, and output format.

Ask for diagnosis before asking for rewrites

A good workflow is:

1. describe the performance symptom
2. provide code and measurement data
3. ask the agent to classify the bottleneck
4. only then ask for code changes

This avoids premature rewrites. The python-performance-optimization skill is more useful when it can reason from metrics to intervention.

Profiling inputs that materially improve output

Best inputs include:

• cProfile summaries for CPU-heavy code
• line-profiler results for hot functions
• memory-profiler or object growth evidence for RAM issues
• timing breakdowns around I/O, DB, HTTP, and serialization boundaries
• representative sample data, not toy inputs

If you have no measurements yet, ask the agent to design a profiling plan first rather than to optimize blindly.

Typical workflow the skill supports

A practical python-performance-optimization guide usually looks like:

1. identify the performance goal
2. choose the right profiling type
3. profile representative workloads
4. find the hottest paths or biggest allocations
5. select the lowest-risk, highest-impact optimization
6. benchmark before and after
7. watch for regressions in correctness and readability

This sequence is the main value of the skill.

When to use the advanced reference

Open references/advanced-patterns.md when the bottleneck is likely in one of these areas:

• numerical loops that may benefit from NumPy
• repeated pure-function work that may benefit from functools.lru_cache
• high-I/O workloads that may benefit from async patterns
• expensive parallelizable work where multiprocessing might help
• query-heavy applications that need database optimization thinking

Do not jump there first unless you already know the category. Start from measured bottlenecks.

Good prompt patterns for common cases

For CPU-bound code:

• “Use the python-performance-optimization skill to review this function and cProfile output. Focus on algorithmic complexity, repeated work, and Python-level loop overhead.”

For memory issues:

• “Use the python-performance-optimization skill to inspect this batch job. RSS climbs from 400MB to 3GB. Suggest likely retention causes, profiling steps, and memory-safe refactors.”

For I/O-heavy services:

• “Use the python-performance-optimization skill on this async API client. Requests are slow despite low CPU. Determine whether the bottleneck is blocking I/O, connection handling, serialization, or concurrency limits.”

What results to expect

Expect the skill to be strongest at:

• selecting the right profiling approach
• interpreting common performance patterns
• proposing plausible optimizations in ranked order
• explaining tradeoffs between caching, vectorization, parallelization, and code simplification

Expect weaker results if you provide no code, no workload shape, and no measurements.

python-performance-optimization skill FAQ

Is python-performance-optimization for Performance Optimization better than a normal prompt?

Usually yes, when you need structured diagnosis instead of ad hoc suggestions. A normal prompt often jumps straight to “use caching” or “use NumPy.” The python-performance-optimization skill is more likely to separate CPU, memory, I/O, and algorithmic issues first.

Is this skill beginner-friendly?

Yes, if you can share code and symptoms. You do not need to be a profiling expert to start. But beginners will get much better results if they provide concrete evidence and ask the agent to explain why a bottleneck matters before proposing fixes.

Do I need profiling output before using it?

No, but having it makes the python-performance-optimization usage much better. If you do not have measurements yet, ask the agent to tell you exactly what to profile and with which tool category.

When should I not use this skill?

Skip it when the issue is clearly outside Python application logic, such as:

• underprovisioned infrastructure
• network problems
• database server misconfiguration with no app-level evidence
• frontend latency unrelated to Python backend execution

In those cases, this skill can still help frame investigation, but it is not the right primary tool.

Does it cover memory as well as speed?

Yes. The repository explicitly covers memory profiling and memory optimization alongside CPU profiling and execution time analysis, which makes it more useful than “speed only” prompts.

Can it help with data workloads?

Yes, especially when the path to improvement may involve vectorization, batching, caching, or reducing Python loop overhead. The advanced reference is particularly relevant for numerical and data-processing code.

How to Improve python-performance-optimization skill

Give the skill benchmark evidence, not just source code

The single best way to improve python-performance-optimization results is to provide:

• before/after timings
• profiling summaries
• sample input sizes
• throughput or latency targets

With only source code, the agent can hypothesize. With measurements, it can prioritize.

Specify the bottleneck type you suspect

Even if you are unsure, say what you think the issue is:

• CPU-bound
• memory-bound
• database-bound
• network/I/O-bound
• startup-time problem
• batch throughput problem

This helps the skill choose the right diagnostic path and avoid generic advice.

Include realistic constraints

Optimization advice changes a lot based on constraints. State them directly:

• cannot change public API
• cannot add NumPy
• must remain readable for junior team
• must run on AWS Lambda
• must preserve deterministic ordering
• multi-tenant memory ceiling is fixed

These details improve decision quality more than asking for “best performance.”

Ask for ranked recommendations

A strong prompt asks the agent to rank suggestions by:

1. expected impact
2. implementation effort
3. correctness risk
4. dependency cost

That prevents the common failure mode where the first answer suggests sophisticated changes before simpler wins like reducing repeated work or fixing inefficient queries.

Watch for common failure modes

The python-performance-optimization skill can be weakened by:

• optimizing code that is not on the hot path
• using microbenchmarks that do not match production workloads
• overvaluing clever code over maintainable code
• applying multiprocessing where I/O or GIL behavior makes it a poor fit
• recommending caching without discussing invalidation or memory cost

Ask the agent to justify each optimization against the measured bottleneck.

Iterate after the first answer

A strong second-round prompt looks like:

• “Here is the updated code and new benchmark. The runtime dropped from 2.4s to 1.5s, but memory increased by 35%. Re-run the python-performance-optimization analysis and suggest the next best change with minimal memory growth.”

This turns the skill into an optimization loop rather than a one-shot rewrite.

Use repository-reading paths strategically

If the first answer stays generic, tell the agent to anchor its reasoning in:

• SKILL.md for profiling categories and workflow
• references/advanced-patterns.md for implementation options like vectorization, caching, memory management, parallelization, async I/O, and benchmarking

That usually raises the specificity of the output.

Ask for measurement plans when adoption is blocked

If your blocker is “we do not know how to start,” prompt for a minimal plan:

• what to measure first
• which profiler category fits
• where to place timers
• what workload to reproduce
• what success metric to use

This is often the highest-value use of the python-performance-optimization guide for teams early in the process.