Skip to content
Get packs

Guide · Agent skill

How to use the Nsight Graphics GPU Profiler agent skill

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

This guide explains how to install and use the cli-anything-nsight-graphics agent skill, which lets an AI agent drive NVIDIA Nsight Graphics through a command-line wrapper. It is aimed at graphics and game engine developers and performance engineers on Windows who want a first-pass GPU profile without clicking through the Nsight interface. By the end you will know how to install the skill, check your Nsight setup, ask the agent for a capture and read its summary.

Nsight Graphics GPU ProfilerHKUDS/CLI-Anything · Apache-2.0

Quick start

  1. 1Install Nsight Graphics. Install NVIDIA Nsight Graphics on a Windows host, since the skill only wraps that official tool.
  2. 2Install the CLI. Run pip install cli-anything-nsight-graphics in Python with pip available.
  3. 3Add the skill to your agent. Unzip the downloaded skill into ~/.claude/skills/ or a project's .claude/skills/, or upload it under Settings, Capabilities, Skills in the Claude apps.
  4. 4Check the setup. Ask the agent to run doctor info and doctor versions to confirm which Nsight install and mode it will use.
  5. 5Ask for a capture. Give the agent a launch target with --exe or a configured --project, then request a GPU Trace capture with auto-export and summary.
  6. 6Review the summary. Read the bottleneck hints, frame-budget classification and warnings the agent reports, and rerun with a narrower frame limit if needed.

What the skill makes the agent do

An agent skill is a folder with a SKILL.md file that tells an AI agent when and how to use a tool. This skill teaches the agent to operate NVIDIA Nsight Graphics, a professional GPU profiling tool, through the cli-anything-nsight-graphics command.

The skill is described as a Windows-first CLI harness. It wraps official Nsight Graphics activities rather than replacing them, so Nsight Graphics must already be installed.

  • Probe installed Nsight binaries and the compatibility mode
  • Launch an application detached under Nsight, or attach to a running process ID
  • Trigger a Graphics Capture or OpenGL Frame Debugger capture
  • Trigger a GPU Trace capture, auto-export it and summarize the results
  • Analyse existing .ngfx-capture files through ngfx-replay
  • Trigger Generate C++ Capture

How to install the Nsight Graphics agent skill

Download the skill ZIP from this page and unzip it. To make it available to Claude Code for all your projects, place the unzipped skill folder in ~/.claude/skills/. To make it available only inside one project, place it in that project's .claude/skills/ folder.

If you use the Claude apps instead, open Settings, go to Capabilities, then Skills, and upload the skill there.

The CLI itself is installed separately with pip. The skill's install line is shown below. If you work from a source checkout of the harness, the source notes say to reinstall from nsight-graphics/agent-harness with an editable install.

pip install cli-anything-nsight-graphics

Check your Nsight setup before capturing

Ask the agent to run the doctor commands first. The source says doctor info should be the first step, because it reveals the available compatibility mode. If several Nsight Graphics versions are installed, doctor versions lists them.

To force a specific install, pass --nsight-path pointing at the install directory or at ngfx.exe. The example path in the source is a host/windows-desktop-nomad-x64 folder inside an Nsight Graphics install.

  • Use --json for programmatic output the agent can parse
  • Use --nsight-path only when you need a specific install
cli-anything-nsight-graphics --json doctor info

Run a GPU Trace and get a one-step performance triage

For a quick first-pass performance review, the source recommends gpu-trace capture with --auto-export and --summarize. The summary covers exported table inventory, metric inventory, frame-budget classification, workload classification, throughput ranking, bottleneck hints, and warnings for empty event or regime tables.

Capture commands need a launch target, given with --exe or a preconfigured root-level --project. You can also summarize an existing folder of traces with gpu-trace summarize.

  • --start-after-ms sets when capture starts after launch
  • --limit-to-frames limits how many frames are traced
  • --output-dir sets where captures are written
cli-anything-nsight-graphics --output-dir D:\traces gpu-trace capture --exe "C:\Path\To\App.exe" --start-after-ms 1000 --limit-to-frames 1 --auto-export --summarize

Analyse an existing .ngfx-capture file

If you already have a Graphics Capture file, ask the agent to run replay analyze. With no analysis switches, it exports metadata, logs, captured log errors and a replay performance report, then adds structured highlights and warnings. The source states this uses official ngfx-replay outputs.

The source warns that .ngfx-gputrace inputs are accepted for diagnostics but may report an invalid file header on some Nsight versions. For GPU Trace tables, use gpu-trace summarize instead.

cli-anything-nsight-graphics --json replay analyze --capture-file D:\captures\frame.ngfx-capture --output-dir D:\analysis

Safety notes: scripts and network access

The skill is listed as running scripts and not using the network. Because it launches and attaches to real applications under Nsight, review what the agent is about to run, especially the path given to --exe and any attach PID.

The skill is not a shader, pipeline, texture or resource inspector. Do not expect it to replace RenderDoc-style debugging.

  • Confirm the --exe path points to the application you intend to profile
  • Check the PID before any attach command
  • Keep captures in a dedicated --output-dir

What people use it for

  • Asking the agent for a first-pass bottleneck triage of a Direct3D, Vulkan or OpenGL game build on Windows.
  • Capturing a single frame of an application after a set delay to check frame-budget classification.
  • Analysing a saved .ngfx-capture file and getting replay highlights and warnings without reopening the GUI.
  • Running repeatable Nsight capture workflows that an agent can repeat and report on.

Frequently asked questions

Is the Nsight Graphics agent skill free?

The skill is published under the Apache-2.0 licence, as stated in its source repository. The source does not cover the price or licence terms of NVIDIA Nsight Graphics itself, so check NVIDIA's own terms before relying on it.

What do I need to use the Nsight Graphics skill?

You need an installed NVIDIA Nsight Graphics, a Windows host is recommended, Python with pip, and a launch target given by --exe or a configured --project for capture commands. The skill cannot profile on its own without Nsight.

How do I install cli-anything-nsight-graphics?

Run pip install cli-anything-nsight-graphics. To use the skill with an agent, unzip the skill into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings, Capabilities, Skills in the Claude apps.

Does this skill work on macOS or Linux?

The skill is described as Windows-first and the source recommends a Windows host. Non-Windows use is not what it is designed for, so treat other platforms as unsupported by this source.

What is the difference between this skill and RenderDoc?

This skill runs official Nsight Graphics captures and summaries and analyses .ngfx-capture files with ngfx-replay. It does not provide RenderDoc-style shader, texture, pipeline or resource inspection.

Why does my .ngfx-gputrace file fail with an invalid file header?

The source says ngfx-replay documents its input as a Graphics Capture file, and .ngfx-gputrace files may report Invalid file header on some Nsight versions. Use gpu-trace summarize for exported GPU Trace table analysis 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 already work with NVIDIA Nsight Graphics on Windows and want an AI agent to run repeatable captures and give you a first-pass summary. Pick a different tool if you need shader, texture or pipeline inspection, or if you do not have Nsight Graphics installed.

Download the skill