Perf Profile
Run a structured game performance profile against FPS, memory, and rendering budgets before you ship or tune a live build.
Overview
perf-profile is an agent skill most often used in Ship (also Operate) that profiles game code against performance budgets and ranks optimization fixes.
Install
npx skills add https://github.com/donchitos/claude-code-game-studios --skill perf-profileWhat is this skill?
- Scopes profiling to one named system or a full cross-system pass via the argument hint.
- Loads FPS, memory, load-time, draw-call, and multiplayer bandwidth budgets from design docs or CLAUDE.md.
- Targets hot-path CPU patterns: per-frame update loops, allocations, physics queries, and entity searches.
- Covers memory footprint, pooling vs instantiate-destroy, leaks, and cache eviction behavior.
- Adds rendering-oriented checks when applicable: draw calls and overdraw from overlapping geometry.
- Supports scoped (system name) or full cross-system profiling modes via the argument hint.
Adoption & trust: 1 installs on skills.sh; 21.2k GitHub stars; 3/3 security scanners passed (skills.sh audits); trending (+100% hot-view momentum).
What problem does it solve?
You suspect frame drops or memory creep but lack a repeatable way to measure hot paths against the budgets you already promised stakeholders.
Who is it for?
Indie game devs with an existing codebase who document frame and memory budgets in CLAUDE.md or design docs.
Skip if: Greenfield idea exploration with no runnable game loop, or teams that only need generic web Lighthouse audits.
When should I use this skill?
You need structured profiling with bottleneck identification, budget comparison, and prioritized optimization recommendations for a game codebase.
What do I get? / Deliverables
You get a scoped bottleneck inventory and prioritized optimization recommendations aligned to your documented FPS, memory, and rendering limits.
- Scoped profiling report with bottleneck list and priority-ranked optimization recommendations
- Measurements interpreted against stated performance budgets
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Canonical shelf is Ship because profiling is framed around launch readiness and budget compliance, not day-one ideation. Perf subphase matches frame-budget analysis, bottleneck ranking, and optimization recommendations tied to ship gates.
Where it fits
Run a full profile the week before a Steam Next Fest build to confirm 60 FPS on target hardware.
Profile a named combat system after a patch reports stutter on mid-tier GPUs.
Focus profiling on entity AI loops while core gameplay systems are still being extended.
How it compares
Use instead of one-off “make it faster” chat threads when you need game-specific CPU, memory, and draw-call profiling tied to budgets.
Common Questions / FAQ
Who is perf-profile for?
Solo and small-studio game builders using Claude Code who need analyst-style profiling across systems before ship or during live tuning.
When should I use perf-profile?
In Ship when validating perf before release; in Operate when diagnosing regressions after patches; in Build when a subsystem’s Update/Tick cost balloons mid-sprint.
Is perf-profile safe to install?
It requests Read, Glob, Grep, and Bash to inspect your repo—review the Security Audits panel on this page and restrict Bash if your environment requires it.
SKILL.md
READMESKILL.md - Perf Profile
## Phase 1: Determine Scope Read the argument: - System name → focus profiling on that specific system - `full` → run a comprehensive profile across all systems --- ## Phase 2: Load Performance Budgets Check for existing performance targets in design docs or CLAUDE.md: - Target FPS (e.g., 60fps = 16.67ms frame budget) - Memory budget (total and per-system) - Load time targets - Draw call budgets - Network bandwidth limits (if multiplayer) --- ## Phase 3: Analyze Codebase **CPU Profiling Targets:** - `_process()` / `Update()` / `Tick()` functions — list all and estimate cost - Nested loops over large collections - String operations in hot paths - Allocation patterns in per-frame code - Unoptimized search/sort over game entities - Expensive physics queries (raycasts, overlaps) every frame **Memory Profiling Targets:** - Large data structures and their growth patterns - Texture/asset memory footprint estimates - Object pool vs instantiate/destroy patterns - Leaked references (objects that should be freed but aren't) - Cache sizes and eviction policies **Rendering Targets (if applicable):** - Draw call estimates - Overdraw from overlapping transparent objects - Shader complexity - Unoptimized particle systems - Missing LODs or occlusion culling **I/O Targets:** - Save/load performance - Asset loading patterns (sync vs async) - Network message frequency and size --- ## Phase 4: Generate Profiling Report ```markdown ## Performance Profile: [System or Full] Generated: [Date] ### Performance Budgets | Metric | Budget | Estimated Current | Status | |--------|--------|-------------------|--------| | Frame time | [16.67ms] | [estimate] | [OK/WARNING/OVER] | | Memory | [target] | [estimate] | [OK/WARNING/OVER] | | Load time | [target] | [estimate] | [OK/WARNING/OVER] | | Draw calls | [target] | [estimate] | [OK/WARNING/OVER] | ### Hotspots Identified | # | Location | Issue | Estimated Impact | Fix Effort | |---|----------|-------|------------------|------------| ### Optimization Recommendations (Priority Order) 1. **[Title]** — [Description] - Location: [file:line] - Expected gain: [estimate] - Risk: [Low/Med/High] - Approach: [How to implement] ### Quick Wins (< 1 hour each) - [Simple optimization 1] ### Requires Investigation - [Area that needs actual runtime profiling to confirm impact] ``` Output the report with a summary: top 3 hotspots, estimated headroom vs budget, and recommended next action. --- ## Phase 5: Scope and Timeline Decision Activate this phase only if any hotspot has Fix Effort rated M or L. Present significant-effort items and ask the user to choose for each: - **A) Implement the optimization** (proceed with fix now or schedule it) - **B) Reduce feature scope** (run `/scope-check [feature]` to analyze trade-offs) - **C) Accept the performance hit and defer to Polish phase** (log as known issue) - **D) Escalate to technical-director for an architectural decision** (run `/architecture-decision`) If multiple items are deferred to Polish (choice C), record them under `### Deferred to Polish`. This skill is read-only — no files are written. Verdict: **COMPLETE** — performance profile generated. --- ## Phase 6: Next Steps - If bottlenecks require architectural change: run `/architecture-decision`. - If scope reduction is needed: run `/scope-check [feature]`. - To schedule optimizations: run `/sprint-plan update`. ### Rules - Never optimize without measuring first — gut feelings about performance are unreliable - Recommendations must include estimated impact — "make it faster" is not actionable - Profile on target hardware, not just development