gindachen/nsys-ai/commands

Command: nsys-ai skill

Manage and run builtin analysis skills against Nsight Systems profiles. Read `PRINCIPLES.md` first for rules, error handling, and tool definitions.

Subcommands

nsys-ai skill list

List all registered skills with name, category, and description. A name marked * cannot run without a parameter; the footer names the flag and where to look up which parameter. In --format json the same information is the required field on each entry in params.

nsys-ai skill list                   # human-readable table
nsys-ai skill list --format json     # JSON array (for programmatic use)

theoretical_flops *             kernels          Computes exact theoretical FLOPs ...
 
* needs a required parameter: nsys-ai skill run <name> <profile> -p KEY=VALUE (see: nsys-ai skill info <name>)

nsys-ai skill run

Execute a skill against a profile database.

nsys-ai skill run <skill_name> <profile.sqlite> [options]
 
# Examples:
nsys-ai skill run top_kernels profile.sqlite
nsys-ai skill run gpu_idle_gaps profile.sqlite --param min_gap_ns=5000000
nsys-ai skill run nccl_breakdown profile.sqlite --format json
nsys-ai skill run top_kernels profile.sqlite --trim 1.5 3.0   # seconds

Options:

• --format {text,json} — output format (default: text)
• --param KEY=VALUE — pass a parameter (repeatable, shorthand: -p)
• --trim START_S END_S — restrict analysis to time range (seconds, space-separated)
• --max-rows N — limit JSON output to at most N data rows (for token budget control). When clipping occurs, the JSON array contains up to N data rows plus a final truncation metadata object: {"_truncated": true, "_total_rows": <original>, "_shown_rows": <shown>}.
• --iteration N — auto-trim to the N-th training iteration (0-based). Cannot be combined with --trim. Requires NVTX markers (or falls back to heuristic kernel-gap detection).
• --marker TEXT — NVTX marker for iteration boundary detection (default: sample_0). Used with --iteration.

nsys-ai skill [--skills-dir <dir>] add <path.md>

Register a custom skill from a markdown file. Requires --skills-dir <dir> (before the subcommand) or the NSYS_AI_CUSTOM_SKILLS_DIR environment variable. The file must use heading-based format (not YAML frontmatter):

• # <name> — top-level heading with the skill name
• ## Description — short summary
• ## Category — e.g. kernels, memory, custom
• ## SQL — fenced ```sql code block with the query

See skills/SKILL_TEMPLATE.md for a complete example.

nsys-ai skill [--skills-dir <dir>] remove <name>

Unregister a previously added custom skill. Requires --skills-dir <dir> (before the subcommand) or the NSYS_AI_CUSTOM_SKILLS_DIR environment variable.

nsys-ai skill save

Export a skill definition to a markdown file.

nsys-ai skill save <name> -o <output.md>

Builtin Skills Catalog

The --trim flag is accepted for all skills, but only restricts the analysis window for skills whose SQL uses {trim_clause} or whose execute_fn explicitly reads trim_start_ns/trim_end_ns. Skills like theoretical_flops, speedup_estimator, and schema_inspect ignore it. Parameters marked required must be provided via --param.

Category: kernels

top_kernels Parameters

kernel_instances Parameters

kernel_launch_overhead Parameters

kernel_launch_pattern Parameters

stream_concurrency Parameters

gpu_idle_gaps Parameters

region_mfu Parameters

theoretical_flops Parameters

\* hidden_dim and seq_len must be > 0 for all operations except linear (which uses M/N/K instead). Passing 0 returns an INVALID_ARGUMENT error.

arithmetic_intensity Parameters

cutracer_analysis Parameters

Category: memory

memory_transfers and memory_bandwidth have no required parameters.

h2d_distribution Parameters

No required parameters. Supports --trim.

Category: communication

nccl_anomaly Parameters

overlap_breakdown Parameters

Category: nvtx