Skip to content
Get packs

Guide · Agent skill

How to use the Performance Profile agent skill (perf-profile)

Updated · written with AI from the project's own documentation and checked against our catalogue data

Performance Profile is an agent skill for Claude that reviews a project for performance risks: likely bottlenecks, frame-time, memory and draw-call issues, and loading or network I/O costs. It is aimed at game developers who have their own performance budgets. This guide explains what the skill does, how to install it, how to trigger it with plain requests, and what it needs before it will produce useful output.

Performance ProfileDonchitos/Claude-Code-Game-Studios · MIT

Quick start

  1. 1Download and unzip. Download the ZIP from the skill page and unzip it into ~/.claude/skills/ for personal use or into your project's .claude/skills/ folder.
  2. 2Or upload in the apps. In the Claude apps, open Settings, go to Capabilities, then Skills, and upload the ZIP.
  3. 3Confirm the hooks folder. Check that hooks/yaml-helper.sh exists, since the skill calls it to read project settings.
  4. 4Set performance budgets. Add the performance keys to project.yaml, or record budgets in your design docs or CLAUDE.md.
  5. 5Ask for a profile. Request a system name or 'full' in plain language.
  6. 6Approve the write. When the agent asks permission, confirm that it may write the report to production/polish/.
  7. 7Review the ranked list. Check the hotspot table and NOT ASSESSED rows, then verify the top items with a real profiler.

What the Performance Profile skill makes the agent do

An agent skill is a folder containing a SKILL.md file with instructions that Claude follows when a task matches them. The perf-profile skill tells the agent to perform a performance review in a fixed order. First it checks whether there is enough real data to report on: profiler output, committed budgets, or code to analyze. If that data is missing, the agent says so and does not invent numbers.

When data exists, the agent looks through the code for likely slow spots. The skill's target list includes per-frame update functions such as _process(), Update() and Tick(), allocation patterns in per-frame code, expensive physics queries every frame, large data structures, object pool versus instantiate/destroy patterns, draw call estimates, overdraw, shader complexity, save/load performance, and asynchronous versus synchronous asset loading.

The result is a report with a budget table and a hotspot table. Each budget row is marked OK, WARNING, OVER or NOT ASSESSED. Before writing the file, the agent asks your permission.

Install the Performance Profile skill

You can install the skill in one of three places. For a personal setup available across your projects, download the ZIP from the skill page and unzip it into ~/.claude/skills/. For a single project, unzip it into that project's .claude/skills/ folder. You can also upload the ZIP in the Claude apps under Settings, then Capabilities, then Skills.

The package contains SKILL.md. The skill's instructions call a helper script at hooks/yaml-helper.sh, so the skill is designed to run inside Claude Code alongside the Claude Code Game Studios hooks folder. Confirm that folder is present before you rely on the skill.

  • Personal install: ~/.claude/skills/
  • Project install: .claude/skills/ inside your project
  • App install: Settings, then Capabilities, then Skills, then upload the ZIP

Set up budgets so the skill has something to measure against

The skill reads performance budgets from project.yaml first. The keys it looks for are performance.target_framerate, performance.frame_budget_ms, performance.draw_call_limit and performance.memory_ceiling_mb. If a key is empty, that budget counts as not set. The skill then falls back to your design docs or CLAUDE.md for anything config does not provide, such as load time targets or per-system memory budgets.

A metric with no committed budget is reported as NOT ASSESSED, not as a pass. This is deliberate, because reporting headroom against a number nobody chose would be misleading.

  • performance.enforce sets what a violation means: warn (default), block or off
  • block marks violations as release-stopping and the report says so
  • Unrecognized values fall back to warn
bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" get_effective_yaml_key performance.frame_budget_ms

Trigger the skill with natural requests

The skill takes one argument: a system name or 'full'. A system name focuses the profile on that system, and 'full' runs a comprehensive profile across all systems. You can phrase requests in plain language, and the agent will match them to the skill's description.

Name the scope clearly so the agent knows what to profile. If you want the report kept for later comparison, say so; the agent will ask before writing it.

  • Profile the combat system for frame-time risks against our budgets.
  • Run a full performance profile and tell me which budgets are not assessed.
  • Find per-frame allocations in the inventory system and rank the fixes.
  • Check whether the level loading path is sync or async and what it costs.

Read and use the report

Reports are written to production/polish/ using the pattern [scope]-report-[date].md. The skill creates the directory if it does not exist. That is the same folder used by /team-polish, so profiles from either route sit together and can be compared across runs.

Treat the numbers as estimates. The skill reads files and code and does not run a real profiler, so its findings are inferences. Confirm the top-ranked hotspots with your own profiler before you change code. Keep NOT ASSESSED sections in the file: they show what was not measured.

What people use it for

  • Reviewing per-frame update functions in a game for CPU cost before a milestone build.
  • Checking a project against its own frame budget, memory ceiling and draw call limit.
  • Comparing profile reports across runs by keeping them in production/polish/.
  • Finding allocation and asset-loading patterns that cause hitches during play.

Frequently asked questions

Is the Performance Profile skill free to use?

The skill is published under the MIT licence, which is stated on the source repository page. Check the licence file in the repository for the full terms before redistributing it.

What do I need to run the perf-profile skill?

You need Claude Code with the Claude Code Game Studios hooks folder present, specifically hooks/yaml-helper.sh. A project.yaml with performance budget keys is optional, and the skill falls back to design docs or CLAUDE.md if it is missing.

Why does the skill say NOT ASSESSED instead of giving a result?

The skill only reports what the data supports. If profiler output, budgets or code are missing, it marks the section NOT ASSESSED rather than estimating a pass. This prevents false clean results.

Does the skill run a real profiler?

No. It reads files and code and estimates likely bottlenecks. Its findings are inferences, so confirm important results with a real profiler.

Does the skill need internet access?

The skill's listed requirements say it does not use the network. It does run a helper script through Bash, and that script is limited to reading config values.

Can I use this skill for non-game software?

The skill is designed for game projects and budgets such as frame time and draw calls. For non-game software or live profiling, use a dedicated profiler instead.

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

Use this skill if you are a game developer who wants a structured review of frame-time, memory and draw-call risks against your own budgets, especially if you use the Claude Code Game Studios setup. Skip it if your project has no budgets or profiler data, since it will mostly return NOT ASSESSED, or if you need live measurements from a real profiler.

Download the skill