perf-optimize
Skill157 starsChanged 32 days agoMITView on GitHub
Runs profile-driven performance optimization using multi-dimensional parallel analysis and sequential TDD fixes. User-invoked entry point via /perf-optimize; not for autonomous or subagent use.
- Deletes or force-pushes
1 other project uses a version of this.
Adopted by
Most recently taken up by
- NVIDIA/TensorRT-LLMtheir own version, first seen Oct 13, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- NVIDIA/TensorRT-LLM★ 15ksame name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository68 other files it gives its agents.
- github-pages/agents.mdAGENTS.md
- adrSkill
- agent-protocolsSkill
- angular-idiomsSkill
- api-documentationSkill
- auditSkill
- axum-idiomsSkill
- browser-automationSkill
- bugfixSkill
- chaos-testingSkill
- ci-cdSkill
- cli-developmentSkill
- code-reviewSkill
- cpp-idiomsSkill
- csharp-idiomsSkill
- data-engineeringSkill
- debugging-protocolSkill
- django-idiomsSkill
- dotnet-idiomsSkill
- elixir-idiomsSkill
- embedded-systemsSkill
- feature-flagsSkill
- flutter-idiomsSkill
- frontend-designSkill
- git-commit-integritySkill
- go-idiomsSkill
- guardrailsSkill
- hono-idiomsSkill
- incident-responseSkill
- java-idiomsSkill
- javascript-idiomsSkill
- kotlin-idiomsSkill
- laravel-idiomsSkill
- logging-implementationSkill
- ml-engineeringSkill
- mobile-designSkill
- mobile-testingSkill
- nextjs-idiomsSkill
- parallel-dispatchSkill
- payment-integrationSkill
- perf-optimizationSkill
- php-idiomsSkill
- postgres-idiomsSkill
- python-idiomsSkill
- rails-idiomsSkill
- react-idiomsSkill
- refactoring-patternsSkill
- refactorSkill
- research-methodologySkill
- ruby-idiomsSkill
- rust-idiomsSkill
- security-auditSkill
- sequential-thinkingSkill
- spring-boot-idiomsSkill
- sql-idiomsSkill
- structured-specSkill
- supply-chain-securitySkill
- swift-idiomsSkill
- testability-patternsSkill
- test-e2eSkill
- The first 60 shown.
The file
Show its rules and text
We split this skill into the rules it gives an agent
21 rules. About 0 are common, 10 are distinctive, and 11 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈10
Distinctive · estimate
This author's own choices. Worth a look.
11
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 14
Skill prerequisite: Read .agents/skills/perf-optimization/SKILL.md before starting.
- Distinctive: line 23
After deploying a new feature that touches a hot path
- Distinctive: line 35
Before starting, you MUST:
- Distinctive: line 44
Before collecting profiles, understand the codebase structure and performance context.
- Very specific: line 85
Use the language-appropriate extraction script (e.g., scripts/go-pprof.sh cpu profile.prof)
- Very specific: line 88
Run the extraction script in bench mode to generate AND analyze profiles in one step:
- Very specific: line 105
Use invoke_subagent to spawn all activated dimension agents in a single call.
- Very specific: line 120
When all subagents message findings ready, proceed to Phase 3.
- Very specific: line 127
Read all .agentwork/findings-perf-*.md files from Phase 2.
- Distinctive: line 140
When findings from 2+ dimensions converge on the same function or module, escalate severity by one level (MEDIUM → HIGH, HIGH → CRITICAL):
- Distinctive: line 148
Create an implementation plan ranking fixes:
- Distinctive: line 157
Rule: If a fix requires more than 1 day AND saves < 20% on the hot path, defer it.
- Very specific: line 161
Create docs/audits/ if it doesn't exist
- Very specific: line 162
Read the report template from perf-optimization skill → references/perf-report-template.md
- Distinctive: line 203
After all fixes are applied:
- Very specific: line 204
Run the full benchmark suite with -count=3 minimum
- Very specific: line 206
Run the complete test suite with -race or equivalent
- Distinctive: line 207
Run all quality checks (formatter, linter, security scanner, build)
- Very specific: line 214
Update the analysis document at docs/audits/perf-analysis-{component}-{YYYY-MM-DD}-{HHmm}.md with:
- Distinctive: line 233
After analysis produces findings, choose the right workflow based on finding type:
- Distinctive: line 244
When starting a fix workflow in a new conversation, reference the persisted report:
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Performance Optimization Skill
Entry-point guard: This is a user-invoked command skill (
/perf-optimize). If you are a spawned subagent, do NOT execute this skill — return to your assigned scope card.
Trigger: User provides profiling data, asks to optimize performance, or benchmarks show regression.
Skill prerequisite: Read .agents/skills/perf-optimization/SKILL.md before starting.
Purpose
Profile-driven performance optimization using multi-dimensional parallel analysis. Dispatches subagents across orthogonal performance dimensions to analyze profiling data and scan code, then implements fixes sequentially with TDD and isolated benchmarks.
When to Use
- User provides profiling data (pprof, flamegraph, py-spy, Chrome DevTools)
- User asks to optimize performance of a specific component
- A benchmark regression is detected
- After deploying a new feature that touches a hot path
When NOT to Use
- General code quality review →
/audit - Security vulnerability scan →
/security-audit - Architectural restructuring →
/refactor - Fixing known bugs →
/bugfix
Prerequisite Skill
Load: perf-optimization skill (.agents/skills/perf-optimization/SKILL.md) — contains methodology, optimization pattern catalog, language modules, and orchestration references.
Pre-Optimization Checklist
Before starting, you MUST:
- Load the skill — read
.agents/skills/perf-optimization/SKILL.md - Load the language module — read
.agents/skills/perf-optimization/languages/{language}.md - Identify optimization scope — determine which component, module, or benchmark to optimize
Phase 0: Reconnaissance
Before collecting profiles, understand the codebase structure and performance context.
0.1 — Stack & Architecture Detection
Scan for language/framework/infrastructure markers:
- Languages:
go.mod,package.json,Cargo.toml,pyproject.toml,pom.xml,*.csproj,Gemfile,composer.json - Frameworks: HTTP frameworks, ORMs, async runtimes, concurrency primitives
- Build tooling: Bundlers, Docker, CI/CD pipeline configuration
0.2 — Performance Inventory
Map performance-relevant components within the optimization scope:
- Hot-path entry points (API endpoints, request handlers, critical loops)
- Database access patterns (ORM, raw queries, connection pooling)
- External service integrations (HTTP clients, message queues, caches)
- Concurrency primitives (goroutines, threads, async/await, channels, locks)
- Serialization points (JSON, protobuf, XML parsing/generation)
- Build/bundle outputs (JS bundles, Docker images, compiled binaries)
- Existing benchmark suite (location, coverage, baseline numbers)
0.3 — Dimension Selection
Activate the applicable dimensions for the codebase under optimization. State your selection explicitly:
| Dim | Scope | Activate When |
| A | CPU & Computation | Always |
| B | Memory & Allocation | Always |
| C | I/O & Network | Project has database, HTTP clients, or file I/O |
| D | Concurrency & Parallelism | Project uses goroutines, threads, async/await, or locks |
| E | Serialization & Data Structures | Project serializes data or uses complex data structures in hot paths |
| F | Build, Bundle & Deployment | Project has frontend bundles, Docker images, or deployable artifacts |
State your selection:
"Activating dimensions: A, B, C, D, E. Skipping F (no frontend bundles or Docker)."
Phase 1: Profile
Collect profiling data using the language-appropriate tool. This step is performed by the coordinator.
If the user provides a profile file or URL:
- Use the language-appropriate extraction script (e.g.,
scripts/go-pprof.sh cpu profile.prof)
If the user asks to profile from scratch:
- Run the extraction script in
benchmode to generate AND analyze profiles in one step:
bash .agents/skills/perf-optimization/scripts/go-pprof.sh bench ./path/to/package/... BenchmarkNameOutput: Raw profiling data (CPU profile, heap profile, mutex/block profile, trace) + extracted summary.
Establish baseline: Record the benchmark baseline numbers (ns/op, B/op, allocs/op) that all subsequent measurements will compare against.
Phase 2: Multi-Dimensional Analysis
Dispatch parallel subagents — one per activated dimension. Each analyzes the profiling data and scans the codebase within its dimension scope independently.
Dispatch Protocol
Use invoke_subagent to spawn all activated dimension agents in a single call.
Per-dimension fields:
- TypeName:
self(universal spawn mechanism — ensures subagents inherit full toolsets peragent-protocols§3) - Role:
Performance Analyst — Dimension {KEY}(e.g.,Performance Analyst — Dimension A) - Workspace:
inherit - Prompt: Build from the system prompt template in
perf-optimizationskill →references/perf-dimensions.md. Fill in: dimension name, scope card, reconnaissance context from Phase 0, and profiling data from Phase 1.
Each subagent receives in its prompt:
- Dimension scope card — from
references/perf-dimensions.md - Reconnaissance context — stack + performance inventory from Phase 0
- Profiling data — summary or file path from Phase 1
- Language module — path to the relevant
languages/{lang}.md - Output target —
.agentwork/findings-perf-{dimension-key}.md
When all subagents message findings ready, proceed to Phase 3.
Phase 3: Synthesis & Prioritization
3.1 — Collect
Read all .agentwork/findings-perf-*.md files from Phase 2.
3.2 — Deduplicate
Consolidate findings reported by multiple dimensions (same root cause, same function). Note which dimensions flagged each.
3.3 — Severity Ranking
Classify all findings using the performance-specific 4-level taxonomy:
- CRITICAL — Algorithmic complexity causing non-linear degradation, memory leaks, unbounded resource consumption
- HIGH — Significant measurable waste in hot paths, missing caching, sequential I/O that could be concurrent
- MEDIUM — Moderate waste, suboptimal data structures, missing pre-allocation
- LOW — Minor micro-optimizations below noise floor
3.4 — Cross-Dimension Correlation
When findings from 2+ dimensions converge on the same function or module, escalate severity by one level (MEDIUM → HIGH, HIGH → CRITICAL):
- High allocations (B) + lock held across allocating path (D) → escalate both
- Sequential I/O (C) + redundant serialization per call (E) → escalate to HIGH
- O(n²) algorithm (A) + heap allocation per iteration (B) → escalate to CRITICAL
- Unoptimized bundle (F) + repeated serialization of static data (E) → escalate
3.5 — Prioritize by Impact/Risk
Create an implementation plan ranking fixes:
| Priority | Criteria |
| Do first | Low risk, high impact (caching, pre-allocation, fast-reject) |
| Do second | Medium risk, high impact (library swap, algorithm change) |
| Do last | High risk, high impact (major refactor, custom implementation) |
| Skip | Any risk, low impact (micro-optimization below noise floor) |
Rule: If a fix requires more than 1 day AND saves < 20% on the hot path, defer it.
3.6 — Write Analysis Report
- Create
docs/audits/if it doesn't exist - Read the report template from
perf-optimizationskill →references/perf-report-template.md - Fill all sections with Phase 2–3 findings (leave "Implementation Results" section empty for now)
- Write to
docs/audits/perf-analysis-{component}-{YYYY-MM-DD}-{HHmm}.md
Present the implementation plan to the user for approval before proceeding to Phase 4.
Zero-Findings Guard: If the analysis produces fewer than 3 findings across all dimensions, you MUST complete the "Dimensions Covered" attestation section to prove comprehensive coverage was not skipped.
Phase 4: Implement (one fix at a time)
Requires user approval from Phase 3 before starting.
For each fix, in priority order:
- Write tests first (TDD Red → Green)
- Implement the fix
- Add
PERF:comments — annotate each optimization with an inline comment explaining the rationale (what the profiler showed and why the new approach is faster) - Run all existing tests (
go test -race ./...or equivalent) - Benchmark immediately — compare ns/op, B/op, allocs/op against baseline
- Run quality checks (formatter, linter, security scanner)
- Commit independently with conventional format:
perf(scope): one-line description
What: <the optimization implemented>
Why: <what the profiler showed — the performance problem it solves>
Impact: <expected improvement, e.g., "Eliminates ~500 allocations per request">
Measurement: <how to verify, e.g., "Run BenchmarkX, compare allocs/op">Rule: One fix per commit. Never batch optimizations.
Size guidance: Each fix should be focused and minimal. If a fix requires > ~100 lines or touches > 3 files, it's likely a refactor — use the /refactor skill instead.
Phase 5: Final Verification
After all fixes are applied:
- Run the full benchmark suite with
-count=3minimum - Compare against the original baseline (before any fixes)
- Run the complete test suite with
-raceor equivalent - Run all quality checks (formatter, linter, security scanner, build)
Phase 6: Document & Ship
6.1 — Update the Analysis Report
Update the analysis document at docs/audits/perf-analysis-{component}-{YYYY-MM-DD}-{HHmm}.md with:
- Before/after benchmark comparison table
- Optimizations applied — commit SHA + measured improvement per fix
- Optimizations skipped — ID + reason
- Failed optimizations — For each optimization tried but didn't improve: (1) what was tried, (2) expected gain, (3) actual result, (4) why it didn't work. Prevents future sessions from repeating failed experiments.
- Surprising findings — Unexpected profiler results revealing codebase-specific characteristics
- Remaining opportunities — Deferred optimizations for future sessions
- Verification suite results — benchmark, tests, quality checks
6.2 — Ship
Present the final results to the user with:
- Cumulative benchmark improvement table
- List of commits
- Any follow-up items
Feedback Loop
After analysis produces findings, choose the right workflow based on finding type:
| Finding Type | Example | Workflow |
| CRITICAL perf issue | O(n²) in hot path, memory leak | Implement in Phase 4 of this skill |
| Requires architectural refactor | Swap sync for async pipeline, restructure data flow | /refactor — separate session |
| Security concern from optimization | Wants to disable validation for speed | REJECTED — security is non-negotiable |
| Code quality issue discovered | Dead code, pattern inconsistency found during analysis | /audit or /bugfix — separate session |
| Build/bundle optimization | Code splitting, Docker layer caching | Implement in Phase 4 if < 100 lines, else /workflow-solo |
Using Findings in Other Contexts
When starting a fix workflow in a new conversation, reference the persisted report:
"Implement the remaining optimization opportunities in
docs/audits/perf-analysis-auth-2026-06-29-1430.md"
The agent in the new context can read the file directly from the repo.
Quick Reference
| Phase | Agent | Output | Gate |
| 0. Reconnaissance | Coordinator | Stack + inventory + dimension selection | Dimensions selected |
| 1. Profile | Coordinator | Raw profiling data + baseline benchmarks | Data collected |
| 2. Multi-Dim Analysis | Parallel subagents | .agentwork/findings-perf-*.md per dimension | All subagents report findings ready |
| 3. Synthesis | Coordinator | docs/audits/perf-analysis-{component}-{date}.md + implementation plan | User approved |
| 4. Implement | Coordinator | Tests + code + PERF: comments + benchmark per fix | Each fix passes tests + improves benchmark |
| 5. Verify | Coordinator | Full benchmark comparison + test suite | All checks pass |
| 6. Document & Ship | Coordinator | Updated report + conventional commits | User notified |
Completion Criteria
- Pre-Optimization Checklist completed (skill loaded, language module loaded, scope set)
- Reconnaissance completed (stack detected, inventory mapped, dimensions selected)
- Profiling data collected and baseline established
- All activated dimensions analyzed by parallel subagents
- Findings synthesized, deduplicated, and severity-ranked
- Cross-dimension correlations identified and severity escalated
- Analysis report saved to
docs/audits/with implementation plan - User approved implementation plan
- Each fix implemented with TDD, benchmarked, and committed independently
- Final verification passed (benchmarks, tests, quality checks)
- Analysis report updated with implementation results
.agentwork/directory cleaned up (rm -rf .agentwork/)
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

