Guide · Agent skill
How to use the System Profiler agent skill (system-profile)
Updated · written with AI from the project's own documentation and checked against our catalogue data
The system-profile skill is an agent skill that tells an AI coding agent how to profile a target such as a Python script, a running process, GPU or memory use, or a multi-GPU link, and then report what it found. It is aimed at engineers chasing slow training jobs or inference servers and at researchers who want to see GPU, memory and inter-GPU costs before scaling up. By the end of this guide you will know what the skill does, how to install it, how to phrase a request so it triggers, and what to check before accepting its code changes.
System Profilerwanshuiyin/Auto-claude-code-research-in-sleep · MIT Download the skill Quick start
- 1Download the ZIP. Download the system-profile ZIP from this page and unzip it so the folder contains SKILL.md.
- 2Choose an install location. Place the folder in ~/.claude/skills/ for all projects, or in .claude/skills/ inside one project.
- 3Or upload in the Claude apps. In the Claude apps, open Settings, go to Capabilities, and upload the skill under Skills.
- 4Name your target. Tell the agent what to profile, such as train.py, a process ID, or the GPU.
- 5Use a trigger phrase. Include words like profile, benchmark or bottleneck so the skill is selected.
- 6Review the results. Read the Part A tables and ranked recommendations, saved outputs are in ./profile_output/.
- 7Review the changelog. Check the Part B changelog for every modified or created file and revert or clean up as needed.
What is an agent skill, and what does system-profile make the agent do?
An agent skill is a folder containing a SKILL.md file with instructions that an AI agent loads when a request matches the skill's description. The skill changes how the agent approaches a task, rather than adding a separate app.
The system-profile skill tells the agent to act as a profiling assistant. It parses your target, chooses measurement methods, runs them, saves artifacts to a profile_output folder, and produces a report with structured tables and recommendations ranked by expected impact.
- Choose external tools such as cProfile, py-spy, memray, nvidia-smi, torch.profiler or nsys, checking which are available first.
- Write small instrumentation code into the target when external tools are not enough, such as timing code blocks or wrapping NCCL collectives.
- Investigate CPU overhead, memory overhead (allocated vs reserved vs peak), interconnect and communication, and GPU compute.
- List every file it modified or created for profiling so you can review or revert the changes.
Install the system-profile skill
Download the ZIP for this skill from this page and unzip it. The skill folder contains SKILL.md. Place the unzipped folder in one of these locations: ~/.claude/skills/ to make it available across your projects, or .claude/skills/ inside a specific project to limit it to that project.
If you use the Claude apps instead, open Settings, go to Capabilities, and upload the skill under Skills.
- Personal install: ~/.claude/skills/
- Project install: .claude/skills/ inside your project folder
- Claude apps: Settings → Capabilities → Skills, then upload
How do you trigger the skill with a natural request?
The skill's description tells the agent to use it when you say things like "profile", "benchmark", "bottleneck", or ask for performance analysis. You do not need a special command. Name the target clearly so the agent knows what to measure.
The skill also accepts a target argument. Examples given in the skill include "train.py", "gpu", "pid 1234" and "vllm serving". If you give no target, or an unclear one, the agent is instructed to ask you.
- "Profile train.py and tell me where the time goes."
- "Benchmark the data loader in dataset.py."
- "Find the bottleneck in the process with pid 1234."
- "Profile the GPU memory use of my training run."
- "Check the interconnect cost of my multi-GPU setup before I scale up."
What does a profiling run look like, step by step?
The skill defines a fixed workflow. The agent first determines the target, then chooses methods, then checks available tools and hardware topology, runs the measurements and saves outputs. Finally it writes a report in two parts.
Part A holds the results: tables for CPU overhead, memory overhead with a redundancy column, interconnect transfers (type, frequency, size, latency, bandwidth), hotspots, and recommendations ranked by impact. Part B is an instrumentation changelog that lists each changed file, the change type, what was added or modified, and the line numbers.
- Output folder: ./profile_output/ for flamegraphs, traces and logs.
- The changelog is mandatory and uses the columns File, Change type, What was added/modified, Line(s).
- When you are finished, the agent offers to remove all instrumentation.
What does the skill need and what should you check for safety?
The skill needs Python and common profiling tools such as cProfile, py-spy or memray where available. GPU profiling needs nvidia-smi and CUDA tooling, though these are optional depending on the target. The skill runs scripts and does not use the network.
The skill explicitly allows inline edits to your source code. Its guidelines prefer wrapping over inline edits and ask the agent to mark any inline change with a # [PROFILE] comment, but you should still review the changelog. Keep the target away from live production traffic, because profilers and inserted instrumentation can disrupt serving or change timing.
- Requires: Python, plus cProfile, py-spy or memray where available; nvidia-smi and CUDA tooling for GPU work.
- Runs scripts: yes. Uses network: no.
- Review the Part B changelog and revert or ask for cleanup before committing code.
- Do not use it on production systems where instrumentation could affect live traffic.
Tips for getting useful results
Give the agent a specific target and a question. "Why is the data loader slow" produces a more focused run than "profile everything". For large frameworks, the skill profiles end-to-end execution and looks for bottlenecks across components.
For a quick single check, one tool command may be enough. The skill adds a full workflow with code edits, so it is more than you need for a one-line question.
- Name the file, process ID or service so the agent does not have to guess.
- Ask for focused runs (for example "gpu" or "memory") if you only care about one dimension.
- Keep a clean git state so the changelog is easy to review and revert.
What people use it for
- Finding why a training job's data loader or CPU side is slower than the GPU work.
- Checking GPU memory allocated, reserved and peak use, including CPU and GPU copies of the same data.
- Measuring CPU-GPU and GPU-GPU transfer volume and NCCL collective latency before scaling to more GPUs.
- Getting a ranked list of bottlenecks for an inference server such as vllm serving.
- Profiling a running process by PID to see where its CPU time goes.
Frequently asked questions
How do I install the system-profile agent skill?
Download the ZIP from this page and unzip it so SKILL.md is in a system-profile folder. Put it in ~/.claude/skills/ for all projects or .claude/skills/ inside one project. In the Claude apps, you can instead upload it under Settings → Capabilities → Skills.
What do I need to run system-profile?
You need Python and common profiling tools such as cProfile, py-spy or memray where available. GPU profiling also needs nvidia-smi and CUDA tooling, but these depend on your target. The skill runs scripts and does not use the network.
Is system-profile free to use?
The item is listed under the MIT licence. The source material does not describe pricing, so check the licence text on the repository for the terms.
Will the skill change my code?
Yes, when it needs to. The skill allows inline edits and writes instrumentation code, marking inline changes with # [PROFILE] comments. Every changed or created file is listed in the Part B changelog so you can review or remove those changes.
Can I use it on a production system?
The skill's own guidance warns against it. Running profilers or inserting instrumentation can disrupt live traffic or change timing behaviour, so use it on a copy or a test environment instead.
What should I use instead for a quick check?
For a one-line question, a single tool command such as nvidia-smi or cProfile may be enough. The skill adds a full workflow with code edits, so it suits deeper investigations rather than quick checks.
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 system-profile if you want an agent to run a structured bottleneck investigation across CPU, memory, GPU and interconnect, and you are comfortable reviewing its code changes. Pick a plain profiling tool or a single command instead if you only need a quick measurement, or if the agent must not edit source files or touch live systems.
Download the skill